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
Agent 비활성화¶
기본적으로 활성화되어 있습니다. 비활성화하려면 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를 활성화하면 로그가 콘솔과 애플리케이션에 구성된 로그 파일(애플리케이션이 로그 파일 출력을 구성한 경우)에 출력됩니다.
데이터베이스 마스킹¶
Agent는 db.statement 의미 체계 속성을 설정하기 전에 모든 데이터베이스 쿼리/문을 정리합니다. 쿼리 문자열의 모든 값(문자열, 숫자)은 물음표(?)로 대체됩니다.
참고: JDBC 바인드 매개변수는 db.statement에 포함되지 않습니다. 바인드 매개변수를 캡처하려는 경우 해당 이슈를 참조하세요.
예:
- 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 전략을 활성화하는 것을 권장합니다.
이 Agent가 계측하는 일부 라이브러리는 내부적으로 역시 계측된 하위 수준 라이브러리를 사용합니다. 이로 인해 일반적으로 중복 텔레메트리 데이터를 포함하는 중첩 스팬이 발생합니다. 예:
- 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`: Agent가 중복된 의미 체계 규칙을 억제합니다. 이것이 javaagent의 기본 동작입니다.
- `span-kind`: Agent가 동일한 유형(`INTERNAL` 제외)의 스팬을 억제합니다.
- `none`: Agent가 아무것도 억제하지 않습니다. 디버깅 목적 이외에는 이 옵션을 사용하지 않는 것이 좋습니다. 많은 양의 중복 텔레메트리 데이터가 생성되기 때문입니다.
예를 들어, 내부적으로 Reactor Netty HTTP 클라이언트를 사용하는 데이터베이스 클라이언트를 계측한다고 가정해 보겠습니다. 이 클라이언트는 다시 Netty를 사용합니다.
기본 semconv 억제 전략을 사용하면 2개의 중첩 CLIENT 스팬이 생성됩니다.
- 데이터베이스 클라이언트 계측에서 내보낸 데이터베이스 클라이언트 의미 체계 속성을 가진
CLIENT스팬. - Reactor Netty 계측에서 내보낸 HTTP 클라이언트 의미 체계 속성을 가진
CLIENT스팬. Netty 계측은 Reactor Netty HTTP 클라이언트 계측을 복제하므로 억제됩니다.
span-kind 억제 전략을 사용하면 하나의 스팬만 생성됩니다.
데이터베이스 클라이언트 계측에서 내보낸 데이터베이스 클라이언트 의미 체계 속성을 가진 CLIENT 스팬.
Reactor Netty와 Netty 계측은 모두 CLIENT 스팬을 내보내므로 억제됩니다.
마지막으로, none 억제 전략을 사용하면 3개의 스팬이 생성됩니다.
- 데이터베이스 클라이언트 계측에서 내보낸 데이터베이스 클라이언트 의미 체계 속성을 가진
CLIENT스팬. - Reactor Netty 계측에서 내보낸 HTTP 클라이언트 의미 체계 속성을 가진
CLIENT스팬. - Netty 계측에서 내보낸 HTTP 클라이언트 의미 체계 속성을 가진
CLIENT스팬.
프로파게이터(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 Agent를 구성하는 다음 방법을 제공합니다.
- 매개변수 방식:
-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. 다음 방법을 통해 프로토콜을 조정할 수 있습니다.
-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의 일부 버전에서는 전송 프로토콜에 차이가 있으므로 수동으로 구성하는 것이 좋습니다.