Suppressing specific instrumentation

Disabling the agent entirely

Enable only specific instrumentation

You can disable all default auto instrumentation and selectively re-enable individual instrumentation. This may be desirable to reduce startup overhead or to have more control of which instrumentation is applied.

Note: Some instrumentation relies on other instrumentation to function properly. When selectively enabling instrumentation, be sure to enable the transitive dependencies too. Determining this dependency relationship is left as an exercise to the user.

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-api.enabled=true -Dotel.instrumentation.opentelemetry-instrumentation-annotations.enabled=true

Suppressing specific agent instrumentation

You can suppress agent instrumentation of specific libraries.

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.

Suppressing controller and/or view spans

Some instrumentations (e.g. Spring Web MVC instrumentation) produce SpanKind.Internal spans to capture the controller and/or view execution. These spans can be suppressed using the configuration settings below, without suppressing the entire instrumentation which would also disable the instrumentation’s capturing of http.route and associated span name on the parent SpanKind.Server span.

Instrumentation span suppression behavior

Some libraries that this agent instruments in turn use lower-level libraries, that are also instrumented. This would normally result in nested spans containing duplicate telemetry data. For example:

• Spans produced by the Reactor Netty HTTP client instrumentation would have duplicate HTTP client spans produced by the Netty instrumentation;
• Dynamo DB spans produced by the AWS SDK instrumentation would have children HTTP client spans produced by its internal HTTP client library (which is also instrumented);
• Spans produced by the Tomcat instrumentation would have duplicate HTTP server spans produced by the generic Servlet API instrumentation.

The Java agent prevents these situations by detecting and suppressing nested spans that duplicate telemetry data. The suppression behavior can be configured using the following configuration option:

For example, suppose we instrument a database client which internally uses the Reactor Netty HTTP client; which in turn uses Netty.

Using the default semconv suppression strategy would result in 2 nested CLIENT spans:

• CLIENT span with database client semantic attributes emitted by the database client instrumentation;
• CLIENT span with HTTP client semantic attributes emitted by the Reactor Netty instrumentation.

The Netty instrumentation would be suppressed, as it duplicates the Reactor Netty HTTP client instrumentation.

Using the suppression strategy span-kind would result in just one span:

• CLIENT span with database client semantic attributes emitted by the database client instrumentation.

Both Reactor Netty and Netty instrumentations would be suppressed, as they also emit CLIENT spans.

Finally, using the suppression strategy none would result in 3 spans:

• CLIENT span with database client semantic attributes emitted by the database client instrumentation;
• CLIENT span with HTTP client semantic attributes emitted by the Reactor Netty instrumentation;
• CLIENT span with HTTP client semantic attributes emitted by the Netty instrumentation.