Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document captured HTTP headers configuration options #4321

Merged
merged 4 commits into from
Oct 8, 2021
Merged

Document captured HTTP headers configuration options #4321

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4a785a2
Document captured HTTP headers configuration options
Oct 7, 2021
958633a
Apply suggestions from code review
Oct 7, 2021
6181925
Reformatting after applying comments
Oct 7, 2021
6f61934
Update docs/config/common.md
Oct 7, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 2 additions & 22 deletions docs/agent-config.md
View file
Open in desktop
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
Open in desktop
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:
mateuszrzeszutek marked this conversation as resolved.
Show resolved Hide resolved

| 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.
Comment on lines +43 to +46
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

these long names 😭

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah... If somebody has a better idea for these, please speak up! Except from dropping the experimental part at some point in time I couldn't think of anything to make them better.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wait, they’re still open for discussion? I love naming vars. Let’s discuss today. :)


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.