Spring BootアプリのログをLogback + OpenTelemetry (OTLP)で送信する

Spring Boot + Logback でログを OTLP（OpenTelemetry Protocol）で送信したい場合、 opentelemetry‑logback‑appender が利用できます。
logback‑spring.xmlへの設定方法は、"OpenTelemetry with Spring Boot" というブログで紹介されています。この appender は GA 版ではなく、（長い間）α バージョンです。α バージョンである限り、Spring Boot 側でAuto Configurationが提供されることは期待できません（実際に Breaking Changes もありました。OpenTelemetry オブジェクト自体は Auto Configuration されます）。

とはいえ、毎回 logback‑spring.xml を手動で用意するのは手間です。そこで私は、以下の Auto Configuration ライブラリを作成し、α 版の appender が GA になるまでの暫定的なサポートとして利用しています。

https://github.com/making/otel-logs-autoconfigure

この Auto Configuration は Spring Boot 3.5 系と 4 系の両方に対応しているので、各バージョンでの使い方を順に紹介します。

Note

otel-logs-autoconfigure 0.6.0以降でlog4j2もサポートされています

OTLP バックエンド（Lognroll）の準備

ログを受け取る OTLP エンドポイントとして、軽量な Lognrollを使用します。
リポジトリは https://github.com/categolj/lognroll です。

Dockerで次のように起動できます:

docker run --rm -p 4318:4318 ghcr.io/categolj/lognroll:native

起動後、ブラウザで http://localhost:4318 にアクセスし、ユーザー名: 空、パスワード: changeme でログインすると次の画面が表示されます。

Spring Boot 4+ の場合

次のコマンドでプロジェクトを作成します:

curl -s https://start.spring.io/starter.tgz \
       -d artifactId=demo-otel-logs \
       -d name=demo-otel-logs \
       -d baseDir=demo-otel-logs \
       -d packageName=com.example \
       -d dependencies=web,actuator,configuration-processor,prometheus,opentelemetry,native \
       -d type=maven-project \
       -d applicationName=DemoOtelLogsApplication | tar -xzvf -
cd demo-otel-logs

pom.xml に以下を追記します。

<dependency>
    <groupId>am.ik.spring.opentelemetry</groupId>
    <artifactId>otel-logs-autoconfigure-logback</artifactId>
    <version>0.6.0</version>
</dependency>

src/main/resources/application.properties に次のプロパティを記述します。

logging.level.web=debug

# OpenTelemetry Logback Appender の実験的属性取得を有効化
management.opentelemetry.instrumentation.logback-appender.capture-experimental-attributes=true
management.opentelemetry.instrumentation.logback-appender.capture-key-value-pair-attributes=true

# OTLP エクスポート先
management.opentelemetry.logging.export.otlp.endpoint=http://localhost:4318/v1/logs
management.opentelemetry.logging.export.otlp.compression=gzip
management.opentelemetry.logging.export.otlp.headers.Authorization=Bearer changeme

# 今回はメトリクスは使用しないので無効化
management.otlp.metrics.export.enabled=false

Spring Boot 3.5 の場合

次のコマンドでプロジェクトを作成します:

curl -s https://start.spring.io/starter.tgz \
       -d artifactId=demo-otel-logs \
       -d name=demo-otel-logs \
       -d baseDir=demo-otel-logs \
       -d packageName=com.example \
       -d dependencies=web,actuator,configuration-processor,prometheus,native \
       -d type=maven-project \
       -d bootVersion=3.5.10 \
       -d applicationName=DemoOtelLogsApplication | tar -xzvf -
cd demo-otel-logs

Spring Boot 3.5 系では OpenTelemetry 用のスターターが提供されていないため、Trace ID と連携させるために Micrometer のブリッジも追加します。

<dependency>
    <groupId>am.ik.spring.opentelemetry</groupId>
    <artifactId>otel-logs-autoconfigure-logback</artifactId>
    <version>0.6.0</version>
</dependency>

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>

また、otel-logs-autoconfigure:0.5.0 が内部で使用している Logback Appender のバージョンは、Spring Boot 3.5 が管理している OpenTelemetry Java SDK のバージョンでは動作しません。そのため、pom.xml の <properties> に以下を追加してバージョンを上書きします。

<properties>
    <!-- ... -->
    <opentelemetry.version>1.55.0</opentelemetry.version>
</properties>

application.properties の内容は Spring Boot 4+ とOTLP エクスポート先のプロパティが異なります。

logging.level.web=debug

# OpenTelemetry Logback Appender の実験的属性取得を有効化
management.opentelemetry.instrumentation.logback-appender.capture-experimental-attributes=true
management.opentelemetry.instrumentation.logback-appender.capture-key-value-pair-attributes=true

# OTLP エクスポート先
management.otlp.logging.endpoint=http://localhost:4318/v1/logs
management.otlp.logging.compression=gzip
management.otlp.logging.headers.Authorization=Bearer changeme

# 今回はメトリクスは使用しないので無効化
management.otlp.metrics.export.enabled=false

ビルドと動作確認

次のコマンドでビルドします:

./mvnw clean package -DskipTests

次のコマンドで実行します:

java -jar target/demo-otel-logs-0.0.1-SNAPSHOT.jar

起動後、Lognroll の UI で "View Logs" ボタンをクリックすると、以下のようにログが表示されます。

次のコマンドでHTTP リクエストを送信します:

curl http://localhost:8080/actuator/health

再度、"View Logs"を押すと、リクエストログが出力され、trace_id 列に対応する Trace ID が確認できます。

本記事では、LognrollをOTLP エンドポイントとしてローカルに立ち上げ、Spring Boot アプリケーションから OpenTelemetry Logback Appender を介してログを送信しました。
otel-logs-autoconfigure が提供する Auto Configuration により、logback‑spring.xml を手書きせずに application.properties だけで設定が完結します。

IK.AM