Skip to content

Commit

Permalink
Document captured HTTP headers configuration options (#4321)
Browse files Browse the repository at this point in the history 
* Document captured HTTP headers configuration options

* Apply suggestions from code review

Co-authored-by: Fabrizio Ferri-Benedetti <fferribenedetti@splunk.com>

* Reformatting after applying comments

* Update docs/config/common.md

Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>

Co-authored-by: Fabrizio Ferri-Benedetti <fferribenedetti@splunk.com>
Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>
  • Loading branch information
@theletterf @trask
3 people authored Oct 8, 2021
1 parent 99f6bcd commit 2fbec93
Show file tree
Hide file tree
Showing 2 changed files with 53 additions and 22 deletions.
24 changes: 2 additions & 22 deletions docs/agent-config.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,29 +60,9 @@ You can enable [extensions](../examples/extension/README.md) by setting the corr
|--------------------------------------|--------------------------------------|----------------------------------------------------------------------------------|
| `otel.javaagent.extensions` | `OTEL_JAVAAGENT_EXTENSIONS` | Path to a an extension jar file or folder, containing jar files. If pointing to a folder, every jar file in that folder will be treated as separate, independent extension|

## Peer service name
## Common instrumentation configuration

The [peer service name](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/semantic_conventions/span-general.md#general-remote-service-attributes) is the name of a remote service being connected to. It corresponds to `service.name` in the [Resource](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/resource/semantic_conventions#service) for the local service.

| System property | Environment variable | Description |
|--------------------------------------|--------------------------------------|----------------------------------------------------------------------------------|
| `otel.instrumentation.common.peer-service-mapping` | `OTEL_INSTRUMENTATION_COMMON_PEER_SERVICE_MAPPING` | Used to specify a mapping from hostnames or IP addresses to peer services, as a comma-separated list of host=name pairs. The peer service is added as an attribute to a span whose host or IP match the mapping. For example, if set to 1.2.3.4=cats-service,dogs-abcdef123.serverlessapis.com=dogs-api, 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`. |

## 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 `?`.

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.
The following property may be used to disable it:

| System property | Environment variable | Description |
|-------------------------------------------------------|-------------------------------------------------------|---------------------------------------------------------------------|
| `otel.instrumentation.common.db-statement-sanitizer.enabled` | `OTEL_INSTRUMENTATION_COMMON_DB_STATEMENT_SANITIZER_ENABLED` | Enables the DB statement sanitization. The default value is `true`. |
See [common instrumentation configuration properties](config/common.md).

## Suppressing specific auto-instrumentation

Expand Down
51 changes: 51 additions & 0 deletions docs/config/common.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Common instrumentation configuration

Common settings that apply to multiple instrumentations at once.

## Peer service name

The [peer service name](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/semantic_conventions/span-general.md#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](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/resource/semantic_conventions#service)
for the local service.

| System property | Environment variable | Description |
| -------------------------------------------------- | -------------------------------------------------- | ----------- |
| `otel.instrumentation.common.peer-service-mapping` | `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 `1.2.3.4=cats-service,dogs-abcdef123.serverlessapis.com=dogs-api`, 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`.

## 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 (`?`).

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 | Environment variable | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------ | ----------- |
| `otel.instrumentation.common.db-statement-sanitizer.enabled` | `OTEL_INSTRUMENTATION_COMMON_DB_STATEMENT_SANITIZER_ENABLED` | Enables the DB statement sanitization. The default value is `true`.

## Capturing HTTP request and response headers

You can configure the agent to capture predefined HTTP headers as span attributes, according to the
[semantic convention](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md#http-request-and-response-headers).
Use the following properties to define which HTTP headers you want to capture:

| System property | Environment variable | Description |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------- |
| `otel.instrumentation.common.experimental.capture-http-headers.client.request` | `OTEL_INSTRUMENTATION_COMMON_EXPERIMENTAL_CAPTURE_HTTP_HEADERS_CLIENT_REQUEST` | A comma-separated list of HTTP header names. HTTP client instrumentations will capture HTTP request header values for all configured header names.
| `otel.instrumentation.common.experimental.capture-http-headers.client.response` | `OTEL_INSTRUMENTATION_COMMON_EXPERIMENTAL_CAPTURE_HTTP_HEADERS_CLIENT_RESPONSE` | A comma-separated list of HTTP header names. HTTP client instrumentations will capture HTTP response header values for all configured header names.
| `otel.instrumentation.common.experimental.capture-http-headers.server.request` | `OTEL_INSTRUMENTATION_COMMON_EXPERIMENTAL_CAPTURE_HTTP_HEADERS_SERVER_REQUEST` | A comma-separated list of HTTP header names. HTTP server instrumentations will capture HTTP request header values for all configured header names.
| `otel.instrumentation.common.experimental.capture-http-headers.server.response` | `OTEL_INSTRUMENTATION_COMMON_EXPERIMENTAL_CAPTURE_HTTP_HEADERS_SERVER_RESPONSE` | A comma-separated list of HTTP header names. HTTP server instrumentations will capture HTTP response header values for all configured header names.

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.

0 comments on commit 2fbec93

Please sign in to comment.