バージョン:

OpenTelemetry Loggingの使用

This guide explains how your Quarkus application can utilize OpenTelemetry (OTel) to provide structured, contextual, vendor-neutral and centralised logging for interactive web applications.

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

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

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

このドキュメントは、このコンポーネントとその他のオブザーバビリティ関連コンポーネントを特集した Quarkus のオブザーバビリティリファレンスガイドの一部です。

OpenTelemetry Logging は tech preview とみなされ、デフォルトでは無効になっています。
OpenTelemetry ガイドには、信号に依存しない、OpenTelemetry エクステンションに関する情報が記載されています。

前提条件

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

約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 OTel logging, in a similar way to the other OpenTelemetry signal 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.22.1: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サポートと、 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";
    }
}

トレースガイドに従ったことがあれば、このクラスは見慣れたものでしょう。主な違いは、 org.jboss.logging.Logger で記録された hello メッセージが OpenTelemetry のログに残るようになったことです。

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

OpenTelemetry Loggingで必須の設定は、ロギングを有効にすることだけです：

quarkus.otel.logs.enabled=true

デフォルトのプロパティ値を変更するために、 src/main/resources/application.properties ファイルを使用して、アプリケーション内でデフォルトの OTLP gRPC Exporter を設定する方法の例を以下に示します:

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	アプリケーションから作成されたすべてのログには、ログが `myservice` アプリケーションによって作成されたことを示す OpenTelemetry `Resource` が含まれます。設定されていない場合、デフォルトでアーティファクト ID が設定されます。
2	OpenTelemetry Loggingを有効にします。ビルド時に設定する必要があります。
3	ログを送信する gRPC エンドポイント。設定されていない場合は、 `http://localhost:4317` がデフォルトです。
4	認証によく使われるオプションの gRPC ヘッダー

すべての信号に対して同じプロパティーを使用して接続を設定するには、ベースの OpenTelemetry ガイドの設定セクションを確認してください。

Setting the log level

By default all log levels are exported.

If the following configuration is created in the the application.properties file, only logs with a level of ERROR or higher will be exported:

quarkus.otel.logs.level=ERROR

As in other logs in Quarkus, log levels can be set to these values.

アプリケーションの実行

まず、OpenTelemetry データを視覚化するシステムを起動する必要があります。 2 つの選択肢があります。

トレース、メトリクス、ログのためのオールインワンのGrafana OTel LGTMシステムを開始します。

Grafana-OTel-LGTM Dev サービスのデータを参照してください。

Grafana OTel LGTM オプション

Grafana-OTel-LGTM のスタートガイドを参照してください。

Quarkus Dev serviceには、データを可視化するGrafana、ログを保存するLoki、トレースを保存するTempo、メトリクスを保存するPrometheusが含まれます。また、データを受け取るためのOTelコレクターも提供します。

Logging エクスポーター

application.properties ファイルで exporter を logging に設定すれば、すべてのログをコンソールに出力できます：

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

1	エクスポーターを `logging` に設定します。通常、これを設定する必要はありません。デフォルトは `cdi` です。

次の依存関係もプロジェクトに追加します。

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

OpenTelemetry 設定リファレンス

メインの OpenTelemetry ガイド設定リファレンスを参照してください。

前提条件
アーキテクチャ
ソリューション
Mavenプロジェクトの作成
- Jakarta REST リソースの調査
- コンフィグレーションの作成
アプリケーションの実行
- Grafana-OTel-LGTM Dev サービスのデータを参照してください。
OpenTelemetry 設定リファレンス