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-mapping
Environment variable:
OTEL_INSTRUMENTATION_COMMON_PEER_SERVICE_MAPPINGDescription:
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 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 asSELECT a from b where password=?in the exported span; - Redis command
HSET map password "secret"will appear asHSET 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.enabled
Environment variable:
OTEL_INSTRUMENTATION_COMMON_DB_STATEMENT_SANITIZER_ENABLEDDefault: 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.enabled
Environment variable:
OTEL_INSTRUMENTATION_MESSAGING_EXPERIMENTAL_RECEIVE_TELEMETRY_ENABLEDDefault: 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.enabled
Environment variable:
OTEL_INSTRUMENTATION_COMMON_ENDUSER_ID_ENABLEDDefault: false
Description:
Determines whether to capture enduser.id semantic attribute.
System property:
otel.instrumentation.common.enduser.role.enabled
Environment variable:
OTEL_INSTRUMENTATION_COMMON_ENDUSER_ROLE_ENABLEDDefault: false
Description:
Determines whether to capture enduser.role semantic attribute.
System property:
otel.instrumentation.common.enduser.scope.enabled
Environment variable:
OTEL_INSTRUMENTATION_COMMON_ENDUSER_SCOPE_ENABLEDDefault: 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-prefix
Environment variable:
OTEL_INSTRUMENTATION_SPRING_SECURITY_ENDUSER_ROLE_GRANTED_AUTHORITY_PREFIXDefault: 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-prefix
Environment variable:
OTEL_INSTRUMENTATION_SPRING_SECURITY_ENDUSER_SCOPE_GRANTED_AUTHORITY_PREFIXDefault: SCOPE_
Description:
Prefix of granted authorities identifying scopes to capture in the
enduser.scopes semantic attribute.
[i18n] feedback_title
[i18n] feedback_question
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!