注意

Splunk Distribution of OpenTelemetry Javaは、2024年6月25日をもって非推奨となり、2025年6月30日にサポート終了となります。それまでは、重要なセキュリティ修正とバグ修正のみが提供されます。

新規のお客様は、Splunk Distribution of OpenTelemetry Java の最新バージョンをご利用ください。既存のお客様は、2.5.0以上への移行をご検討ください。移行方法については、OpenTelemetry Java 2.xメトリクスの移行ガイドを参照してください。

Splunk Observability Cloud用のJavaエージェント1.xを設定する(非推奨) 🔗

以下のセクションでは、Splunk Distribution of OpenTelemetry Java独自の新機能を有効にするオプションを含め、Javaエージェント1.xを設定するために利用可能なすべての設定について説明します。

設定方法 🔗

エージェントの設定は2つの方法で変更できます：

環境変数を設定します。例：

export OTEL_SERVICE_NAME=my-java-app

$env:OTEL_SERVICE_NAME=my-java-app

システム・プロパティをランタイム・パラメータとして追加します。例：

java -javaagent:./splunk-otel-javaagent.jar \
-Dotel.service.name=<my-java-app> \
-jar <myapp>.jar

環境変数は、OpenTelemetry エージェントを設定するための望ましい方法です。システムプロパティを指定すると、既存の環境変数を上書きします。

一般設定 🔗

以下の設定は、Splunk Distribution of OpenTelemetry Java 固有のものです：

環境変数	説明
`SPLUNK_REALM`	組織のレルムの名前、例えば `us0` 。レルムを設定すると、テレメトリは Splunk Distribution of OpenTelemetry Collector をバイパスして Splunk Observability Cloud のインジェスト・エンドポイントに直接送信されます。システム・プロパティ： `splunk.realm`
`SPLUNK_ACCESS_TOKEN`	Splunk Observability Cloud に直接データを送信するための Splunk 認証トークン。デフォルトでは設定されていません。Splunk Observability Cloud インジェスト・エンドポイントにデータを送信する必要がなければ不要です。Splunk Observability Cloudを使用して認証トークンを作成および管理するを参照してください。システム・プロパティ： `splunk.access.token`
`SPLUNK_TRACE_RESPONSE_HEADER_ENABLED`	HTTP レスポンス・ヘッダーへのサーバートレース情報の追加を有効にします。詳細については、サーバートレース情報を参照してください。デフォルト値は `true` です。システム・プロパティ： `splunk.trace-response-header.enabled`
`SPLUNK_METRICS_FORCE_FULL_COMMANDLINE`	すべてのメトリクスのリソース属性として、完全なコマンド行を追加します。Falseを指定すると、255文字を超えるコマンドは切り捨てられます。システム・プロパティ： `splunk.metrics.force_full_commandline`

トレース設定 🔗

以下の設定は、トレースの制限と属性を制御します：

環境変数	説明
`OTEL_SERVICE_NAME`	インストルメンテーションするサービスまたはアプリケーションの名前。`OTEL_RESOURCE_ATTRIBUTES` 変数で定義されたサービス名よりも優先されます。システム・プロパティ： `otel.service.name`
`OTEL_RESOURCE_ATTRIBUTES`	報告されたスパンごとに追加されるリソース属性のカンマ区切りリスト。例えば、`key1=val1,key2=val2` 。システム・プロパティ： `otel.resource.attributes`
`OTEL_INSTRUMENTATION_COMMON_` `PEER_SERVICE_MAPPING`	ホスト名またはIPアドレスからのマッピングのカンマ区切りリストを指定して、 `peer.service` 属性を追加するために使用されます。例えば、`1.2.3.4=cats-srv,dogs-srv.com=dogs-api` に設定された場合、`1.2.3.4` へのリクエストは `peer.service` 属性 `cats-service` を持ち、`dogs-srv.com` へのリクエストは `dogs-api` を持ちます。システム・プロパティ： `otel.instrumentation.common` `.peer-service-mapping`
`OTEL_INSTRUMENTATION_METHODS_INCLUDE`	対象メソッド文字列の `@WithSpan` アノテーション機能を追加します。フォーマットは `my.package.MyClass1[m1,m2];my.package.MyClass2[m3]` です。システム・プロパティ： `otel.instrumentation.methods.include`
`OTEL_INSTRUMENTATION_OPENTELEMETRY` `_ANNOTATIONS_EXCLUDE_METHODS`	特定のメソッドについて `@WithSpan` のインストルメンテーションを抑制します。フォーマットは `my.package.MyClass1[m1,m2];my.package.MyClass2[m3]` です。システム・プロパティ： `otel.instrumentation.opentelemetry` `-annotations.exclude-methods`
`OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT`	スパンごとの属性の最大数。デフォルト値は無制限です。システム・プロパティ： `otel.span.attribute.count.limit`
`OTEL_SPAN_EVENT_COUNT_LIMIT`	スパンあたりの最大イベント数。デフォルト値は無制限です。システム・プロパティ： `otel.span.event.count.limit`
`OTEL_SPAN_LINK_COUNT_LIMIT`	スパンあたりの最大リンク数。デフォルト値は `1000` です。システム・プロパティ： `otel.span.link.count.limit`

エクスポーターの設定 🔗

以下の設定は、トレースエクスポーターとそのエンドポイントをコントロールします：

環境変数	説明
`OTEL_TRACES_EXPORTER`	使用するトレース・エクスポーター。カンマ区切りで複数の値を設定できます。システム・プロパティ： `otel.traces.exporter`
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP gRPC エンドポイント。デフォルト値は `http://localhost:4317` です。システム・プロパティ： `otel.exporter.otlp.endpoint`

Splunk Distribution of OpenTelemetry Java は、デフォルトで OTLP gRPC span エクスポーターを使用します。Splunk Observability Cloud に直接データを送信するには、Splunk Observability Cloud に直接データを送信するを参照してください。

サンプラーの設定 🔗

以下の設定はトレースサンプリングをコントロールします：

環境変数

説明

OTEL_TRACES_SAMPLER

使用するサンプラー。デフォルト値は always_on です。

OpenTelemetry Java SDK が提供するサンプラーに加えて、以下のサンプラーを使用できます：

internal_root_off: spanKind が INTERNAL、CLIENT または PRODUCER であるルートスパンを持つすべてのトレースを削除します。 spanKind が SERVER または CONSUMER であるルートスパンを保持します。

rules: OTEL_TRACES_SAMPLER_ARG の設定値で定義された、特定のエンドポイントを起点とするすべてのトレースを削除します。spanKind が SERVER であるスパンにのみ適用されます。

システム・プロパティ： otel.traces.sampler

OTEL_TRACES_SAMPLER_ARG

セミコロンで区切られた、rules サンプラーのルールのリスト。例：

OTEL_TRACES_SAMPLER_ARG=drop=/healthcheck;fallback=always_on

以下のルールがサポートされています：

drop=<value>:サンプラーは、スパンの http.target 属性に、指定した値と同じ部分文字列がある場合、そのスパンを削除します。例： drop=/status。

fallback=<sampler>:指定されたスパンにマッチする drop ルールがない場合に使用するサンプラー。サポートされるサンプラーは、always_on と parentbased_always_on です。複数のフォールバック・サンプラーを定義した場合、Javaエージェントは最後のものを使用します。

rules サンプラーを使用する際に引数を設定しない場合、インストルメンテーションのデフォルトは parentbased_always_on サンプラーになります。

システム・プロパティ： otel.traces.sampler.arg

トレースサンプリングの例 🔗

次の例は、rules traces sampler を使用して、/healthcheck エンドポイントを監視から除外する方法を示しています：

export OTEL_TRACES_SAMPLER=rules
export OTEL_TRACES_SAMPLER_ARG=drop=/healthcheck;fallback=parentbased_always_on

除外されたエンドポイントを呼び出した結果として起こるダウンストリームサービスへのリクエストもすべて除外されます。

プロパゲータの構成 🔗

以下の設定はトレース伝搬をコントロールします：

環境変数	説明
`OTEL_PROPAGATORS`	使用したいプロパゲータのカンマ区切りリスト。デフォルト値は `tracecontext,baggage` です。サポートされているプロパゲータの一覧は、OpenTelemetry のドキュメントにあります。システム・プロパティ： `otel.propagators`

旧バージョンの Splunk Distribution of OpenTelemetry Java または SignalFx Java Agent との後方互換性を保つには、b3multi トレースプロパゲータを使用してください：

export OTEL_PROPAGATORS=b3multi

$env:OTEL_PROPAGATORS=b3multi

AlwaysOn Profilingの Java 設定 🔗

以下の設定は、Java エージェントの AlwaysOn Profiling機能を制御します：

環境変数	説明
`SPLUNK_PROFILER_ENABLED`	AlwaysOn Profilingを有効にします。デフォルト値は `false` です。システム・プロパティ： `splunk.profiler.enabled`
`SPLUNK_PROFILER_LOGS_ENDPOINT`	プロファイラ・ログのコレクタ・エンドポイント。デフォルトでは、`otel.exporter.otlp.endpoint` の値を取ります。システム・プロパティ： `splunk.profiler.logs-endpoint`
`SPLUNK_PROFILER_DIRECTORY`	JDK Flight Recorder ファイルの場所。デフォルト値はローカルディレクトリ ( `.` ) です。システム・プロパティ： `splunk.profiler.directory`
`SPLUNK_PROFILER_RECORDING_DURATION`	記録単位の継続時間。`<number><unit>` の形式で継続時間を定義できます。単位は `ms`、`s`、`m`、`h`、`d` のいずれかです。デフォルトの間隔は `20s` です。数値を入力し単位を入力しなかった場合、デフォルトの単位は `ms` と見なされます。システム・プロパティ： `splunk.profiler.recording.duration`
`SPLUNK_PROFILER_KEEP_FILES`	JDK Flight Recorder (JFR) ファイルを保存するかどうか。デフォルト値は `false` で、処理後に JFR ファイルが削除されることを意味します。システム・プロパティ： `splunk.profiler.keep-files`
`SPLUNK_PROFILER_CALL_STACK_INTERVAL`	コールスタックをサンプリングする頻度をミリ秒単位で指定します。デフォルト値は10000ミリ秒です。システム・プロパティ： `splunk.profiler.call.stack.interval`
`SPLUNK_PROFILER_MEMORY_ENABLED`	すべてのオプションでメモリ・プロファイリングを有効にします。特定のメモリ・プロファイリング・オプションを有効または無効にするには、その値を明示的に設定します。デフォルト値は `false` です。 `splunk.profiler.enabled` を `true` に設定する必要があります。メモリ・プロファイリングを有効にすると、`splunk.metrics.enabled` の値が `true` に設定されます。注釈 OpenJDKのバージョン15.0から17.0.8は、メモリプロファイリングに対応していません。詳しくはJDKバグシステムの https://bugs.openjdk.org/browse/JDK-8309862 を参照してください。システム・プロパティ： `splunk.profiler.memory.enabled`
`SPLUNK_PROFILER_MEMORY_EVENT_RATE`	単位時間あたりのスタック・トレースで表される、メモリ・プロファイリング・データのレート制限。`<number>/<unit>` 単位は `s` または `m` です。デフォルト値は `150/s` で、1秒あたり150スタック・トレースです。アプリケーションサーバーのような複雑なマルチスレッド・ワークロードからメモリ・プロファイリング・データを収集する場合は、この値を増やすことを検討してください。システム・プロパティ： `splunk.profiler.memory.event.rate`
`SPLUNK_PROFILER_TLAB_ENABLED`	TLAB メモリイベントを有効にするかどうか。デフォルト値は、`splunk.profiler.memory.enabled` プロパティに割り当てられた値です。システム・プロパティ： `splunk.profiler.tlab.enabled`
`SPLUNK_PROFILER_INCLUDE_INTERNAL_STACKS`	エージェント内部スレッドのスタックトレースと JDK 内部フレームのスタックトレースを含めるかどうか。デフォルト値は `false` です。システム・プロパティ： `splunk.profiler.include.internal.stacks`
`SPLUNK_PROFILER_TRACING_STACKS_ONLY`	スパンコンテキストにリンクされているスタックトレースのみを含めるかどうか。デフォルト値は `false` です。`true` に設定すると、スパンコンテキストにリンクされていないコールスタックは削除されるため、データインジェスト量を削減するのに便利です。システム・プロパティ： `splunk.profiler.tracing.stacks.only`

AlwaysOn Profilingの詳細については、Splunk APMのAlwaysOn Profilingの概要を参照してください。

メトリクス収集設定 🔗

注釈

OpenTelemetryのネイティブメトリクスから移行するには、OpenTelemetry Java 2.xメトリクスの移行ガイドを参照してください。

以下の設定は、Java エージェントのメトリクス収集を制御します：

環境変数

説明

SPLUNK_METRICS_ENABLED

メトリクスのエクスポートを有効にします。詳細については、Splunk OTel Java エージェントが収集したメトリクスと属性を参照してください。

デフォルトは false です。
splunk.profiler.memory.enabled プロパティを使用してメモリ・プロファイリングを有効にすると、splunk.metrics.enabled の値は true に設定されます。

システム・プロパティ： splunk.metrics.enabled

SPLUNK_METRICS_ENDPOINT

OTelコレクタのメトリクスエンドポイント。デフォルトは http://localhost:9943/v2/datapoint.

システム・プロパティ： splunk.metrics.endpoint

SPLUNK_METRICS_EXPORT_INTERVAL

非推奨。代わりに OTEL_METRIC_EXPORT_INTERVAL を使ってください。公式 OpenTelemetry ドキュメントの Periodic exporting MetricReader を参照してください。

サーバートレース情報 🔗

モバイルおよびウェブアプリケーションからのリアルユーザーモニタリング（RUM）リクエストとサーバートレース・データを接続するために、トレース・レスポンス・ヘッダーがデフォルトで有効になっています。インストルメンテーションは、HTTP レスポンスに以下のレスポンス・ヘッダーを追加します：

Access-Control-Expose-Headers: Server-Timing
Server-Timing: traceparent;desc="00-<serverTraceId>-<serverSpanId>-01"

Server-Timing ヘッダーは、traceId と spanId パラメータを traceparent 形式で含みます。詳しくは、W3CウェブサイトのServer-Timingとtraceparentのドキュメントを参照してください。

以下のサーバー・フレームワークとライブラリは、Server-Timing の情報を追加します：

Servlet API バージョン 2.2 から 4.X。
Nettyバージョン3.8から4.0。

注釈

トレース・レスポンス・ヘッダーを無効にする必要がある場合は、SPLUNK_TRACE_RESPONSE_HEADER_ENABLED を false に設定します。

その他の設定 🔗

環境変数	説明
`OTEL_JAVAAGENT_ENABLED`	Javaエージェントの自動インストルメンテーションをグローバルに有効にします。デフォルト値は `true` です。テストシナリオやパイプラインで自動検出を無効にするのに便利です。システムプロパティ： `otel.javaagent.enabled`

このページは 2024年06月25日に最終更新されました。

Related Topics