SignalFx Javaエージェントからの移行

Splunk Distribution of OpenTelemetry Java のエージェントは廃止された SignalFx Java Agent を置き換えるものです。Splunk Java OTel エージェントに移行するには、次の手順に従います。

SignalFx Java エージェントは廃止されて、サポートが終了しました。Splunk Distribution of OpenTelemetry Java のエージェントに置き換えてください。

Splunk Distribution of OpenTelemetry Java のエージェントは、OpenTelemetry API を使用するオープンソースプロジェクトである OpenTelemetry Instrumentation for Java をベースにしており、SignalFx Java エージェントよりもメモリフットプリントが小さくなっています。

互換性と要件

Splunk Distribution of OpenTelemetry Java には、Java ランタイムバージョン 8 以上が必要です。「Java エージェントの互換性と要件」を参照してください。

Splunk Distribution of OpenTelemetry Java への移行

SignalFx Java Agent から Splunk Distribution of OpenTelemetry Java へ移行するには、以下の手順に従ってください：

Java エージェントをインストールして有効化します。「Java エージェントをインストールして有効化する」を参照してください。
トレースをエクスポートする OpenTelemetry Collector のエンドポイントを指定します。「エクスポータの設定」を参照してください。
アプリケーションの起動スクリプトで、-javaagent:./signalfx-tracing.jar を -javaagent:/path/to/splunk-otel-javaagent.jar に置き換えてください。

OpenTracing を使ってコードを手動でインストルメントしたら、OpenTracing Shim を使って OpenTelemetry トレーサを公開してください。手動でインストルメンテーションするために他の API を使っている場合は、アプリケーションの classpath にも含まれていることを確認します。

注: 移行の際、スパン名と属性の意味上の規約が変更されます。詳細は、SignalFx Smart Agent から Splunk Distribution of OpenTelemetry Collector への移行を参照してください。

機能の変更

以下の各セクションでは、SignalFx Java Agent から Splunk Distribution of OpenTelemetry Java への移行に伴う機能の主な変更点について説明します。

コンフィギュレーション設定の変更

次の表は、SignalFx Java Agent のシステム・プロパティと、それに相当する OpenTelemetry のプロパティです：


SignalFx システム・プロパティ	OpenTelemetry システム・プロパティ
`signalfx.service.name`	`otel.service.name=<service_name>`
`signalfx.env`	`otel.resource.attributes=deployment.environment=<environment_name>`
`signalfx.endpoint.url`	`otel.exporter.otlp.endpoint`
`signalfx.tracing.enabled`	`otel.javaagent.enabled`
`signalfx.integration.<name>.enabled=false`	`otel.instrumentation.<id>.enabled=false`します。詳細については、「ライブラリのインストルメンテーションに関する問題」を参照してください。
`signalfx.span.tags`	`otel.resource.attributes=<comma-separated key=value pairs>`
`signalfx.trace.annotated.method.blacklist`	`otel.trace.annotated.methods.exclude`
`signalfx.trace.methods`	`otel.trace.methods`
`signalfx.server.timing.context`	`splunk.trace-response-header.enabled`

次の表は、SignalFx Java エージェントの環境変数と、それに相当する OpenTelemetry の環境変数を示しています：


SignalFx 環境変数	OpenTelemetry環境変数
`SIGNALFX_SERVICE_NAME`	`OTEL_SERVICE_NAME=<service_name>`
`SIGNALFX_ENV`	`OTEL_RESOURCE_ATTRIBUTES=deployment.environment=<environment_name>`
`SIGNALFX_ENDPOINT_URL`	`OTEL_EXPORTER_OTLP_ENDPOINT`
`SIGNALFX_TRACING_ENABLED`	`OTEL_JAVAAGENT_ENABLED`
`SIGNALFX_INTEGRATION_<name>_ENABLED=false`	`OTEL_INSTRUMENTATION_<id>_ENABLED=false`します。詳細については、「ライブラリのインストルメンテーションに関する問題」を参照してください。
`SIGNALFX_SPAN_TAGS`	`OTEL_RESOURCE_ATTRIBUTES`
`SIGNALFX_TRACE_ANNOTATED_METHOD_BLACKLIST`	`OTEL_TRACE_ANNOTATED_METHODS_EXCLUDE`
`SIGNALFX_TRACE_METHODS`	`OTEL_TRACE_METHODS`
`SIGNALFX_SERVER_TIMING_CONTEXT`	`SPLUNK_TRACE_RESPONSE_HEADER_ENABLED`

以下の SignalFx Java Agent のシステムプロパティと環境変数には、Splunk Distribution for OpenTelemetry Java に対応する設定がありません。

非推奨システム・プロパティ

signalfx.agent.host
signalfx.db.statement.max.length
signalfx.recorded.value.max.length
signalfx.max.spans.per.trace
signalfx.max.continuation.depth

非推奨環境変数

SIGNALFX_AGENT_HOST
SIGNALFX_DB_STATEMENT_MAX_LENGTH
SIGNALFX_RECORDED_VALUE_MAX_LENGTH
SIGNALFX_MAX_SPANS_PER_TRACE
SIGNALFX_MAX_SPANS_PER_TRACE

Splunk Java の OTel 設定の詳細については、「Splunk Observability Cloud の Java エージェントを設定する」を参照してください。

ログ・インジェクションの変更

ログにトレースデータを挿入するための互換性のあるロギングフレームワークのリストについては、「Splunk Observability Cloud のログと Java トレースデータを接続する」を参照してください。

注釈変更のトレース

SignalFx Java Agent が使用する @Trace アノテーションは Splunk Distribution of OpenTelemetry Java と互換性があります。カスタムインストルメンテーションに @Trace アノテーションを使用している場合は、変更を行う必要はありません。

新しいカスタムインストルメンテーションを構成したいが、OpenTelemetry getTracer と API を直接使いたくない場合は、@Trace アノテーションの代わりに OpenTelemetry @WithSpan アノテーションを使います。詳細については、OpenTelemetry ドキュメントの「WithSpan アノテーションを構成する」を参照してください。

注: 例外を許可するための @TraceSetting アノテーションはサポートされていません。