Splunk Observability Cloud のログと Java トレースデータを接続する

Splunk Distribution of OpenTelemetry Java エージェントは、アプリケーションログをキャプチャし、OTLP エクスポータを使用してコレクタに送信します。ログイベントには、トレース ID、スパン ID、およびトレースフラグで注釈が付けられます。

Splunk Distribution of OpenTelemetry Javaエージェントは、アプリケーションログを自動的にキャプチャし、OTLPエクスポーターを使用してOpen Telemetry Collectorに送信し、ログイベントにトレースID、スパンID、トレースフラグでアノテーションを付けます。

必要に応じて、サービスのバージョンやデプロイ環境など、Splunk OTel Javaエージェントによって自動的に提供される追加の属性を含むログを生成するようにJavaロギングライブラリを設定できます。

注: ログのエクスポートには、Splunk Distribution of OpenTelemetry Collectorが必要です。

互換性と必要条件をチェック

Splunk OTel Java エージェントは以下のロギングライブラリをサポートしています：

Log4j 2 2.7 以上
Log4j 1 1.2 以上
Logback 1.0 以上
JBoss LogManager 1.1.0以上

java.util.logging ライブラリは、Splunk Distribution of OpenTelemetry Java と互換性のあるすべての JDK バージョンで完全にサポートされています。「Java エージェントの互換性と要件」を参照してください。

ログ文のトレースメタデータ

Splunk OTel Javaエージェントは、デフォルトでログライブラリ用に次のMapped Diagnostic Context（MDC）フィールドを自動的に追加します。

トレース情報： trace_id と span_id
トレースフラグ

デフォルトの動作では、MDC フィールドは Collector に送信されますが、アプリケーションログファイルには書き込まれません。この情報をログファイルに含めるには、MDC フィールドを含めるようにロギングフレームワークの出力フォーマットを設定する必要があります。ロギングフレームワークを設定するには、「ロギングライブラリを設定する」を参照してください。

Collectorは、OTLPエクスポーターを使用してアノテーションを付けたログを送信します。

ログのエクスポートを無効にする

ログのエクスポートをオフにするには、OTEL_LOGS_EXPORTER 環境変数または otel.logs.exporter システムプロパティを none に設定します。

リソース属性を注入する

Java エージェントは自動的にログを生成し、Collector を通じて Splunk に送信しますが、互換性のあるログライブラリを使用して注釈付きログを生成し、ログを手動で収集したり、Universal Forwarder を経由したりすることもできます。「Splunk Log Observer Connect の概要」を参照してください。

たとえば、service.name や deployment.environment などのログステートメントにリソース属性を挿入できます。これには、挿入する属性を定義し、ロガーを手動で設定する必要があります。

リソース属性を定義する

属性を挿入する前に、実行時に mdc.resource-attributes プロパティを設定して MDC から属性を利用できるようにする必要があります。例：

-Dotel.instrumentation.common.mdc.resource-attributes=service.name,deployment.environment

ロギングライブラリを設定する

Splunk Distribution of OpenTelemetry Javaは、ロガーライブラリを設定するために使用できるコンテキストプロパティをプレフィックスとするシステムプロパティとして、リソース属性を公開しています。

以下の例は、ロギングライブラリが生成するログ文に追加のメタデータを含める方法を示しています：

Log4j

src/main/resources/log4j2.xml ファイルなど、Log4j の設定を編集してください。環境によっては、別のファイルを編集したり、別のコンフィギュレーションシステムを使用したりする必要がある可能性があります。

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
   <Appenders>
      <Console name="STDOUT" target="SYSTEM_OUT">
         <JsonLayout compact="true" eventEol="true">
            <KeyValuePair key="trace_id" value="${ctx:trace_id}"/>
            <KeyValuePair key="span_id" value="${ctx:span_id}"/>
            <KeyValuePair key="service.name" value="${ctx:service.name}"/>
            <KeyValuePair key="environment" value="${ctx:deployment.environment}"/>
            <KeyValuePair key="trace_sampled" value="${ctx:trace_flags}"/>
         </JsonLayout>
      </Console>
   </Appenders>
   <!-- More configuration -->
</Configuration>

Spring Bootアプリケーションでは、application.properties ファイルを編集して、以下のロギングパターンを追加することもできます：

logging.pattern.console = %d{yyyy-MM-dd HH:mm:ss} - %logger{36} - %msg trace_id=%X{trace_id} span_id=%X{span_id} service.name=%X{service.name}, deployment.environment=%X{deployment.environment} trace_flags=%X{trace_flags} %n

Logback

src/main/resources/logback.xml ファイルなどの Logback 設定を編集します。環境によっては、別のファイルを編集したり、別のコンフィギュレーションシステムを使用したりする必要がある可能性があります。

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
   <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
      <encoder>
         <pattern>d{yyyy-MM-dd HH:mm:ss} - %logger{36} - %msg trace_id=%X{trace_id} span_id=%X{span_id} service.name=%X{service.name}, deployment.environment=%X{deployment.environment} trace_flags=%X{trace_flags} %nn</pattern>
      </encoder>
   </appender>
   <root level="info">
      <appender-ref ref="STDOUT" />
   </root>
</configuration>

Spring Bootアプリケーションでは、application.properties ファイルを編集して、以下のロギングパターンを追加することもできます：

logging.pattern.console = %d{yyyy-MM-dd HH:mm:ss} - %logger{36} - %msg %logger{36} - %msg trace_id=%X{trace_id} span_id=%X{span_id} service.name=%X{service.name}, deployment.environment=%X{deployment.environment} trace_flags=%X{trace_flags} %n %n

JBoss LogManager

JBoss LogManagerの設定を編集します（ logging.properties ファイルなど）。

formatter.PATTERN=org.jboss.logmanager.formatters.PatternFormatter
formatter.PATTERN.properties=pattern
formatter.PATTERN.constructorProperties=pattern
formatter.PATTERN.pattern=%logger{36} - %msg trace_id=%X{trace_id} span_id=%X{span_id} service.name=%X{service.name}, deployment.environment=%X{deployment.environment} trace_flags=%X{trace_flags}: %m%n

サーバーレスのサービスまたはアプリケーションをインストルメントする場合は、代わりに環境変数を使用します。導入環境では、OTEL_ENV_NAME などの任意の環境変数を設定する必要があります。

Log4j

<PatternLayout>
   <pattern>
      service.name=${OTEL_SERVICE_NAME}, deployment.environment=${OTEL_ENV_NAME} %m%n
   </pattern>
</PatternLayout>

Logback

<pattern>
   service.name: ${OTEL_SERVICE_NAME}, deployment.environment: ${OTEL_ENV_NAME}: %m%n
</pattern>

JBoss LogManager

formatter.PATTERN.pattern=service.name=${OTEL_SERVICE_NAME}, deployment.environment=${OTEL_ENV_NAME}