# Instrumentation configuration

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.

<div class="config-option">
<details>
  <summary title="Expand to view environment variable">
    <span class="label">System property</span>:
      <code>otel.instrumentation.common.peer-service-mapping</code>
  </summary>
  <span class="label">Environment variable</span>:
    <code>OTEL_INSTRUMENTATION_COMMON_PEER_SERVICE_MAPPING</code>
</details>

<span class="label">Description</span>:
Used to specify a mapping from host names or IP addresses to peer services, as a
comma-separated list of `&lt;host_or_ip&gt;=&lt;user_assigned_name&gt;` 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 `peer.service` of `cats-service` and requests to
`dogs-abcdef123.serverlessapis.com:80/api/v1` will have an attribute of
`dogs-api`.
</div>


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

<div class="config-option">
<details>
  <summary title="Expand to view environment variable">
    <span class="label">System property</span>:
      <code>otel.instrumentation.common.db-statement-sanitizer.enabled</code>
  </summary>
  <span class="label">Environment variable</span>:
    <code>OTEL_INSTRUMENTATION_COMMON_DB_STATEMENT_SANITIZER_ENABLED</code>
</details>

<span class="label">Default</span>: true<br>
<span class="label">Description</span>:
Enables the DB statement sanitization.
</div>


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

<div class="config-option">
<details>
  <summary title="Expand to view environment variable">
    <span class="label">System property</span>:
      <code>otel.instrumentation.messaging.experimental.receive-telemetry.enabled</code>
  </summary>
  <span class="label">Environment variable</span>:
    <code>OTEL_INSTRUMENTATION_MESSAGING_EXPERIMENTAL_RECEIVE_TELEMETRY_ENABLED</code>
</details>

<span class="label">Default</span>: false<br>
<span class="label">Description</span>:
Enables the consumer message receive telemetry.
</div>


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/registry/attributes/enduser/)
(`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.

<div class="config-option">
<details>
  <summary title="Expand to view environment variable">
    <span class="label">System property</span>:
      <code>otel.instrumentation.common.enduser.id.enabled</code>
  </summary>
  <span class="label">Environment variable</span>:
    <code>OTEL_INSTRUMENTATION_COMMON_ENDUSER_ID_ENABLED</code>
</details>

<span class="label">Default</span>: false<br>
<span class="label">Description</span>:
Determines whether to capture `enduser.id` semantic attribute.
</div>


<div class="config-option">
<details>
  <summary title="Expand to view environment variable">
    <span class="label">System property</span>:
      <code>otel.instrumentation.common.enduser.role.enabled</code>
  </summary>
  <span class="label">Environment variable</span>:
    <code>OTEL_INSTRUMENTATION_COMMON_ENDUSER_ROLE_ENABLED</code>
</details>

<span class="label">Default</span>: false<br>
<span class="label">Description</span>:
Determines whether to capture `enduser.role` semantic attribute.
</div>


<div class="config-option">
<details>
  <summary title="Expand to view environment variable">
    <span class="label">System property</span>:
      <code>otel.instrumentation.common.enduser.scope.enabled</code>
  </summary>
  <span class="label">Environment variable</span>:
    <code>OTEL_INSTRUMENTATION_COMMON_ENDUSER_SCOPE_ENABLED</code>
</details>

<span class="label">Default</span>: false<br>
<span class="label">Description</span>:
Determines whether to capture `enduser.scope` semantic attribute.
</div>


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

<div class="config-option">
<details>
  <summary title="Expand to view environment variable">
    <span class="label">System property</span>:
      <code>otel.instrumentation.spring-security.enduser.role.granted-authority-prefix</code>
  </summary>
  <span class="label">Environment variable</span>:
    <code>OTEL_INSTRUMENTATION_SPRING_SECURITY_ENDUSER_ROLE_GRANTED_AUTHORITY_PREFIX</code>
</details>

<span class="label">Default</span>: ROLE_<br>
<span class="label">Description</span>:
Prefix of granted authorities identifying roles to capture in the
`enduser.role` semantic attribute.
</div>


<div class="config-option">
<details>
  <summary title="Expand to view environment variable">
    <span class="label">System property</span>:
      <code>otel.instrumentation.spring-security.enduser.scope.granted-authority-prefix</code>
  </summary>
  <span class="label">Environment variable</span>:
    <code>OTEL_INSTRUMENTATION_SPRING_SECURITY_ENDUSER_SCOPE_GRANTED_AUTHORITY_PREFIX</code>
</details>

<span class="label">Default</span>: SCOPE_<br>
<span class="label">Description</span>:
Prefix of granted authorities identifying scopes to capture in the
`enduser.scopes` semantic attribute.
</div>

---

Section pages:

- [HTTP instrumentation configuration](/ja/docs/zero-code/java/agent/instrumentation/http/)