Instrumentation configuration

This page describes common settings that apply to multiple instrumentations at once.

Peer service name

The peer service name is the name of a remote service to which a connection is made. It corresponds to service.name in the resource for the local service.

System property: otel.instrumentation.common.peer-service-mappingEnvironment variable: OTEL_INSTRUMENTATION_COMMON_PEER_SERVICE_MAPPING

Description: 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:

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.

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 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:

System property: otel.instrumentation.common.db-statement-sanitizer.enabledEnvironment variable: OTEL_INSTRUMENTATION_COMMON_DB_STATEMENT_SANITIZER_ENABLED

Default: true
Description: Enables the DB statement sanitization.

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:

System property: otel.instrumentation.messaging.experimental.receive-telemetry.enabledEnvironment variable: OTEL_INSTRUMENTATION_MESSAGING_EXPERIMENTAL_RECEIVE_TELEMETRY_ENABLED

Default: false
Description: Enables the consumer message receive telemetry.

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 (enduser.id, enduser.role, enduser.scope) from instrumentation libraries like JavaEE/JakartaEE Servlet and Spring Security.

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.

System property: otel.instrumentation.common.enduser.id.enabledEnvironment variable: OTEL_INSTRUMENTATION_COMMON_ENDUSER_ID_ENABLED

Default: false
Description: Determines whether to capture enduser.id semantic attribute.

System property: otel.instrumentation.common.enduser.role.enabledEnvironment variable: OTEL_INSTRUMENTATION_COMMON_ENDUSER_ROLE_ENABLED

Default: false
Description: Determines whether to capture enduser.role semantic attribute.

System property: otel.instrumentation.common.enduser.scope.enabledEnvironment variable: OTEL_INSTRUMENTATION_COMMON_ENDUSER_SCOPE_ENABLED

Default: false
Description: Determines whether to capture enduser.scope semantic attribute.

Spring Security

For users of Spring Security who use custom granted authority prefixes, you can use the following properties to strip those prefixes from the enduser.* attribute values to better represent the actual role and scope names:

System property: otel.instrumentation.spring-security.enduser.role.granted-authority-prefixEnvironment variable: OTEL_INSTRUMENTATION_SPRING_SECURITY_ENDUSER_ROLE_GRANTED_AUTHORITY_PREFIX

Default: ROLE_
Description: Prefix of granted authorities identifying roles to capture in the enduser.role semantic attribute.

System property: otel.instrumentation.spring-security.enduser.scope.granted-authority-prefixEnvironment variable: OTEL_INSTRUMENTATION_SPRING_SECURITY_ENDUSER_SCOPE_GRANTED_AUTHORITY_PREFIX

Default: SCOPE_
Description: Prefix of granted authorities identifying scopes to capture in the enduser.scopes semantic attribute.