OpenTelemetry Agent for JAVA パラメータ設定¶
環境変数を使用した設定¶
一部の環境では、環境変数による設定が好まれます。システムプロパティで設定可能な項目は、環境変数でも設定できます。以下の設定の多くは両方のオプションを提供していますが、適切なシステムプロパティ名にマッピングするために以下の手順を適用する必要はありません。
- システムプロパティを大文字に変換します。
- すべての
.と-を_に置き換えます。 例：otel.instrumentation.common.default-enabledはOTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLEDに変換されます。
起動¶
-javaagent:/home/liurui/agent/opentelemetry-javaagent-guance.jar \
-Dotel.traces.exporter=otlp \
-Dotel.exporter.otlp.endpoint=http://localhost:4317 \
-Dotel.resource.attributes=service.name=springboot \
-jar springboot-server.jar
エージェントの無効化¶
デフォルトでは有効です。無効にする場合は false に設定します。
-Dotel.javaagent.enabled=false
debug ログの有効化¶
-Dotel.javaagent.debug=true
[otel.javaagent 2024-02-19 10:25:25:909 +0800] [main] INFO io.opentelemetry.javaagent.tooling.VersionLogger - opentelemetry-javaagent - version: 1.26.1-guance
[otel.javaagent 2024-02-19 10:25:25:911 +0800] [main] DEBUG io.opentelemetry.javaagent.tooling.VersionLogger - Running on Java 11.0.18. JVM Java HotSpot(TM) 64-Bit Server VM - Oracle Corporation - 11.0.18+9-LTS-195
[otel.javaagent 2024-02-19 10:25:25:911 +0800] [main] DEBUG io.opentelemetry.javaagent.tooling.AgentInstaller - io.opentelemetry.javaagent.tooling.AgentInstaller loaded on io.opentelemetry.javaagent.bootstrap.AgentClassLoader@6cc4c815
[otel.javaagent 2024-02-19 10:25:25:924 +0800] [main] DEBUG io.opentelemetry.javaagent.tooling.SafeServiceLoader - Unable to load instrumentation class: io/opentelemetry/javaagent/shaded/instrumentation/javaagent/runtimetelemetryjfr/RuntimeMetricsInstallerJfr has been compiled by a more recent version of the Java Runtime (class file version 61.0), this version of the Java Runtime only recognizes class file versions up to 55.0
[otel.javaagent 2024-02-19 10:25:26:098 +0800] [main] DEBUG io.opentelemetry.sdk.internal.JavaVersionSpecific - Using the APIs optimized for: Java 9+
[otel.javaagent 2024-02-19 10:25:26:584 +0800] [main] DEBUG io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdkBuilder - Global OpenTelemetry set to OpenTelemetrySdk{tracerProvider=SdkTracerProvider{clock=SystemClock{}, idGenerator=RandomIdGenerator{}, resource=Resource{schemaUrl=https://opentelemetry.io/schemas/1.19.0, attributes={host.arch="amd64", host.name="liurui", os.description="Linux 5.15.0-92-generic", os.type="linux", process.command_line="/home/liurui/middleware/jdk/jdk-11.0.18/bin/java -javaagent:/home/liurui/agent/opentelemetry-javaagent-1.26.1-guance.jar -Dotel.traces.exporter=otlp -Dotel.exporter.otlp.endpoint=http://localhost:4317 -Dotel.resource.attributes=service.name=springboot -Dotel.javaagent.debug=true -XX:TieredStopAtLevel=1 -Xverify:none -Dspring.output.ansi.enabled=always -Dcom.sun.management.jmxremote -Dspring.jmx.enabled=true -Dspring.liveBeansView.mbeanDomain -Dspring.application.admin.enabled=true -Dmanagement.endpoints.jmx.exposure.include=* -javaagent:/home/liurui/middleware/idea-IU-231.9161.38/lib/idea_rt.jar=39689:/home/liurui/middleware/idea-IU-231.9161.38/bin -Dfile.encoding=UTF-8 com.zy.observable.server.ServerApplication", process.executable.path="/home/liurui/middleware/jdk/jdk-11.0.18/bin/java", process.pid=11464, process.runtime.description="Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 11.0.18+9-LTS-195", process.runtime.name="Java(TM) SE Runtime Environment", process.runtime.version="11.0.18+9-LTS-195", service.name="springboot", telemetry.auto.version="1.26.1-guance", telemetry.sdk.language="java", telemetry.sdk.name="opentelemetry", telemetry.sdk.version="1.26.0"}}, spanLimitsSupplier=SpanLimitsValue{maxNumberOfAttributes=128, maxNumberOfEvents=128, maxNumberOfLinks=128, maxNumberOfAttributesPerEvent=128, maxNumberOfAttributesPerLink=128, maxAttributeValueLength=2147483647}, sampler=ParentBased{root:AlwaysOnSampler,remoteParentSampled:AlwaysOnSampler,remoteParentNotSampled:AlwaysOffSampler,localParentSampled:AlwaysOnSampler,localParentNotSampled:AlwaysOffSampler}, spanProcessor=MultiSpanProcessor{spanProcessorsStart=[io.opentelemetry.javaagent.tooling.AddThreadDetailsSpanProcessor@74287ea3], spanProcessorsEnd=[BatchSpanProcessor{spanExporter=io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter@7d7758be, scheduleDelayNanos=5000000000, maxExportBatchSize=512, exporterTimeoutNanos=30000000000}, SimpleSpanProcessor{spanExporter=io.opentelemetry.exporter.logging.LoggingSpanExporter@2bdd8394}], spanProcessorsAll=[BatchSpanProcessor{spanExporter=io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter@7d7758be, scheduleDelayNanos=5000000000, maxExportBatchSize=512, exporterTimeoutNanos=30000000000}, io.opentelemetry.javaagent.tooling.AddThreadDetailsSpanProcessor@74287ea3, SimpleSpanProcessor{spanExporter=io.opentelemetry.exporter.logging.LoggingSpanExporter@2bdd8394}]}}, meterProvider=SdkMeterProvider{clock=SystemClock{}, resource=Resource{schemaUrl=https://opentelemetry.io/schemas/1.19.0, attributes={host.arch="amd64", host.name="liurui", os.description="Linux 5.15.0-92-generic", os.type="linux", process.command_line="/home/liurui/middleware/jdk/jdk-11.0.18/bin/java -javaagent:/home/liurui/agent/opentelemetry-javaagent-1.26.1-guance.jar -Dotel.traces.exporter=otlp -Dotel.exporter.otlp.endpoint=http://localhost:4317 -Dotel.resource.attributes=service.name=springboot -Dotel.javaagent.debug=true -XX:TieredStopAtLevel=1 -Xverify:none -Dspring.output.ansi.enabled=always -Dcom.sun.management.jmxremote -Dspring.jmx.enabled=true -Dspring.liveBeansView.mbeanDomain -Dspring.application.admin.enabled=true -Dmanagement.endpoints.jmx.exposure.include=* -javaagent:/home/liurui/middleware/idea-IU-231.9161.38/lib/idea_rt.jar=39689:/home/liurui/middleware/idea-IU-231.9161.38/bin -Dfile.encoding=UTF-8 com.zy.observable.server.ServerApplication", process.executable.path="/home/liurui/middleware/jdk/jdk-11.0.18/bin/java", process.pid=11464, process.runtime.description="Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 11.0.18+9-LTS-195", process.runtime.name="Java(TM) SE Runtime Environment", process.runtime.version="11.0.18+9-LTS-195", service.name="springboot", telemetry.auto.version="1.26.1-guance", telemetry.sdk.language="java", telemetry.sdk.name="opentelemetry", telemetry.sdk.version="1.26.0"}}, metricReaders=[PeriodicMetricReader{exporter=io.opentelemetry.exporter.otlp.metrics.OtlpGrpcMetricExporter@68746f22, intervalNanos=60000000000}], views=[]}, loggerProvider=SdkLoggerProvider{clock=SystemClock{}, resource=Resource{schemaUrl=https://opentelemetry.io/schemas/1.19.0, attributes={host.arch="amd64", host.name="liurui", os.description="Linux 5.15.0-92-generic", os.type="linux", process.command_line="/home/liurui/middleware/jdk/jdk-11.0.18/bin/java -javaagent:/home/liurui/agent/opentelemetry-javaagent-1.26.1-guance.jar -Dotel.traces.exporter=otlp -Dotel.exporter.otlp.endpoint=http://localhost:4317 -Dotel.resource.attributes=service.name=springboot -Dotel.javaagent.debug=true -XX:TieredStopAtLevel=1 -Xverify:none -Dspring.output.ansi.enabled=always -Dcom.sun.management.jmxremote -Dspring.jmx.enabled=true -Dspring.liveBeansView.mbeanDomain -Dspring.application.admin.enabled=true -Dmanagement.endpoints.jmx.exposure.include=* -javaagent:/home/liurui/middleware/idea-IU-231.9161.38/lib/idea_rt.jar=39689:/home/liurui/middleware/idea-IU-231.9161.38/bin -Dfile.encoding=UTF-8 com.zy.observable.server.ServerApplication", process.executable.path="/home/liurui/middleware/jdk/jdk-11.0.18/bin/java", process.pid=11464, process.runtime.description="Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 11.0.18+9-LTS-195", process.runtime.name="Java(TM) SE Runtime Environment", process.runtime.version="11.0.18+9-LTS-195", service.name="springboot", telemetry.auto.version="1.26.1-guance", telemetry.sdk.language="java", telemetry.sdk.name="opentelemetry", telemetry.sdk.version="1.26.0"}}, logLimits=LogLimits{maxNumberOfAttributes=128, maxAttributeValueLength=2147483647}, logRecordProcessor=io.opentelemetry.sdk.logs.NoopLogRecordProcessor@7fd7a283}, propagators=DefaultContextPropagators{textMapPropagator=MultiTextMapPropagator{textMapPropagators=[W3CTraceContextPropagator, W3CBaggagePropagator]}}} by autoconfiguration
[otel.javaagent 2024-02-19 10:25:26:873 +0800] [main] DEBUG io.opentelemetry.javaagent.tooling.AgentInstaller - Loading extension instrumentation-loader [class io.opentelemetry.javaagent.tooling.instrumentation.InstrumentationLoader]
[otel.javaagent 2024-02-19 10:25:26:959 +0800] [main] DEBUG io.opentelemetry.javaagent.tooling.SafeServiceLoader - Unable to load instrumentation class: io/opentelemetry/javaagent/instrumentation/spring/jms/v6_0/SpringJmsInstrumentationModule has been compiled by a more recent version of the Java Runtime (class file version 61.0), this version of the Java Runtime only recognizes class file versions up to 55.0
[otel.javaagent 2024-02-19 10:25:27:010 +0800] [main] DEBUG io.opentelemetry.javaagent.tooling.SafeServiceLoader - Unable to load instrumentation class: io/opentelemetry/javaagent/instrumentation/spring/webmvc/v6_0/SpringWebMvcInstrumentationModule has been compiled by a more recent version of the Java Runtime (class file version 61.0), this version of the Java Runtime only recognizes class file versions up to 55.0
[otel.javaagent 2024-02-19 10:25:27:011 +0800] [main] DEBUG io.opentelemetry.javaagent.tooling.instrumentation.InstrumentationLoader - Loading instrumentation opentelemetry-instrumentation-annotations [class io.opentelemetry.javaagent.instrumentation.instrumentationannotations.AnnotationInstrumentationModule]
[otel.javaagent 2024-02-19 10:25:27:031 +0800] [main] DEBUG io.opentelemetry.javaagent.tooling.instrumentation.InstrumentationLoader - Loading instrumentation opentelemetry-api [class io.opentelemetry.javaagent.instrumentation.opentelemetryapi.v1_15.OpenTelemetryApiInstrumentationModule]
[otel.javaagent 2024-02-19 10:25:27:032 +0800] [main] DEBUG io.opentelemetry.javaagent.tooling.instrumentation.InstrumentationLoader - Loading instrumentation opentelemetry-api [class io.opentelemetry.javaagent.instrumentation.opentelemetryapi.v1_10.OpenTelemetryApiInstrumentationModule]
debug を有効にすると、ログはコンソールおよびアプリケーションで設定されているログファイル（存在する場合）に出力されます。
データベースのサニタイズ¶
エージェントは、db.statement セマンティック属性を設定する前に、すべてのデータベースクエリ/ステートメントをサニタイズします。クエリ文字列内のすべての値（文字列、数値）は疑問符 (?) に置き換えられます。
注意：JDBC のバインドパラメータは db.statement ではキャプチャされません。バインドパラメータのキャプチャについては、関連する issue を参照してください。
例：
- SQL クエリ
SELECT a from b where password="secret"は、エクスポートされたスパンではSELECT a from b where password=?として表示されます。 - Redis コマンド
HSET map password "secret"は、エクスポートされたスパンではHSET map password ?として表示されます。
デフォルトでは、すべてのデータベースインストルメンテーションでこの動作が有効になっています。以下のプロパティを使用して無効にします。
システムプロパティ： otel.instrumentation.common.db-statement-sanitizer.enabled 環境変数： OTEL_INSTRUMENTATION_COMMON_DB_STATEMENT_SANITIZER_ENABLED デフォルト値：true 説明：DB ステートメントのサニタイズを有効にします。
スパンの抑制¶
span-kind 戦略の使用を推奨します。
当エージェントでインストルメント化される一部のライブラリは、内部でさらに下位レベルのインストルメント化されたライブラリを使用しています。これにより、重複するテレメトリーデータを含むネストされたスパンが生成されることがよくあります。例えば：
- Reactor Netty HTTP クライアントのインストルメンテーションによって生成されたスパンには、Netty のインストルメンテーションによって生成された重複する HTTP クライアントスパンが含まれます。
- AWS SDK のインストルメンテーションによって生成された Dynamo DB スパンには、内部の HTTP クライアントライブラリ（これもインストルメント化されている）によって生成された子 HTTP クライアントスパンが含まれます。
- Tomcat のインストルメンテーションによって生成されたスパンには、汎用 Servlet API のインストルメンテーションによって生成された重複する HTTP サーバースパンが含まれます。
javaagent は、重複するテレメトリーデータを含むネストされたスパンを検出して抑制することで、これらの状況を防ぎます。抑制動作は以下の設定オプションで構成できます。
システムプロパティ： otel.instrumentation.experimental.span-suppression-strategy
説明：javaagent のスパン抑制戦略。以下の 3 つの戦略をサポートします。
- `semconv`：エージェントは重複するセマンティック規約を抑制します。これは javaagent のデフォルトの動作です。
- `span-kind`：エージェントは同じ種類（`INTERNAL` を除く）のスパンを抑制します。
- `none`：エージェントは何も抑制しません。デバッグ目的以外での使用は推奨しません。大量の重複テレメトリーデータが生成されるためです。
例えば、内部で Reactor Netty HTTP クライアントを使用するデータベースクライアントをインストルメント化し、その Reactor Netty がさらに Netty を使用しているとします。
デフォルトの semconv 抑制戦略を使用すると、2 つのネストされた CLIENT スパンが生成されます。
CLIENTスパン（データベースクライアントのインストルメンテーションによって発行されたデータベースクライアントのセマンティック属性を持つ）CLIENTスパン（Reactor Netty のインストルメンテーションによって発行された HTTP クライアントのセマンティック属性を持つ） Netty のインストルメンテーションは、Reactor Netty HTTP クライアントのインストルメンテーションを複製するため、抑制されます。
span-kind 抑制戦略を使用すると、1 つのスパンのみが生成されます。
CLIENT スパン（データベースクライアントのインストルメンテーションによって発行されたデータベースクライアントのセマンティック属性を持つ）
Reactor Netty と Netty のインストルメンテーションは、どちらも CLIENT スパンを発行するため、抑制されます。
最後に、none 抑制戦略を使用すると、3 つのスパンが生成されます。
CLIENTスパン（データベースクライアントのインストルメンテーションによって発行されたデータベースクライアントのセマンティック属性を持つ）CLIENTスパン（Reactor Netty のインストルメンテーションによって発行された HTTP クライアントのセマンティック属性を持つ）CLIENTスパン（Netty のインストルメンテーションによって発行された HTTP クライアントのセマンティック属性を持つ）
プロパゲーター（Propagator）設定¶
プロパゲーターは、複数のタイプの APM フレームワーク間でリンクデータを互換性を持たせるために使用されます。パラメータまたは環境変数を使用してプロパゲーターのタイプを調整できます。
-Dotel.propagators：デフォルトのプロパゲーターはtracecontext,baggage(W3C) です。OTEL_PROPAGATORS
現在、以下のタイプのプロパゲーターをサポートしています。
- "tracecontext": W3C Trace Context（W3C baggage を含めるために baggage も追加）
- "baggage": W3C Baggage
- "b3": B3 Single
- "b3multi": B3 Multi
- "jaeger": Jaeger（Jaeger baggage を含む）
- "xray": AWS X-Ray
- "ottrace": OT Trace
プロパゲーターの仕組みについては、ドキュメントリンク伝播（Propagate）の仕組みとユースケースを参照してください。
関数トレーシング¶
コードを変更できない場合、OpenTelemetry は特定のメソッドのスパンをキャプチャするための以下の Java エージェント設定を提供します。
- パラメータ方式：
-Dotel.instrumentation.methods.include - 環境変数方式：
OTEL_INSTRUMENTATION_METHODS_INCLUDE
OpenTelemetry はワイルドカードによる設定をサポートしていないことに注意してください。
例：
-Dotel.instrumentation.methods.include="com.zy.observable.server.service.TestService[users]" は、TestService の users メソッドに APM リンクトレーシングを追加します。
関数の引数トレーシング¶
デフォルトでは、リンクは関数の呼び出し状況を取得できますが、関数の引数情報は取得できません。以下の設定により、関数の引数情報を取得できるようになります。
-Dotel.instrumentation.methods.attribute.enabled、デフォルト値は false です。
レポートプロトコル¶
OpenTelemetry は gRPC、http/protobuf、http/json の 3 つのデータプロトコルをサポートしています。以下の方法でプロトコルを調整できます。
-Dotel.exporter.otlp.protocol=grpcOTEL_EXPORTER_OTLP_PROTOCOL
DataKit は、レポートプロトコルに応じてパラメータ設定が異なります。
# OpenTelemetry gRPC プロトコルで Datakit に送信
-Dotel.exporter=otlp \
-Dotel.exporter.otlp.protocol=grpc \
-Dotel.exporter.otlp.endpoint=http://datakit-endpoint:4317
# http/protobuf 方式を使用
-Dotel.exporter=otlp \
-Dotel.exporter.otlp.protocol=http/protobuf \
-Dotel.exporter.otlp.traces.endpoint=http://datakit-endpoint:9529/otel/v1/trace \
-Dotel.exporter.otlp.metrics.endpoint=http://datakit-endpoint:9529/otel/v1/metric
# http/json 方式を使用
-Dotel.exporter=otlp \
-Dotel.exporter.otlp.protocol=http/json \
-Dotel.exporter.otlp.traces.endpoint=http://datakit-endpoint:9529/otel/v1/trace \
-Dotel.exporter.otlp.metrics.endpoint=http://datakit-endpoint:9529/otel/v1/metric
OpenTelemetry のバージョンによってはレポートプロトコルに差異があるため、手動で設定することを推奨します。