禁用特定插桩

完全禁用代理

System property: otel.javaagent.enabledEnvironment variable: OTEL_JAVAAGENT_ENABLED

Description: 将值设置为 false 可完全禁用代理。

仅启用特定插桩

你可以禁用所有默认的自动插桩,并有选择地重新启用单个插桩。 这可能有助于减少启动开销,或更好地控制要应用哪些插桩。

System property: otel.instrumentation.common.default-enabledEnvironment variable: OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED

Description: 设置为 false 以禁用代理中的所有插桩。

System property: otel.instrumentation.[name].enabledEnvironment variable: OTEL_INSTRUMENTATION_[NAME]_ENABLED

Description: 设置为 true 以单独启用每个所需的插桩。

仅启用手动插桩

你可以通过使用 -Dotel.instrumentation.common.default-enabled=false -Dotel.instrumentation.opentelemetry-api.enabled=true -Dotel.instrumentation.opentelemetry-instrumentation-annotations.enabled=true 来禁用所有自动插桩,但保留对带有 @WithSpan 的手动插桩和正常 API 交互的支持。

禁用特定代理插桩

你可以禁用代理对特定库的插桩。

System property: otel.instrumentation.[name].enabledEnvironment variable: OTEL_INSTRUMENTATION_[NAME]_ENABLED

Description: 设置为 false 以禁用代理对特定库的插桩,其中 [name] 是相应的插桩名称:

库 / 框架插桩名称
Additional methods tracingmethods
Additional tracing annotationsexternal-annotations
Activej HTTPactivej-http
Avaje Jexavaje-jex
Akka Actorakka-actor
Akka HTTPakka-http
Alibaba Druidalibaba-druid
Apache Axis2axis2
Apache Camelcamel
Apache Cassandracassandra
Apache CXFcxf
Apache DBCPapache-dbcp
Apache Dubboapache-dubbo
Apache Geodegeode
Apache HttpAsyncClientapache-httpasyncclient
Apache HttpClientapache-httpclient
Apache Kafkakafka
Apache MyFacesjsf-myfaces
Apache Pekko Actorpekko-actor
Apache Pekko HTTPpekko-http
Apache Pulsarpulsar
Apache RocketMQrocketmq-client
Apache Shenyuapache-shenyu
Apache Struts 2struts
Apache Tapestrytapestry
Apache Tomcattomcat
Apache Wicketwicket
Armeriaarmeria
AsyncHttpClient (AHC)async-http-client
AWS Lambdaaws-lambda
AWS SDKaws-sdk
Azure SDKazure-core
Clickhouse Clientclickhouse
Couchbasecouchbase
C3P0c3p0
Dropwizard Viewsdropwizard-views
Dropwizard Metricsdropwizard-metrics
Eclipse Grizzlygrizzly
Eclipse Jerseyjersey
Eclipse Jettyjetty
Eclipse Jetty HTTP Clientjetty-httpclient
Eclipse Metrometro
Eclipse Mojarrajsf-mojarra
Eclipse Vert.x HttpClientvertx-http-client
Eclipse Vert.x Kafka Clientvertx-kafka-client
Eclipse Vert.x Redis Clientvertx-redis-client
Eclipse Vert.x RxJavavertx-rx-java
Eclipse Vert.x SQL Clientvertx-sql-client
Eclipse Vert.x Webvertx-web
Elasticsearch API clientelasticsearch-api-client
Elasticsearch clientelasticsearch-transport
Elasticsearch REST clientelasticsearch-rest
Finaglefinagle-http
Google Guavaguava
Google HTTP clientgoogle-http-client
Google Web Toolkitgwt
Grailsgrails
GraphQL Javagraphql-java
GRPCgrpc
Hibernatehibernate
Hibernate Reactivehibernate-reactive
HikariCPhikaricp
InfluxDBinfluxdb
Java HTTP Clientjava-http-client
Java HTTP Serverjava-http-server
Java HttpURLConnectionhttp-url-connection
Java JDBCjdbc
Java JDBC DataSourcejdbc-datasource
Java RMIrmi
Java Runtimeruntime-telemetry
Java Servletservlet
java.util.concurrentexecutors
java.util.loggingjava-util-logging
Javalinjavalin
JAX-RS (Client)jaxrs-client
JAX-RS (Server)jaxrs
JAX-WSjaxws
JBoss Logging Appenderjboss-logmanager-appender
JBoss Logging MDCjboss-logmanager-mdc
JMSjms
Jodd HTTPjodd-http
JSPjsp
K8s Clientkubernetes-client
Ktorktor
kotlinx.coroutineskotlinx-coroutines
Log4j Appenderlog4j-appender
Log4j MDC (1.x)log4j-mdc
Log4j Context Data (2.x)log4j-context-data
Logback Appenderlogback-appender
Logback MDClogback-mdc
Micrometermicrometer
MongoDBmongo
MyBatismybatis
Netflix Hystrixhystrix
Nettynetty
OkHttpokhttp
OpenLibertyliberty
OpenAIopenai
OpenSearch RESTopensearch-rest
OpenTelemetry Extension Annotationsopentelemetry-extension-annotations
OpenTelemetry Instrumentation Annotationsopentelemetry-instrumentation-annotations
OpenTelemetry APIopentelemetry-api
Oracle UCPoracle-ucp
OSHI (Operating System and Hardware Information)oshi
Payarapayara
Play Frameworkplay
Play WS HTTP Clientplay-ws
Powerjobpowerjob
Quarkusquarkus
Quartzquartz
R2DBCr2dbc
RabbitMQ Clientrabbitmq
Ratpackratpack
ReactiveX RxJavarxjava
Reactorreactor
Reactor Kafkareactor-kafka
Reactor Nettyreactor-netty
Redis Jedisjedis
Redis Lettucelettuce
Rediscalarediscala
Redissonredisson
Restletrestlet
Scala ForkJoinPoolscala-fork-join
Spark Web Frameworkspark
Spring Batchspring-batch
Spring Boot Actuator Autoconfigurespring-boot-actuator-autoconfigure
Spring Cloud AWSspring-cloud-aws
Spring Cloud Gatewayspring-cloud-gateway
Spring Corespring-core
Spring Dataspring-data
Spring JMSspring-jms
Spring Integrationspring-integration
Spring Kafkaspring-kafka
Spring Pulsarspring-pulsar
Spring RabbitMQspring-rabbit
Spring RMIspring-rmi
Spring Schedulingspring-scheduling
Spring Security Configspring-security-config
Spring Webspring-web
Spring WebFluxspring-webflux
Spring Web MVCspring-webmvc
Spring Web Servicesspring-ws
Spymemcachedspymemcached
Tomcat JDBCtomcat-jdbc
Twilio SDKtwilio
Twitter Finatrafinatra
Undertowundertow
Vaadinvaadin
Vibur DBCPvibur-dbcp
XXL-JOBxxl-job
ZIOzio

注意: 使用环境变量时,破折号(-)应转换为下划线(_)。 例如,要禁用来自 akka-actor 库的跟踪,请将 OTEL_INSTRUMENTATION_AKKA_ACTOR_ENABLED 设置为 false

禁用控制器视图 Span

某些插桩(例如 Spring Web MVC 插桩)会生成 SpanKind.Internal Span 来捕获控制器、视图的执行情况。 可以使用以下配置设置来禁用这些 Span,而无需禁用整个插桩, 禁用整个插桩还会取消该插桩对父级 SpanKind.Server Span 上 http.route 和相关 Span 名称的捕获。

System property: otel.instrumentation.common.experimental.controller-telemetry.enabledEnvironment variable: OTEL_INSTRUMENTATION_COMMON_EXPERIMENTAL_CONTROLLER_TELEMETRY_ENABLED

Default: false
Description: 设置为 true 以启用控制器遥测。

System property: otel.instrumentation.common.experimental.view-telemetry.enabledEnvironment variable: OTEL_INSTRUMENTATION_COMMON_EXPERIMENTAL_VIEW_TELEMETRY_ENABLED

Default: false
Description: 设置为 true 以启用视图遥测。

插桩 Span 禁用行为

此代理所插桩的某些库会转而使用更低级别的库,而这些更低级别的库也会被插桩。 这通常会导致嵌套的 Span 包含重复的遥测数据。例如:

  • Reactor Netty HTTP 客户端插桩产生的 Span 会与 Netty 插桩产生的 HTTP 客户端 Span 重复;
  • AWS SDK 插桩产生的 Dynamo DB Span 会包含由其内部 HTTP 客户端库(该库也会被插桩)产生的子 HTTP 客户端 Span;
  • Tomcat 插桩产生的 Span 会与通用 Servlet API 插桩产生的 HTTP 服务器 Span 重复。

Java 代理通过检测并禁用包含重复遥测数据的嵌套 Span 来防止这些情况。 可以使用以下配置选项配置禁用行为:

System property: otel.instrumentation.experimental.span-suppression-strategyEnvironment variable: OTEL_INSTRUMENTATION_EXPERIMENTAL_SPAN_SUPPRESSION_STRATEGY

Description: Java 代理的 Span 禁用策略。支持以下 3 种策略:

  • semconv:代理将禁用重复的语义约定。这是 Java 代理的默认行为。
  • span-kind:代理将禁用相同类型的 Span(除了 INTERNAL)。
  • none:代理将根本不禁用任何内容。我们不建议使用此选项进行除调试以外的任何其他用途,因为它会生成大量重复的遥测数据

例如,假设我们对一个数据库客户端进行插桩,该客户端在内部使用 Reactor Netty HTTP 客户端; 而 Reactor Netty HTTP 客户端又会使用 Netty。

使用默认的 semconv 禁用策略将导致 2 个嵌套的 CLIENT Span:

  • 由数据库客户端插桩发出的具有数据库客户端语义属性的 CLIENT Span;
  • 由 Reactor Netty 插桩发出的具有 HTTP 客户端语义属性的 CLIENT Span;

Netty 插桩会被禁用,因为它会重复 Reactor Netty HTTP 客户端插桩。

使用 span-kind 禁用策略将仅产生 1 个 CLIENT Span:

  • 由数据库客户端插桩发出的具有数据库客户端语义属性的 CLIENT Span;

Reactor Netty 和 Netty 插桩都会被禁用,因为它们也会发出 CLIENT Span。

最后,使用 none 禁用策略将产生 3 个 CLIENT Span:

  • 由数据库客户端插桩发出的具有数据库客户端语义属性的 CLIENT Span;
  • 由 Reactor Netty 插桩发出的具有 HTTP 客户端语义属性的 CLIENT Span;
  • 由 Netty 插桩发出的具有 HTTP 客户端语义属性的 CLIENT Span;