re-organize agent config (#4811)
Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com> Co-authored-by: Patrice Chalin <pchalin@gmail.com> Co-authored-by: Severin Neumann <neumanns@cisco.com>
This commit is contained in:
Gregor Zeitlinger
GitHub
parent
ec1824d4d4
commit
94b83c9010
|
|
@ -260,5 +260,5 @@ COPY opentelemetry_module.conf /etc/nginx/conf.d
|
|||
[v1.0.1 release of the otel-webserver-module]:
|
||||
https://github.com/open-telemetry/opentelemetry-cpp-contrib/releases/tag/webserver%2Fv1.0.1
|
||||
[java]:
|
||||
/docs/zero-code/java/agent/configuration/#capturing-http-request-and-response-headers
|
||||
/docs/zero-code/java/agent/instrumentation/http/#capturing-http-request-and-response-headers
|
||||
[python]: /docs/zero-code/python/
|
||||
|
|
|
|||
|
|
@ -56,7 +56,7 @@ variables:
|
|||
instrumentations, see [Suppressing specific agent instrumentation][1].
|
||||
|
||||
[1]:
|
||||
/docs/zero-code/java/agent/configuration/#suppressing-specific-agent-instrumentation
|
||||
/docs/zero-code/java/agent/disable/#suppressing-specific-agent-instrumentation
|
||||
|
||||
For example, to only enable auto-instrumentation for Lambda and the AWS SDK, you
|
||||
would set the following environment variables:
|
||||
|
|
|
|||
|
|
@ -212,7 +212,7 @@ Therefore, the example uses `http://demo-collector:4318`, which connects to the
|
|||
#### Excluding auto-instrumentation {#java-excluding-auto-instrumentation}
|
||||
|
||||
By default, the Java auto-instrumentation ships with
|
||||
[many instrumentation libraries](/docs/zero-code/java/agent/#supported-libraries-frameworks-application-services-and-jvms).
|
||||
[many instrumentation libraries](/docs/zero-code/java/agent/getting-started/#supported-libraries-frameworks-application-services-and-jvms).
|
||||
This makes instrumentation easy, but could result in too much or unwanted data.
|
||||
If there are any libraries you do not want to use you can set the
|
||||
`OTEL_INSTRUMENTATION_[NAME]_ENABLED=false` where `[NAME]` is the name of the
|
||||
|
|
@ -221,7 +221,7 @@ the default libraries by setting
|
|||
`OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED=false` and then use
|
||||
`OTEL_INSTRUMENTATION_[NAME]_ENABLED=true` where `[NAME]` is the name of the
|
||||
library. For more details, see
|
||||
[Suppressing specific instrumentation](/docs/zero-code/java/agent/configuration/#suppressing-specific-instrumentation).
|
||||
[Suppressing specific instrumentation](/docs/zero-code/java/agent/disable/).
|
||||
|
||||
```yaml
|
||||
apiVersion: opentelemetry.io/v1alpha1
|
||||
|
|
|
|||
|
|
@ -248,7 +248,7 @@ For more:
|
|||
[metrics]: /docs/concepts/signals/metrics/
|
||||
[logs]: /docs/concepts/signals/logs/
|
||||
[annotations]: /docs/zero-code/java/agent/annotations/
|
||||
[configure the java agent]: /docs/zero-code/java/agent/#configuring-the-agent
|
||||
[configure the java agent]: /docs/zero-code/java/agent/configuration/
|
||||
[console exporter]:
|
||||
https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/README.md#logging-exporter
|
||||
[exporter]:
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ in order to generate telemetry data for a library or framework.
|
|||
The Java agent for automatic instrumentation includes instrumentation libraries
|
||||
for many common Java frameworks. Most are turned on by default. If you need to
|
||||
turn off certain instrumentation libraries, you can
|
||||
[suppress them](/docs/zero-code/java/agent/configuration/#suppressing-specific-instrumentation).
|
||||
[suppress them](/docs/zero-code/java/agent/disable/).
|
||||
|
||||
If you use [code-based instrumentation](../instrumentation), you can leverage
|
||||
some instrumentation libraries for your dependencies standalone. To find out
|
||||
|
|
|
|||
|
|
@ -5,7 +5,6 @@ aliases:
|
|||
- /docs/java/automatic_instrumentation
|
||||
- /docs/languages/java/automatic_instrumentation
|
||||
redirects: [{ from: /docs/languages/java/automatic/*, to: ':splat' }]
|
||||
cSpell:ignore: Dotel myapp
|
||||
---
|
||||
|
||||
Zero-code instrumentation with Java uses a Java agent JAR attached to any Java
|
||||
|
|
@ -14,97 +13,3 @@ popular libraries and frameworks. It can be used to capture telemetry data at
|
|||
the "edges" of an app or service, such as inbound requests, outbound HTTP calls,
|
||||
database calls, and so on. To learn how to manually instrument your service or
|
||||
app code, see [Manual instrumentation](/docs/languages/java/instrumentation/).
|
||||
|
||||
## Setup
|
||||
|
||||
1. Download [opentelemetry-javaagent.jar][] from [Releases][] of the
|
||||
`opentelemetry-java-instrumentation` repository and place the JAR in your
|
||||
preferred directory. The JAR file contains the agent and instrumentation
|
||||
libraries.
|
||||
2. Add `-javaagent:path/to/opentelemetry-javaagent.jar` and other config to
|
||||
your JVM startup arguments and launch your app:
|
||||
|
||||
- Directly on the startup command:
|
||||
|
||||
```shell
|
||||
java -javaagent:path/to/opentelemetry-javaagent.jar -Dotel.service.name=your-service-name -jar myapp.jar
|
||||
```
|
||||
|
||||
- Via the `JAVA_TOOL_OPTIONS` and other environment variables:
|
||||
|
||||
```shell
|
||||
export JAVA_TOOL_OPTIONS="-javaagent:path/to/opentelemetry-javaagent.jar"
|
||||
export OTEL_SERVICE_NAME="your-service-name"
|
||||
java -jar myapp.jar
|
||||
```
|
||||
|
||||
## Configuring the agent
|
||||
|
||||
The agent is highly configurable.
|
||||
|
||||
One option is to pass configuration properties via the `-D` flag. In this
|
||||
example, a service name and Zipkin exporter for traces are configured:
|
||||
|
||||
```sh
|
||||
java -javaagent:path/to/opentelemetry-javaagent.jar \
|
||||
-Dotel.service.name=your-service-name \
|
||||
-Dotel.traces.exporter=zipkin \
|
||||
-jar myapp.jar
|
||||
```
|
||||
|
||||
You can also use environment variables to configure the agent:
|
||||
|
||||
```sh
|
||||
OTEL_SERVICE_NAME=your-service-name \
|
||||
OTEL_TRACES_EXPORTER=zipkin \
|
||||
java -javaagent:path/to/opentelemetry-javaagent.jar \
|
||||
-jar myapp.jar
|
||||
```
|
||||
|
||||
You can also supply a Java properties file and load configuration values from
|
||||
there:
|
||||
|
||||
```sh
|
||||
java -javaagent:path/to/opentelemetry-javaagent.jar \
|
||||
-Dotel.javaagent.configuration-file=path/to/properties/file.properties \
|
||||
-jar myapp.jar
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```sh
|
||||
OTEL_JAVAAGENT_CONFIGURATION_FILE=path/to/properties/file.properties \
|
||||
java -javaagent:path/to/opentelemetry-javaagent.jar \
|
||||
-jar myapp.jar
|
||||
```
|
||||
|
||||
To see the full range of configuration options, see
|
||||
[Agent Configuration](configuration).
|
||||
|
||||
## Supported libraries, frameworks, application services, and JVMs
|
||||
|
||||
The Java agent ships with instrumentation libraries for many popular components.
|
||||
For the full list, see [Supported libraries, frameworks, application services,
|
||||
and JVMs][support].
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
{{% config_option name="otel.javaagent.debug" %}}
|
||||
|
||||
Set to `true` to see debug logs. Note that these are quite verbose.
|
||||
|
||||
{{% /config_option %}}
|
||||
|
||||
## Next steps
|
||||
|
||||
After you have automatic instrumentation configured for your app or service, you
|
||||
might want to [annotate](annotations) selected methods or add
|
||||
[manual instrumentation](/docs/languages/java/instrumentation/) to collect
|
||||
custom telemetry data.
|
||||
|
||||
[opentelemetry-javaagent.jar]:
|
||||
https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
|
||||
[releases]:
|
||||
https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases
|
||||
[support]:
|
||||
https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md
|
||||
|
|
|
|||
|
|
@ -1,60 +1,24 @@
|
|||
---
|
||||
title: Agent Configuration
|
||||
linkTitle: Configuration
|
||||
title: Configuration
|
||||
weight: 10
|
||||
aliases: [agent-config]
|
||||
# prettier-ignore
|
||||
cSpell:ignore: akka armeria classloaders couchbase Customizer datasource dbcp Dotel dropwizard dubbo enduser finatra hikari hikaricp HSET httpasyncclient httpclient hystrix jaxrs jaxws jedis jodd kotlinx logback logmanager mojarra myfaces okhttp oshi pekko rabbitmq ratpack rediscala redisson restlet rocketmq serverlessapis spymemcached twilio vaadin vertx vibur webflux webmvc
|
||||
---
|
||||
|
||||
## SDK Autoconfiguration
|
||||
|
||||
The SDK's autoconfiguration module is used for basic configuration of the agent.
|
||||
Read the [docs](/docs/languages/java/configuration) to find settings such as
|
||||
configuring export or sampling.
|
||||
|
||||
{{% alert title="Important" color="warning" %}}
|
||||
|
||||
Unlike the SDK autoconfiguration, versions 2.0+ of the Java agent and
|
||||
OpenTelemetry Spring Boot starter use `http/protobuf` as the default protocol,
|
||||
not `grpc`.
|
||||
|
||||
{{% /alert %}}
|
||||
|
||||
### Enable Resource Providers that are disabled by default
|
||||
|
||||
In addition to the resource configuration from the SDK autoconfiguration, you
|
||||
can enable additional resource providers that are disabled by default:
|
||||
|
||||
{{% config_option
|
||||
name="otel.resource.providers.aws.enabled"
|
||||
default=false
|
||||
%}} Enables the
|
||||
[AWS Resource Provider](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/aws-resources).
|
||||
{{% /config_option %}}
|
||||
|
||||
{{% config_option
|
||||
name="otel.resource.providers.gcp.enabled"
|
||||
default=false
|
||||
%}} Enables the
|
||||
[GCP Resource Provider](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/gcp-resources).
|
||||
{{% /config_option %}}
|
||||
|
||||
## Configuring the agent
|
||||
## Agent Configuration
|
||||
|
||||
The agent can consume configuration from one or more of the following sources
|
||||
(ordered from highest to lowest priority):
|
||||
|
||||
- system properties
|
||||
- [environment variables](#configuring-with-environment-variables)
|
||||
- the [configuration file](#configuration-file)
|
||||
- properties provided by the
|
||||
- System properties
|
||||
- [Environment variables](#configuring-with-environment-variables)
|
||||
- [Configuration file](#configuration-file)
|
||||
- Properties provided by the
|
||||
[`AutoConfigurationCustomizer#addPropertiesSupplier()`](https://github.com/open-telemetry/opentelemetry-java/blob/f92e02e4caffab0d964c02a32fe305d6d6ba372e/sdk-extensions/autoconfigure-spi/src/main/java/io/opentelemetry/sdk/autoconfigure/spi/AutoConfigurationCustomizer.java#L73)
|
||||
function; using the
|
||||
[`AutoConfigurationCustomizerProvider`](https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure-spi/src/main/java/io/opentelemetry/sdk/autoconfigure/spi/AutoConfigurationCustomizerProvider.java)
|
||||
SPI
|
||||
|
||||
### Configuring with Environment Variables
|
||||
## Configuring with Environment Variables
|
||||
|
||||
In some environments, configuring via Environment Variables is more preferred.
|
||||
Any setting configurable with a System Property can also be configured with an
|
||||
|
|
@ -68,7 +32,7 @@ desired System Property:
|
|||
For example `otel.instrumentation.common.default-enabled` would convert to
|
||||
`OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED`.
|
||||
|
||||
### Configuration file
|
||||
## Configuration file
|
||||
|
||||
You can provide a path to agent configuration file by setting the following
|
||||
property:
|
||||
|
|
@ -77,7 +41,7 @@ property:
|
|||
Java properties file which contains the agent configuration.
|
||||
{{% /config_option %}}
|
||||
|
||||
### Extensions
|
||||
## Extensions
|
||||
|
||||
You can enable [extensions][] by setting the following property:
|
||||
|
||||
|
|
@ -89,7 +53,7 @@ extension.
|
|||
|
||||
{{% /config_option %}}
|
||||
|
||||
### Java agent logging output
|
||||
## Java agent logging output
|
||||
|
||||
The agent's logging output can be configured by setting the following property:
|
||||
|
||||
|
|
@ -111,484 +75,38 @@ The Java agent logging mode. The following 3 modes are supported:
|
|||
|
||||
{{% /config_option %}}
|
||||
|
||||
## Common instrumentation configuration
|
||||
## SDK Configuration
|
||||
|
||||
Common settings that apply to multiple instrumentations at once.
|
||||
The SDK's autoconfiguration module is used for basic configuration of the agent.
|
||||
Read the [docs](/docs/languages/java/configuration) to find settings such as
|
||||
configuring export or sampling.
|
||||
|
||||
### Peer service name
|
||||
{{% alert title="Important" color="warning" %}}
|
||||
|
||||
The
|
||||
[peer service name](/docs/specs/semconv/general/attributes/#general-remote-service-attributes)
|
||||
is the name of a remote service to which a connection is made. It corresponds to
|
||||
`service.name` in the [resource](/docs/specs/semconv/resource/#service) for the
|
||||
local service.
|
||||
Unlike the SDK autoconfiguration, versions 2.0+ of the Java agent and
|
||||
OpenTelemetry Spring Boot starter use `http/protobuf` as the default protocol,
|
||||
not `grpc`.
|
||||
|
||||
{{% config_option name="otel.instrumentation.common.peer-service-mapping" %}}
|
||||
{{% /alert %}}
|
||||
|
||||
Used to specify a mapping from host names or IP addresses to peer services, as a
|
||||
comma-separated list of `<host_or_ip>=<user_assigned_name>` pairs. The peer
|
||||
service is added as an attribute to a span whose host or IP address match the
|
||||
mapping.
|
||||
## Enable Resource Providers that are disabled by default
|
||||
|
||||
For example, if set to the following:
|
||||
|
||||
1.2.3.4=cats-service,dogs-abcdef123.serverlessapis.com=dogs-api
|
||||
|
||||
Then, requests to `1.2.3.4` will have a `peer.service` attribute of
|
||||
`cats-service` and requests to `dogs-abcdef123.serverlessapis.com` will have an
|
||||
attribute of `dogs-api`.
|
||||
|
||||
Since Java agent version `1.31.0`, it is possible to provide a port and a path
|
||||
to define a `peer.service`.
|
||||
|
||||
For example, if set to the following:
|
||||
|
||||
1.2.3.4:443=cats-service,dogs-abcdef123.serverlessapis.com:80/api=dogs-api
|
||||
|
||||
Then, requests to `1.2.3.4` will have no override for `peer.service` attribute,
|
||||
while `1.2.3.4:443` will have have `peer.service` of `cats-service` and requests
|
||||
to `dogs-abcdef123.serverlessapis.com:80/api/v1` will have an attribute of
|
||||
`dogs-api`.
|
||||
|
||||
{{% /config_option %}}
|
||||
|
||||
### DB statement sanitization
|
||||
|
||||
The agent sanitizes all database queries/statements before setting the
|
||||
`db.statement` semantic attribute. All values (strings, numbers) in the query
|
||||
string are replaced with a question mark (`?`).
|
||||
|
||||
Note: JDBC bind parameters are not captured in `db.statement`. See
|
||||
[the corresponding issue](https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues/7413)
|
||||
if you are looking to capture bind parameters.
|
||||
|
||||
Examples:
|
||||
|
||||
- SQL query `SELECT a from b where password="secret"` will appear as
|
||||
`SELECT a from b where password=?` in the exported span;
|
||||
- Redis command `HSET map password "secret"` will appear as
|
||||
`HSET map password ?` in the exported span.
|
||||
|
||||
This behavior is turned on by default for all database instrumentations. Use the
|
||||
following property to disable it:
|
||||
In addition to the resource configuration from the SDK autoconfiguration, you
|
||||
can enable additional resource providers that are disabled by default:
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.common.db-statement-sanitizer.enabled"
|
||||
default=true
|
||||
%}} Enables the DB statement sanitization. {{% /config_option %}}
|
||||
|
||||
### HTTP instrumentation configuration
|
||||
|
||||
#### Capturing HTTP request and response headers
|
||||
|
||||
You can configure the agent to capture predefined HTTP headers as span
|
||||
attributes, according to the
|
||||
[semantic convention](/docs/specs/semconv/http/http-spans/). Use the following
|
||||
properties to define which HTTP headers you want to capture:
|
||||
|
||||
{{% config_option name="otel.instrumentation.http.client.capture-request-headers" %}}
|
||||
A comma-separated list of HTTP header names. HTTP client instrumentations will
|
||||
capture HTTP request header values for all configured header names.
|
||||
{{% /config_option %}}
|
||||
|
||||
{{% config_option name="otel.instrumentation.http.client.capture-response-headers" %}}
|
||||
A comma-separated list of HTTP header names. HTTP client instrumentations will
|
||||
capture HTTP response header values for all configured header names.
|
||||
{{% /config_option %}}
|
||||
|
||||
{{% config_option name="otel.instrumentation.http.server.capture-request-headers" %}}
|
||||
A comma-separated list of HTTP header names. HTTP server instrumentations will
|
||||
capture HTTP request header values for all configured header names.
|
||||
{{% /config_option %}}
|
||||
|
||||
{{% config_option name="otel.instrumentation.http.server.capture-response-headers" %}}
|
||||
A comma-separated list of HTTP header names. HTTP server instrumentations will
|
||||
capture HTTP response header values for all configured header names.
|
||||
{{% /config_option %}}
|
||||
|
||||
These configuration options are supported by all HTTP client and server
|
||||
instrumentations.
|
||||
|
||||
> **Note**: The property/environment variable names listed in the table are
|
||||
> still experimental, and thus are subject to change.
|
||||
|
||||
#### Capturing servlet request parameters
|
||||
|
||||
You can configure the agent to capture predefined HTTP request parameter as span
|
||||
attributes for requests that are handled by Servlet API. Use the following
|
||||
property to define which servlet request parameters you want to capture:
|
||||
|
||||
{{% config_option name="otel.instrumentation.servlet.experimental.capture-request-parameters" %}}
|
||||
A comma-separated list of request parameter names. {{% /config_option %}}
|
||||
|
||||
> **Note**: The property/environment variable names listed in the table are
|
||||
> still experimental, and thus are subject to change.
|
||||
|
||||
#### Configuring known HTTP methods
|
||||
|
||||
Configures the instrumentation to recognize an alternative set of HTTP request
|
||||
methods. All other methods will be treated as `_OTHER`.
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.http.known-methods"
|
||||
default="CONNECT,DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT,TRACE"
|
||||
%}} A comma-separated list of known HTTP methods. {{% /config_option %}}
|
||||
|
||||
#### Enabling experimental HTTP telemetry
|
||||
|
||||
You can configure the agent to capture additional experimental HTTP telemetry
|
||||
data.
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.http.client.emit-experimental-telemetry"
|
||||
name="otel.resource.providers.aws.enabled"
|
||||
default=false
|
||||
%}} Enables the experimental HTTP client telemetry. {{% /config_option %}}
|
||||
|
||||
{{% config_option name="otel.instrumentation.http.server.emit-experimental-telemetry"
|
||||
default=false
|
||||
%}}
|
||||
Enables the experimental HTTP server telemetry. {{% /config_option %}}
|
||||
|
||||
For client and server spans, the following attributes are added:
|
||||
|
||||
- `http.request.body.size` and `http.response.body.size`: The size of the
|
||||
request and response bodies, respectively.
|
||||
|
||||
For client metrics, the following metrics are created:
|
||||
|
||||
- [http.client.request.body.size](/docs/specs/semconv/http/http-metrics/#metric-httpclientrequestbodysize)
|
||||
- [http.client.response.body.size](/docs/specs/semconv/http/http-metrics/#metric-httpclientresponsebodysize)
|
||||
|
||||
For server metrics, the following metrics are created:
|
||||
|
||||
- [http.server.active_requests](/docs/specs/semconv/http/http-metrics/#metric-httpserveractive_requests)
|
||||
- [http.server.request.body.size](/docs/specs/semconv/http/http-metrics/#metric-httpserverrequestbodysize)
|
||||
- [http.server.response.body.size](/docs/specs/semconv/http/http-metrics/#metric-httpserverresponsebodysize)
|
||||
|
||||
### Capturing consumer message receive telemetry in messaging instrumentations
|
||||
|
||||
You can configure the agent to capture the consumer message receive telemetry in
|
||||
messaging instrumentation. Use the following property to enable it:
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.messaging.experimental.receive-telemetry.enabled"
|
||||
default=false
|
||||
%}} Enables the consumer message receive telemetry. {{% /config_option %}}
|
||||
|
||||
Note that this will cause the consumer side to start a new trace, with only a
|
||||
span link connecting it to the producer trace.
|
||||
|
||||
> **Note**: The property/environment variable names listed in the table are
|
||||
> still experimental, and thus are subject to change.
|
||||
|
||||
### Capturing enduser attributes
|
||||
|
||||
You can configure the agent to capture
|
||||
[general identity attributes](/docs/specs/semconv/general/attributes/#general-identity-attributes)
|
||||
(`enduser.id`, `enduser.role`, `enduser.scope`) from instrumentation libraries
|
||||
like
|
||||
[JavaEE/JakartaEE Servlet](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/servlet)
|
||||
and
|
||||
[Spring Security](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/spring/spring-security-config-6.0).
|
||||
|
||||
> **Note**: Given the sensitive nature of the data involved, this feature is
|
||||
> turned off by default while allowing selective activation for particular
|
||||
> attributes. You must carefully evaluate each attribute's privacy implications
|
||||
> before enabling the collection of the data.
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.common.enduser.id.enabled"
|
||||
default=false
|
||||
%}} Determines whether to capture `enduser.id` semantic attribute.
|
||||
%}} Enables the
|
||||
[AWS Resource Provider](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/aws-resources).
|
||||
{{% /config_option %}}
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.common.enduser.role.enabled"
|
||||
name="otel.resource.providers.gcp.enabled"
|
||||
default=false
|
||||
%}} Determines whether to capture `enduser.role` semantic attribute.
|
||||
%}} Enables the
|
||||
[GCP Resource Provider](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/gcp-resources).
|
||||
{{% /config_option %}}
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.common.enduser.scope.enabled"
|
||||
default=false
|
||||
%}} Determines whether to capture `enduser.scope` semantic attribute.
|
||||
{{% /config_option %}}
|
||||
|
||||
#### Spring Security
|
||||
|
||||
For users of Spring Security who use custom
|
||||
[granted authority prefixes](https://docs.spring.io/spring-security/reference/servlet/authorization/architecture.html#authz-authorities),
|
||||
you can use the following properties to strip those prefixes from the
|
||||
`enduser.*` attribute values to better represent the actual role and scope
|
||||
names:
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.spring-security.enduser.role.granted-authority-prefix"
|
||||
default=ROLE_
|
||||
%}} Prefix of granted authorities identifying roles to capture in the
|
||||
`enduser.role` semantic attribute. {{% /config_option %}}
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.spring-security.enduser.scope.granted-authority-prefix"
|
||||
default=SCOPE_
|
||||
%}} Prefix of granted authorities identifying scopes to capture in the
|
||||
`enduser.scopes` semantic attribute. {{% /config_option %}}
|
||||
|
||||
## Suppressing specific instrumentation
|
||||
|
||||
### Disabling the agent entirely
|
||||
|
||||
{{% config_option name="otel.javaagent.enabled" %}}
|
||||
|
||||
Set the value to `false` to disable the agent entirely.
|
||||
|
||||
{{% /config_option %}}
|
||||
|
||||
### 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.
|
||||
|
||||
{{% config_option name="otel.instrumentation.common.default-enabled" %}} Set to
|
||||
`false` to disable all instrumentation in the agent. {{% /config_option %}}
|
||||
|
||||
{{% config_option name="otel.instrumentation.[name].enabled" %}} Set to `true`
|
||||
to enable each desired instrumentation individually. {{% /config_option %}}
|
||||
|
||||
> **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.
|
||||
|
||||
{{% config_option name="otel.instrumentation.[name].enabled" %}} Set to `false`
|
||||
to suppress agent instrumentation of specific libraries, where [name] is the
|
||||
corresponding instrumentation name: {{% /config_option %}}
|
||||
|
||||
| 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 | `camel` |
|
||||
| Apache Cassandra | `cassandra` |
|
||||
| Apache CXF | `cxf` |
|
||||
| Apache DBCP | `apache-dbcp` |
|
||||
| Apache Dubbo | `apache-dubbo` |
|
||||
| Apache Geode | `geode` |
|
||||
| Apache HttpAsyncClient | `apache-httpasyncclient` |
|
||||
| Apache HttpClient | `apache-httpclient` |
|
||||
| Apache Kafka | `kafka` |
|
||||
| Apache MyFaces | `jsf-myfaces` |
|
||||
| Apache Pekko Actor | `pekko-actor` |
|
||||
| Apache Pekko HTTP | `pekko-http` |
|
||||
| Apache Pulsar | `pulsar` |
|
||||
| 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` |
|
||||
| Azure SDK | `azure-core` |
|
||||
| Couchbase | `couchbase` |
|
||||
| C3P0 | `c3p0` |
|
||||
| Dropwizard Views | `dropwizard-views` |
|
||||
| Dropwizard Metrics | `dropwizard-metrics` |
|
||||
| Eclipse Grizzly | `grizzly` |
|
||||
| Eclipse Jersey | `jersey` |
|
||||
| Eclipse Jetty | `jetty` |
|
||||
| Eclipse Jetty HTTP Client | `jetty-httpclient` |
|
||||
| Eclipse Metro | `metro` |
|
||||
| Eclipse Mojarra | `jsf-mojarra` |
|
||||
| Eclipse Vert.x HttpClient | `vertx-http-client` |
|
||||
| Eclipse Vert.x Kafka Client | `vertx-kafka-client` |
|
||||
| Eclipse Vert.x RxJava | `vertx-rx-java` |
|
||||
| Eclipse Vert.x Web | `vertx-web` |
|
||||
| Elasticsearch client | `elasticsearch-transport` |
|
||||
| Elasticsearch REST client | `elasticsearch-rest` |
|
||||
| Google Guava | `guava` |
|
||||
| Google HTTP client | `google-http-client` |
|
||||
| Google Web Toolkit | `gwt` |
|
||||
| Grails | `grails` |
|
||||
| GraphQL Java | `graphql-java` |
|
||||
| GRPC | `grpc` |
|
||||
| Hibernate | `hibernate` |
|
||||
| HikariCP | `hikaricp` |
|
||||
| Java HTTP Client | `java-http-client` |
|
||||
| Java `HttpURLConnection` | `http-url-connection` |
|
||||
| Java JDBC | `jdbc` |
|
||||
| Java JDBC `DataSource` | `jdbc-datasource` |
|
||||
| Java RMI | `rmi` |
|
||||
| Java Runtime | `runtime-telemetry` |
|
||||
| Java Servlet | `servlet` |
|
||||
| java.util.concurrent | `executors` |
|
||||
| java.util.logging | `java-util-logging` |
|
||||
| JAX-RS (Client) | `jaxrs-client` |
|
||||
| JAX-RS (Server) | `jaxrs` |
|
||||
| JAX-WS | `jaxws` |
|
||||
| JBoss Logging Appender | `jboss-logmanager-appender` |
|
||||
| JBoss Logging MDC | `jboss-logmanager-mdc` |
|
||||
| JMS | `jms` |
|
||||
| Jodd HTTP | `jodd-http` |
|
||||
| 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 Extension Annotations | `opentelemetry-extension-annotations` |
|
||||
| OpenTelemetry Instrumentation Annotations | `opentelemetry-instrumentation-annotations` |
|
||||
| OpenTelemetry API | `opentelemetry-api` |
|
||||
| Oracle UCP | `oracle-ucp` |
|
||||
| OSHI (Operating System and Hardware Information) | `oshi` |
|
||||
| Play Framework | `play` |
|
||||
| Play WS HTTP Client | `play-ws` |
|
||||
| Quartz | `quartz` |
|
||||
| R2DBC | `r2dbc` |
|
||||
| RabbitMQ Client | `rabbitmq` |
|
||||
| Ratpack | `ratpack` |
|
||||
| ReactiveX RxJava | `rxjava` |
|
||||
| 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 JMS | `spring-jms` |
|
||||
| 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` |
|
||||
| Tomcat JDBC | `tomcat-jdbc` |
|
||||
| Twilio SDK | `twilio` |
|
||||
| Twitter Finatra | `finatra` |
|
||||
| Undertow | `undertow` |
|
||||
| Vaadin | `vaadin` |
|
||||
| Vibur DBCP | `vibur-dbcp` |
|
||||
| ZIO | `zio` |
|
||||
|
||||
**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](/docs/specs/otel/trace/api/#spankind) 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](/docs/specs/otel/trace/api/#spankind) span.
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.common.experimental.controller-telemetry.enabled"
|
||||
default=false
|
||||
%}} Set to `true` to enable controller telemetry. {{% /config_option %}}
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.common.experimental.view-telemetry.enabled"
|
||||
default=false
|
||||
%}} Set to `true` to enable view telemetry. {{% /config_option %}}
|
||||
|
||||
### 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:
|
||||
|
||||
{{% config_option name="otel.instrumentation.experimental.span-suppression-strategy" %}}
|
||||
|
||||
The Java agent span suppression strategy. The following 3 strategies are
|
||||
supported:
|
||||
|
||||
- `semconv`: The agent will suppress duplicate semantic conventions. This is the
|
||||
default behavior of the Java agent.
|
||||
- `span-kind`: The agent will suppress spans with the same kind (except
|
||||
`INTERNAL`).
|
||||
- `none`: The agent will not suppress anything at all. **We do not recommend
|
||||
using this option for anything other than debug purposes, as it generates lots
|
||||
of duplicate telemetry data**.
|
||||
|
||||
{{% /config_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.
|
||||
|
||||
[extensions]:
|
||||
https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/examples/extension#readme
|
||||
|
|
|
|||
|
|
@ -0,0 +1,261 @@
|
|||
---
|
||||
title: Suppressing specific instrumentation
|
||||
linkTitle: Suppressing instrumentation
|
||||
weight: 11
|
||||
# prettier-ignore
|
||||
cSpell:ignore: akka armeria classloaders couchbase Customizer datasource dbcp Dotel dropwizard dubbo enduser finatra hikari hikaricp HSET httpasyncclient httpclient hystrix jaxrs jaxws jedis jodd kotlinx logback logmanager mojarra myfaces okhttp oshi pekko rabbitmq ratpack rediscala redisson restlet rocketmq serverlessapis spymemcached twilio vaadin vertx vibur webflux webmvc
|
||||
---
|
||||
|
||||
## Disabling the agent entirely
|
||||
|
||||
{{% config_option name="otel.javaagent.enabled" %}}
|
||||
|
||||
Set the value to `false` to disable the agent entirely.
|
||||
|
||||
{{% /config_option %}}
|
||||
|
||||
## 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.
|
||||
|
||||
{{% config_option name="otel.instrumentation.common.default-enabled" %}} Set to
|
||||
`false` to disable all instrumentation in the agent. {{% /config_option %}}
|
||||
|
||||
{{% config_option name="otel.instrumentation.[name].enabled" %}} Set to `true`
|
||||
to enable each desired instrumentation individually. {{% /config_option %}}
|
||||
|
||||
> **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.
|
||||
|
||||
{{% config_option name="otel.instrumentation.[name].enabled" %}} Set to `false`
|
||||
to suppress agent instrumentation of specific libraries, where [name] is the
|
||||
corresponding instrumentation name: {{% /config_option %}}
|
||||
|
||||
| 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 | `camel` |
|
||||
| Apache Cassandra | `cassandra` |
|
||||
| Apache CXF | `cxf` |
|
||||
| Apache DBCP | `apache-dbcp` |
|
||||
| Apache Dubbo | `apache-dubbo` |
|
||||
| Apache Geode | `geode` |
|
||||
| Apache HttpAsyncClient | `apache-httpasyncclient` |
|
||||
| Apache HttpClient | `apache-httpclient` |
|
||||
| Apache Kafka | `kafka` |
|
||||
| Apache MyFaces | `jsf-myfaces` |
|
||||
| Apache Pekko Actor | `pekko-actor` |
|
||||
| Apache Pekko HTTP | `pekko-http` |
|
||||
| Apache Pulsar | `pulsar` |
|
||||
| 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` |
|
||||
| Azure SDK | `azure-core` |
|
||||
| Couchbase | `couchbase` |
|
||||
| C3P0 | `c3p0` |
|
||||
| Dropwizard Views | `dropwizard-views` |
|
||||
| Dropwizard Metrics | `dropwizard-metrics` |
|
||||
| Eclipse Grizzly | `grizzly` |
|
||||
| Eclipse Jersey | `jersey` |
|
||||
| Eclipse Jetty | `jetty` |
|
||||
| Eclipse Jetty HTTP Client | `jetty-httpclient` |
|
||||
| Eclipse Metro | `metro` |
|
||||
| Eclipse Mojarra | `jsf-mojarra` |
|
||||
| Eclipse Vert.x HttpClient | `vertx-http-client` |
|
||||
| Eclipse Vert.x Kafka Client | `vertx-kafka-client` |
|
||||
| Eclipse Vert.x RxJava | `vertx-rx-java` |
|
||||
| Eclipse Vert.x Web | `vertx-web` |
|
||||
| Elasticsearch client | `elasticsearch-transport` |
|
||||
| Elasticsearch REST client | `elasticsearch-rest` |
|
||||
| Google Guava | `guava` |
|
||||
| Google HTTP client | `google-http-client` |
|
||||
| Google Web Toolkit | `gwt` |
|
||||
| Grails | `grails` |
|
||||
| GraphQL Java | `graphql-java` |
|
||||
| GRPC | `grpc` |
|
||||
| Hibernate | `hibernate` |
|
||||
| HikariCP | `hikaricp` |
|
||||
| Java HTTP Client | `java-http-client` |
|
||||
| Java `HttpURLConnection` | `http-url-connection` |
|
||||
| Java JDBC | `jdbc` |
|
||||
| Java JDBC `DataSource` | `jdbc-datasource` |
|
||||
| Java RMI | `rmi` |
|
||||
| Java Runtime | `runtime-telemetry` |
|
||||
| Java Servlet | `servlet` |
|
||||
| java.util.concurrent | `executors` |
|
||||
| java.util.logging | `java-util-logging` |
|
||||
| JAX-RS (Client) | `jaxrs-client` |
|
||||
| JAX-RS (Server) | `jaxrs` |
|
||||
| JAX-WS | `jaxws` |
|
||||
| JBoss Logging Appender | `jboss-logmanager-appender` |
|
||||
| JBoss Logging MDC | `jboss-logmanager-mdc` |
|
||||
| JMS | `jms` |
|
||||
| Jodd HTTP | `jodd-http` |
|
||||
| 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 Extension Annotations | `opentelemetry-extension-annotations` |
|
||||
| OpenTelemetry Instrumentation Annotations | `opentelemetry-instrumentation-annotations` |
|
||||
| OpenTelemetry API | `opentelemetry-api` |
|
||||
| Oracle UCP | `oracle-ucp` |
|
||||
| OSHI (Operating System and Hardware Information) | `oshi` |
|
||||
| Play Framework | `play` |
|
||||
| Play WS HTTP Client | `play-ws` |
|
||||
| Quartz | `quartz` |
|
||||
| R2DBC | `r2dbc` |
|
||||
| RabbitMQ Client | `rabbitmq` |
|
||||
| Ratpack | `ratpack` |
|
||||
| ReactiveX RxJava | `rxjava` |
|
||||
| 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 JMS | `spring-jms` |
|
||||
| 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` |
|
||||
| Tomcat JDBC | `tomcat-jdbc` |
|
||||
| Twilio SDK | `twilio` |
|
||||
| Twitter Finatra | `finatra` |
|
||||
| Undertow | `undertow` |
|
||||
| Vaadin | `vaadin` |
|
||||
| Vibur DBCP | `vibur-dbcp` |
|
||||
| ZIO | `zio` |
|
||||
|
||||
**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](/docs/specs/otel/trace/api/#spankind) 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](/docs/specs/otel/trace/api/#spankind) span.
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.common.experimental.controller-telemetry.enabled"
|
||||
default=false
|
||||
%}} Set to `true` to enable controller telemetry. {{% /config_option %}}
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.common.experimental.view-telemetry.enabled"
|
||||
default=false
|
||||
%}} Set to `true` to enable view telemetry. {{% /config_option %}}
|
||||
|
||||
## 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:
|
||||
|
||||
{{% config_option name="otel.instrumentation.experimental.span-suppression-strategy" %}}
|
||||
|
||||
The Java agent span suppression strategy. The following 3 strategies are
|
||||
supported:
|
||||
|
||||
- `semconv`: The agent will suppress duplicate semantic conventions. This is the
|
||||
default behavior of the Java agent.
|
||||
- `span-kind`: The agent will suppress spans with the same kind (except
|
||||
`INTERNAL`).
|
||||
- `none`: The agent will not suppress anything at all. **We do not recommend
|
||||
using this option for anything other than debug purposes, as it generates lots
|
||||
of duplicate telemetry data**.
|
||||
|
||||
{{% /config_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.
|
||||
|
|
@ -4,7 +4,7 @@ aliases: [/docs/instrumentation/java/extensions]
|
|||
description:
|
||||
Extensions add capabilities to the agent without having to create a separate
|
||||
distribution.
|
||||
weight: 30
|
||||
weight: 300
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
|
|
|||
|
|
@ -0,0 +1,99 @@
|
|||
---
|
||||
title: Getting started
|
||||
weight: 1
|
||||
cSpell:ignore: Dotel myapp
|
||||
---
|
||||
|
||||
## Setup
|
||||
|
||||
1. Download [opentelemetry-javaagent.jar][] from [Releases][] of the
|
||||
`opentelemetry-java-instrumentation` repository and place the JAR in your
|
||||
preferred directory. The JAR file contains the agent and instrumentation
|
||||
libraries.
|
||||
2. Add `-javaagent:path/to/opentelemetry-javaagent.jar` and other config to
|
||||
your JVM startup arguments and launch your app:
|
||||
|
||||
- Directly on the startup command:
|
||||
|
||||
```shell
|
||||
java -javaagent:path/to/opentelemetry-javaagent.jar -Dotel.service.name=your-service-name -jar myapp.jar
|
||||
```
|
||||
|
||||
- Via the `JAVA_TOOL_OPTIONS` and other environment variables:
|
||||
|
||||
```shell
|
||||
export JAVA_TOOL_OPTIONS="-javaagent:path/to/opentelemetry-javaagent.jar"
|
||||
export OTEL_SERVICE_NAME="your-service-name"
|
||||
java -jar myapp.jar
|
||||
```
|
||||
|
||||
## Configuring the agent
|
||||
|
||||
The agent is highly configurable.
|
||||
|
||||
One option is to pass configuration properties via the `-D` flag. In this
|
||||
example, a service name and Zipkin exporter for traces are configured:
|
||||
|
||||
```sh
|
||||
java -javaagent:path/to/opentelemetry-javaagent.jar \
|
||||
-Dotel.service.name=your-service-name \
|
||||
-Dotel.traces.exporter=zipkin \
|
||||
-jar myapp.jar
|
||||
```
|
||||
|
||||
You can also use environment variables to configure the agent:
|
||||
|
||||
```sh
|
||||
OTEL_SERVICE_NAME=your-service-name \
|
||||
OTEL_TRACES_EXPORTER=zipkin \
|
||||
java -javaagent:path/to/opentelemetry-javaagent.jar \
|
||||
-jar myapp.jar
|
||||
```
|
||||
|
||||
You can also supply a Java properties file and load configuration values from
|
||||
there:
|
||||
|
||||
```sh
|
||||
java -javaagent:path/to/opentelemetry-javaagent.jar \
|
||||
-Dotel.javaagent.configuration-file=path/to/properties/file.properties \
|
||||
-jar myapp.jar
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```sh
|
||||
OTEL_JAVAAGENT_CONFIGURATION_FILE=path/to/properties/file.properties \
|
||||
java -javaagent:path/to/opentelemetry-javaagent.jar \
|
||||
-jar myapp.jar
|
||||
```
|
||||
|
||||
To see the full range of configuration options, see
|
||||
[Agent Configuration](../configuration).
|
||||
|
||||
## Supported libraries, frameworks, application services, and JVMs
|
||||
|
||||
The Java agent ships with instrumentation libraries for many popular components.
|
||||
For the full list, see [Supported libraries, frameworks, application services,
|
||||
and JVMs][support].
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
{{% config_option name="otel.javaagent.debug" %}}
|
||||
|
||||
Set to `true` to see debug logs. Note that these are quite verbose.
|
||||
|
||||
{{% /config_option %}}
|
||||
|
||||
## Next steps
|
||||
|
||||
After you have automatic instrumentation configured for your app or service, you
|
||||
might want to [annotate](../annotations) selected methods or add
|
||||
[manual instrumentation](/docs/languages/java/instrumentation/) to collect
|
||||
custom telemetry data.
|
||||
|
||||
[opentelemetry-javaagent.jar]:
|
||||
https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
|
||||
[releases]:
|
||||
https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases
|
||||
[support]:
|
||||
https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md
|
||||
|
|
@ -0,0 +1,144 @@
|
|||
---
|
||||
title: Instrumentation configuration
|
||||
linkTitle: Instrumentation config
|
||||
weight: 100
|
||||
cSpell:ignore: enduser hset serverlessapis
|
||||
---
|
||||
|
||||
This page describes common settings that apply to multiple instrumentations at
|
||||
once.
|
||||
|
||||
## Peer service name
|
||||
|
||||
The
|
||||
[peer service name](/docs/specs/semconv/general/attributes/#general-remote-service-attributes)
|
||||
is the name of a remote service to which a connection is made. It corresponds to
|
||||
`service.name` in the [resource](/docs/specs/semconv/resource/#service) for the
|
||||
local service.
|
||||
|
||||
{{% config_option name="otel.instrumentation.common.peer-service-mapping" %}}
|
||||
|
||||
Used to specify a mapping from host names or IP addresses to peer services, as a
|
||||
comma-separated list of `<host_or_ip>=<user_assigned_name>` pairs. The peer
|
||||
service is added as an attribute to a span whose host or IP address match the
|
||||
mapping.
|
||||
|
||||
For example, if set to the following:
|
||||
|
||||
```text
|
||||
1.2.3.4=cats-service,dogs-abcdef123.serverlessapis.com=dogs-api
|
||||
```
|
||||
|
||||
Then, requests to `1.2.3.4` will have a `peer.service` attribute of
|
||||
`cats-service` and requests to `dogs-abcdef123.serverlessapis.com` will have an
|
||||
attribute of `dogs-api`.
|
||||
|
||||
Since Java agent version `1.31.0`, it is possible to provide a port and a path
|
||||
to define a `peer.service`.
|
||||
|
||||
For example, if set to the following:
|
||||
|
||||
```text
|
||||
1.2.3.4:443=cats-service,dogs-abcdef123.serverlessapis.com:80/api=dogs-api
|
||||
```
|
||||
|
||||
Then, requests to `1.2.3.4` will have no override for `peer.service` attribute,
|
||||
while `1.2.3.4:443` will have have `peer.service` of `cats-service` and requests
|
||||
to `dogs-abcdef123.serverlessapis.com:80/api/v1` will have an attribute of
|
||||
`dogs-api`.
|
||||
|
||||
{{% /config_option %}}
|
||||
|
||||
## DB statement sanitization
|
||||
|
||||
The agent sanitizes all database queries/statements before setting the
|
||||
`db.statement` semantic attribute. All values (strings, numbers) in the query
|
||||
string are replaced with a question mark (`?`).
|
||||
|
||||
Note: JDBC bind parameters are not captured in `db.statement`. See
|
||||
[the corresponding issue](https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues/7413)
|
||||
if you are looking to capture bind parameters.
|
||||
|
||||
Examples:
|
||||
|
||||
- SQL query `SELECT a from b where password="secret"` will appear as
|
||||
`SELECT a from b where password=?` in the exported span;
|
||||
- Redis command `HSET map password "secret"` will appear as
|
||||
`HSET map password ?` in the exported span.
|
||||
|
||||
This behavior is turned on by default for all database instrumentations. Use the
|
||||
following property to disable it:
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.common.db-statement-sanitizer.enabled"
|
||||
default=true
|
||||
%}} Enables the DB statement sanitization. {{% /config_option %}}
|
||||
|
||||
## Capturing consumer message receive telemetry in messaging instrumentations
|
||||
|
||||
You can configure the agent to capture the consumer message receive telemetry in
|
||||
messaging instrumentation. Use the following property to enable it:
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.messaging.experimental.receive-telemetry.enabled"
|
||||
default=false
|
||||
%}} Enables the consumer message receive telemetry. {{% /config_option %}}
|
||||
|
||||
Note that this will cause the consumer side to start a new trace, with only a
|
||||
span link connecting it to the producer trace.
|
||||
|
||||
> **Note**: The property/environment variable names listed in the table are
|
||||
> still experimental, and thus are subject to change.
|
||||
|
||||
## Capturing enduser attributes
|
||||
|
||||
You can configure the agent to capture
|
||||
[general identity attributes](/docs/specs/semconv/general/attributes/#general-identity-attributes)
|
||||
(`enduser.id`, `enduser.role`, `enduser.scope`) from instrumentation libraries
|
||||
like
|
||||
[JavaEE/JakartaEE Servlet](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/servlet)
|
||||
and
|
||||
[Spring Security](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/spring/spring-security-config-6.0).
|
||||
|
||||
> **Note**: Given the sensitive nature of the data involved, this feature is
|
||||
> turned off by default while allowing selective activation for particular
|
||||
> attributes. You must carefully evaluate each attribute's privacy implications
|
||||
> before enabling the collection of the data.
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.common.enduser.id.enabled"
|
||||
default=false
|
||||
%}} Determines whether to capture `enduser.id` semantic attribute.
|
||||
{{% /config_option %}}
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.common.enduser.role.enabled"
|
||||
default=false
|
||||
%}} Determines whether to capture `enduser.role` semantic attribute.
|
||||
{{% /config_option %}}
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.common.enduser.scope.enabled"
|
||||
default=false
|
||||
%}} Determines whether to capture `enduser.scope` semantic attribute.
|
||||
{{% /config_option %}}
|
||||
|
||||
### Spring Security
|
||||
|
||||
For users of Spring Security who use custom
|
||||
[granted authority prefixes](https://docs.spring.io/spring-security/reference/servlet/authorization/architecture.html#authz-authorities),
|
||||
you can use the following properties to strip those prefixes from the
|
||||
`enduser.*` attribute values to better represent the actual role and scope
|
||||
names:
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.spring-security.enduser.role.granted-authority-prefix"
|
||||
default=ROLE_
|
||||
%}} Prefix of granted authorities identifying roles to capture in the
|
||||
`enduser.role` semantic attribute. {{% /config_option %}}
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.spring-security.enduser.scope.granted-authority-prefix"
|
||||
default=SCOPE_
|
||||
%}} Prefix of granted authorities identifying scopes to capture in the
|
||||
`enduser.scopes` semantic attribute. {{% /config_option %}}
|
||||
|
|
@ -0,0 +1,91 @@
|
|||
---
|
||||
title: HTTP instrumentation configuration
|
||||
linkTitle: HTTP
|
||||
weight: 110
|
||||
---
|
||||
|
||||
## Capturing HTTP request and response headers
|
||||
|
||||
You can configure the agent to capture predefined HTTP headers as span
|
||||
attributes, according to the
|
||||
[semantic convention](/docs/specs/semconv/http/http-spans/). Use the following
|
||||
properties to define which HTTP headers you want to capture:
|
||||
|
||||
{{% config_option name="otel.instrumentation.http.client.capture-request-headers" %}}
|
||||
A comma-separated list of HTTP header names. HTTP client instrumentations will
|
||||
capture HTTP request header values for all configured header names.
|
||||
{{% /config_option %}}
|
||||
|
||||
{{% config_option name="otel.instrumentation.http.client.capture-response-headers" %}}
|
||||
A comma-separated list of HTTP header names. HTTP client instrumentations will
|
||||
capture HTTP response header values for all configured header names.
|
||||
{{% /config_option %}}
|
||||
|
||||
{{% config_option name="otel.instrumentation.http.server.capture-request-headers" %}}
|
||||
A comma-separated list of HTTP header names. HTTP server instrumentations will
|
||||
capture HTTP request header values for all configured header names.
|
||||
{{% /config_option %}}
|
||||
|
||||
{{% config_option name="otel.instrumentation.http.server.capture-response-headers" %}}
|
||||
A comma-separated list of HTTP header names. HTTP server instrumentations will
|
||||
capture HTTP response header values for all configured header names.
|
||||
{{% /config_option %}}
|
||||
|
||||
These configuration options are supported by all HTTP client and server
|
||||
instrumentations.
|
||||
|
||||
> **Note**: The property/environment variable names listed in the table are
|
||||
> still experimental, and thus are subject to change.
|
||||
|
||||
## Capturing servlet request parameters
|
||||
|
||||
You can configure the agent to capture predefined HTTP request parameter as span
|
||||
attributes for requests that are handled by Servlet API. Use the following
|
||||
property to define which servlet request parameters you want to capture:
|
||||
|
||||
{{% config_option name="otel.instrumentation.servlet.experimental.capture-request-parameters" %}}
|
||||
A comma-separated list of request parameter names. {{% /config_option %}}
|
||||
|
||||
> **Note**: The property/environment variable names listed in the table are
|
||||
> still experimental, and thus are subject to change.
|
||||
|
||||
## Configuring known HTTP methods
|
||||
|
||||
Configures the instrumentation to recognize an alternative set of HTTP request
|
||||
methods. All other methods will be treated as `_OTHER`.
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.http.known-methods"
|
||||
default="CONNECT,DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT,TRACE"
|
||||
%}} A comma-separated list of known HTTP methods. {{% /config_option %}}
|
||||
|
||||
## Enabling experimental HTTP telemetry
|
||||
|
||||
You can configure the agent to capture additional experimental HTTP telemetry
|
||||
data.
|
||||
|
||||
{{% config_option
|
||||
name="otel.instrumentation.http.client.emit-experimental-telemetry"
|
||||
default=false
|
||||
%}} Enables the experimental HTTP client telemetry. {{% /config_option %}}
|
||||
|
||||
{{% config_option name="otel.instrumentation.http.server.emit-experimental-telemetry"
|
||||
default=false
|
||||
%}}
|
||||
Enables the experimental HTTP server telemetry. {{% /config_option %}}
|
||||
|
||||
For client and server spans, the following attributes are added:
|
||||
|
||||
- `http.request.body.size` and `http.response.body.size`: The size of the
|
||||
request and response bodies, respectively.
|
||||
|
||||
For client metrics, the following metrics are created:
|
||||
|
||||
- [http.client.request.body.size](/docs/specs/semconv/http/http-metrics/#metric-httpclientrequestbodysize)
|
||||
- [http.client.response.body.size](/docs/specs/semconv/http/http-metrics/#metric-httpclientresponsebodysize)
|
||||
|
||||
For server metrics, the following metrics are created:
|
||||
|
||||
- [http.server.active_requests](/docs/specs/semconv/http/http-metrics/#metric-httpserveractive_requests)
|
||||
- [http.server.request.body.size](/docs/specs/semconv/http/http-metrics/#metric-httpserverrequestbodysize)
|
||||
- [http.server.response.body.size](/docs/specs/semconv/http/http-metrics/#metric-httpserverresponsebodysize)
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
title: Application server configuration
|
||||
linkTitle: App server config
|
||||
description: Learn how to define agent paths for Java application servers
|
||||
weight: 15
|
||||
weight: 215
|
||||
cSpell:ignore: asadmin binsetenv binstart Glassfish Payara setenv
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ IDE.
|
|||
## General configuration
|
||||
|
||||
The OpenTelemetry Starter supports all the
|
||||
[SDK Autoconfiguration](/docs/zero-code/java/agent/configuration/#sdk-autoconfiguration)
|
||||
[SDK Autoconfiguration](/docs/zero-code/java/agent/configuration/#sdk-configuration)
|
||||
(since 2.2.0).
|
||||
|
||||
You can update the configuration with properties in the `application.properties`
|
||||
|
|
|
|||
|
|
@ -1315,6 +1315,10 @@
|
|||
"StatusCode": 206,
|
||||
"LastSeen": "2024-02-17T16:19:07.140338072Z"
|
||||
},
|
||||
"https://docs.micrometer.io/micrometer/reference/implementations/otlp.html": {
|
||||
"StatusCode": 206,
|
||||
"LastSeen": "2024-07-15T14:03:44.726797719+02:00"
|
||||
},
|
||||
"https://docs.microsoft.com/aspnet/core": {
|
||||
"StatusCode": 200,
|
||||
"LastSeen": "2024-01-18T08:53:25.01054-05:00"
|
||||
|
|
@ -3859,6 +3863,10 @@
|
|||
"StatusCode": 200,
|
||||
"LastSeen": "2024-01-18T19:55:35.674322-05:00"
|
||||
},
|
||||
"https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues": {
|
||||
"StatusCode": 200,
|
||||
"LastSeen": "2024-07-15T14:03:44.295338372+02:00"
|
||||
},
|
||||
"https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues/7413": {
|
||||
"StatusCode": 200,
|
||||
"LastSeen": "2024-02-22T15:50:20.20139382Z"
|
||||
|
|
|
|||
Loading…
Reference in New Issue