バージョン:

Using OpenTelemetry Logging

This guide explains how your Quarkus application can utilize OpenTelemetry (OTel) to provide distributed logging for interactive web applications.

この技術は、previewと考えられています。

preview では、下位互換性やエコシステムでの存在は保証されていません。具体的な改善には設定や API の変更が必要になるかもしれませんが、 stable になるための計画は現在進行中です。フィードバックはメーリングリストや GitHub の課題管理で受け付けています。

とりうるステータスの完全なリストについては、 FAQの項目を参照してください。

OpenTelemetry Logging is considered tech preview and is disabled by default.
The OpenTelemetry Guide is available with signal independent information about the OpenTelemetry extension.

前提条件

このガイドを完成させるには、以下が必要です:

約15分
IDE
JDK 17+がインストールされ、 JAVA_HOME が適切に設定されていること
Apache Maven 3.9.9
Docker と Docker Compose、または Podman 、および Docker Compose
使用したい場合は、 Quarkus CLI
ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM（あるいはネイティブなコンテナビルドを使用する場合はDocker）をインストールし、適切に設定していること

アーキテクチャ

In this guide, we create a straightforward REST application to demonstrate distributed logging, similar to the other OpenTelemetry guides.

ソリューション

次の章で紹介する手順に沿って、ステップを踏んでアプリを作成することをお勧めします。ただし、すぐに完成した例に飛んでも構いません。

Git リポジトリーのクローンを作成: git clonehttps://github.com/quarkusio/quarkus-quickstarts.git、またはアーカイブをダウンロードします。

ソリューションは opentelemetry-quickstart ディレクトリにあります。

Mavenプロジェクトの作成

まず、新しいプロジェクトが必要です。以下のコマンドで新規プロジェクトを作成します。

コマンドラインインタフェース

quarkus create app org.acme:opentelemetry-quickstart \
    --extension='rest,quarkus-opentelemetry' \
    --no-code
cd opentelemetry-quickstart

Gradleプロジェクトを作成するには、 --gradle または --gradle-kotlin-dsl オプションを追加します。

Quarkus CLIのインストールと使用方法の詳細については、 Quarkus CLI ガイドを参照してください。

Maven

mvn io.quarkus.platform:quarkus-maven-plugin:3.17.4:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=opentelemetry-quickstart \
    -Dextensions='rest,quarkus-opentelemetry' \
    -DnoCode
cd opentelemetry-quickstart

Gradleプロジェクトを作成するには、 -DbuildTool=gradle または -DbuildTool=gradle-kotlin-dsl オプションを追加します。

Windowsユーザーの場合:

cmdを使用する場合、（バックスラッシュ \ を使用せず、すべてを同じ行に書かないでください）。
Powershellを使用する場合は、 -D パラメータを二重引用符で囲んでください。例: "-DprojectArtifactId=opentelemetry-quickstart"

このコマンドはMavenプロジェクトを生成し、quarkus-opentelemetry エクステンションをインポートします。このエクステンションには、デフォルトのOpenTelemetryサポートと、https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/otlp.md[OTLP]のgRPC spanエクスポーターが含まれています。

Quarkusプロジェクトがすでに設定されている場合、プロジェクトのベースディレクトリで次のコマンドを実行することで、quarkus-opentelemetry エクステンションをプロジェクトに追加できます：

コマンドラインインタフェース

quarkus extension add opentelemetry

Maven

./mvnw quarkus:add-extension -Dextensions='opentelemetry'

Gradle

./gradlew addExtension --extensions='opentelemetry'

これにより、以下がビルドファイルに追加されます。

pom.xml

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-opentelemetry</artifactId>
</dependency>

build.gradle

implementation("io.quarkus:quarkus-opentelemetry")

Jakarta REST リソースの調査

src/main/java/org/acme/opentelemetry/TracedResource.java のファイルを開くと、以下の内容が表示されます。

package org.acme.opentelemetry;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import org.jboss.logging.Logger;

@Path("/hello")
public class TracedResource {

    private static final Logger LOG = Logger.getLogger(TracedResource.class);

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        LOG.info("hello");
        return "hello";
    }
}

If you have followed the tracing guide, this class will seem familiar. The main difference is that now, the hello message logged with org.jboss.logging.Logger will end up in the OpenTelemetry logs.

コンフィグレーションの作成

The only mandatory configuration for OpenTelemetry Logging is the one enabling it:

quarkus.otel.logs.enabled=true

To change any of the default property values, here is an example on how to configure the default OTLP gRPC Exporter within the application, using the src/main/resources/application.properties file:

quarkus.application.name=myservice (1)
quarkus.otel.logs.enabled=true (2)
quarkus.otel.exporter.otlp.logs.endpoint=http://localhost:4317 (3)
quarkus.otel.exporter.otlp.logs.headers=authorization=Bearer my_secret (4)

1	All logs created from the application will include an OpenTelemetry `Resource` indicating the logs were created by the `myservice` application. If not set, it will default to the artifact id.
2	Enable the OpenTelemetry logging. Must be set at build time.
3	gRPC endpoint to send the logs. If not set, it will default to `http://localhost:4317`.
4	Optional gRPC headers commonly used for authentication.

To configure the connection using the same properties for all signals, please check the base configuration section of the OpenTelemetry guide.

アプリケーションの実行

First we need to start a system to visualise the OpenTelemetry data. We have 2 options:

Start an all-in-one Grafana OTel LGTM system for traces, metrics and logs.

See the data

Grafana OTel LGTM option

Take a look at: Getting Started with Grafana-OTel-LGTM.

This features a Quarkus Dev service including a Grafana for visualizing data, Loki to store logs, Tempo to store traces and Prometheus to store metrics. Also provides and OTel collector to receive the data.

Logging exporter

You can output all logs to the console by setting the exporter to logging in the application.properties file:

quarkus.otel.logs.exporter=logging (1)

1	Set the exporter to `logging`. Normally you don’t need to set this. The default is `cdi`.

Also add this dependency to your project:

<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-logging</artifactId>
</dependency>

OpenTelemetry 設定リファレンス

See the main OpenTelemetry Guide configuration reference.

前提条件
アーキテクチャ
ソリューション
Mavenプロジェクトの作成
- Jakarta REST リソースの調査
- コンフィグレーションの作成
アプリケーションの実行
- See the data
OpenTelemetry 設定リファレンス