169 lines
12 KiB
Markdown
169 lines
12 KiB
Markdown
## Disabling the agent entirely
|
|
|
|
You can disable the agent using `-Dotel.javaagent.enabled=false`
|
|
(or using the equivalent environment variable `OTEL_JAVAAGENT_ENABLED=false`).
|
|
|
|
## Suppressing specific agent instrumentation
|
|
|
|
You can suppress agent instrumentation of specific libraries by using
|
|
`-Dotel.instrumentation.[name].enabled=false` (or using the equivalent environment
|
|
variable `OTEL_INSTRUMENTATION_[NAME]_ENABLED`) where `name` (`NAME`) is the
|
|
corresponding instrumentation `name`:
|
|
|
|
| Library/Framework | Instrumentation name |
|
|
|--------------------------------------------------|---------------------------|
|
|
| Additional methods tracing | methods |
|
|
| Additional tracing annotations | external-annotations |
|
|
| Akka Actor | akka-actor |
|
|
| Akka HTTP | akka-http |
|
|
| Apache Axis2 | axis2 |
|
|
| Apache Camel | apache-camel |
|
|
| Apache Cassandra | cassandra |
|
|
| Apache CXF | cxf |
|
|
| Apache Dubbo | apache-dubbo |
|
|
| Apache Geode | geode |
|
|
| Apache HttpAsyncClient | apache-httpasyncclient |
|
|
| Apache HttpClient | apache-httpclient |
|
|
| Apache Kafka | kafka |
|
|
| Apache MyFaces | myfaces |
|
|
| Apache RocketMQ | rocketmq-client |
|
|
| Apache Struts 2 | struts |
|
|
| Apache Tapestry | tapestry |
|
|
| Apache Tomcat | tomcat |
|
|
| Apache Wicket | wicket |
|
|
| Armeria | armeria |
|
|
| AsyncHttpClient (AHC) | async-http-client |
|
|
| AWS Lambda | aws-lambda |
|
|
| AWS SDK | aws-sdk |
|
|
| Couchbase | couchbase |
|
|
| Dropwizard Views | dropwizard-views |
|
|
| Eclipse Grizzly | grizzly |
|
|
| Eclipse Jersey | jersey |
|
|
| Eclipse Jetty | jetty |
|
|
| Eclipse Jetty HTTP Client | jetty-httpclient |
|
|
| Eclipse Metro | metro |
|
|
| Eclipse Mojarra | mojarra |
|
|
| Eclipse Vert.x | vertx |
|
|
| Elasticsearch client | elasticsearch-transport |
|
|
| Elasticsearch REST client | elasticsearch-rest |
|
|
| Google Guava | guava |
|
|
| Google HTTP client | google-http-client |
|
|
| Google Web Toolkit | gwt |
|
|
| Grails | grails |
|
|
| GRPC | grpc |
|
|
| Hibernate | hibernate |
|
|
| Java HTTP Client | java-http-client |
|
|
| Java `HttpURLConnection` | http-url-connection |
|
|
| Java JDBC | jdbc |
|
|
| Java JDBC `DataSource` | jdbc-datasource |
|
|
| Java RMI | rmi |
|
|
| Java Servlet | servlet |
|
|
| java.util.concurrent | executor |
|
|
| java.util.logging | java-util-logging |
|
|
| JAX-RS (Client) | jaxrs-client |
|
|
| JAX-RS (Server) | jaxrs |
|
|
| JAX-WS | jaxws |
|
|
| JMS | jms |
|
|
| JSP | jsp |
|
|
| K8s Client | kubernetes-client |
|
|
| kotlinx.coroutines | kotlinx-coroutines |
|
|
| Log4j Appender | log4j-appender |
|
|
| Log4j MDC (1.x) | log4j-mdc |
|
|
| Log4j Context Data (2.x) | log4j-context-data |
|
|
| Logback Appender | logback-appender |
|
|
| Logback MDC | logback-mdc |
|
|
| Micrometer | micrometer |
|
|
| MongoDB | mongo |
|
|
| Netflix Hystrix | hystrix |
|
|
| Netty | netty |
|
|
| OkHttp | okhttp |
|
|
| OpenLiberty | liberty |
|
|
| OpenTelemetry Trace annotations | opentelemetry-annotations |
|
|
| OpenTelemetry API | opentelemetry-api |
|
|
| OSHI (Operating System and Hardware Information) | oshi |
|
|
| Play Framework | play |
|
|
| Play WS HTTP Client | play-ws |
|
|
| Quartz | quartz |
|
|
| RabbitMQ Client | rabbitmq |
|
|
| Ratpack | ratpack |
|
|
| ReactiveX RxJava | rxjava2, rxjava3 |
|
|
| Reactor | reactor |
|
|
| Reactor Netty | reactor-netty |
|
|
| Redis Jedis | jedis |
|
|
| Redis Lettuce | lettuce |
|
|
| Rediscala | rediscala |
|
|
| Redisson | redisson |
|
|
| Restlet | restlet |
|
|
| Scala ForkJoinPool | scala-fork-join |
|
|
| Spark Web Framework | spark |
|
|
| Spring Batch | spring-batch |
|
|
| Spring Core | spring-core |
|
|
| Spring Data | spring-data |
|
|
| Spring Integration | spring-integration |
|
|
| Spring Kafka | spring-kafka |
|
|
| Spring RabbitMQ | spring-rabbit |
|
|
| Spring RMI | spring-rmi |
|
|
| Spring Scheduling | spring-scheduling |
|
|
| Spring Web | spring-web |
|
|
| Spring WebFlux | spring-webflux |
|
|
| Spring Web MVC | spring-webmvc |
|
|
| Spring Web Services | spring-ws |
|
|
| Spymemcached | spymemcached |
|
|
| Twilio SDK | twilio |
|
|
| Twitter Finatra | finatra |
|
|
| Undertow | undertow |
|
|
| Vaadin | vaadin |
|
|
|
|
**Note:** When using environment variables, dashes (`-`) should be converted to
|
|
underscores (`_`). For example, to suppress traces from `akka-actor` library, set
|
|
`OTEL_INSTRUMENTATION_AKKA_ACTOR_ENABLED` to `false`.
|
|
|
|
### Even more fine-grained control
|
|
|
|
You can also exclude specific classes from being instrumented.
|
|
|
|
This can be useful to completely silence spans from a given class/package.
|
|
|
|
Or as a quick workaround for an instrumentation bug, when byte code in one specific class is problematic.
|
|
|
|
This option should not be used lightly, as it can leave some instrumentation partially applied,
|
|
which could have unknown side-effects.
|
|
|
|
If you find yourself needing to use this, it would be great if you could drop us an issue explaining why,
|
|
so that we can try to come up with a better solution to address your need.
|
|
|
|
| System property | Environment variable | Purpose |
|
|
|--------------------------------|--------------------------------|---------------------------------------------------------------------------------------------------|
|
|
| otel.javaagent.exclude-classes | OTEL_JAVAAGENT_EXCLUDE_CLASSES | Suppresses all instrumentation for specific classes, format is "my.package.MyClass,my.package2.*" |
|
|
|
|
## Enable manual instrumentation only
|
|
|
|
You can suppress all auto instrumentations but have support for manual instrumentation with `@WithSpan` and normal API interactions by using
|
|
`-Dotel.instrumentation.common.default-enabled=false -Dotel.instrumentation.opentelemetry-annotations.enabled=true`
|
|
|
|
## Enable instrumentation suppression by type
|
|
|
|
Some of the libraries that this agent instruments in turn use lower-level libraries, that are also instrumented.
|
|
This results in nested `CLIENT` spans (a span with the kind `CLIENT` has a child span with the same kind `CLIENT`).
|
|
For example spans produced by Reactor Netty instrumentation will have children spans produced by Netty instrumentation.
|
|
Or Dynamo DB spans produced by AWS SDK instrumentation will have children spans produced by http protocol library instrumentation.
|
|
|
|
Although OpenTelemetry specification allows such situation, such nested spans often produce duplicate data without any added benefit.
|
|
For this reason this agent by default suppresses nested `CLIENT` spans and emits only the top-level one.
|
|
|
|
By setting `-Dotel.instrumentation.experimental.outgoing-span-suppression-by-type=true` you can enable a more sophisticated suppression strategy: only `CLIENT` spans of the same semantic convention type (e.g. DB, HTTP, RPC) will be suppressed.
|
|
For example, if we have a database client which uses Reactor Netty http client which uses Netty networking library, then without any suppression we would have 3 nested spans:
|
|
|
|
- `CLIENT` span with database semantic attributes from the database client instrumentation
|
|
- `CLIENT` span with http semantic attributes from Reactor Netty instrumentation
|
|
- `CLIENT` span with http semantic attributes from Netty instrumentation
|
|
|
|
With default suppression, we would have 1 span:
|
|
|
|
- `CLIENT` span with database semantic attributes from the database client instrumentation
|
|
|
|
With suppression by type, we would have 2 nested spans:
|
|
|
|
- `CLIENT` span with database semantic attributes from the database client instrumentation
|
|
- `CLIENT` span with http semantic attributes from Reactor Netty instrumentation
|