From 4a785a2c33917b9ed695b528b709bea2344c3200 Mon Sep 17 00:00:00 2001 From: Mateusz Rzeszutek Date: Thu, 7 Oct 2021 15:37:57 +0200 Subject: [PATCH 1/4] Document captured HTTP headers configuration options --- docs/agent-config.md | 24 ++------------------ docs/config/common.md | 52 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+), 22 deletions(-) create mode 100644 docs/config/common.md diff --git a/docs/agent-config.md b/docs/agent-config.md index ffcca1d9cff3..824afc8e59de 100644 --- a/docs/agent-config.md +++ b/docs/agent-config.md @@ -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 diff --git a/docs/config/common.md b/docs/config/common.md new file mode 100644 index 000000000000..f8fce221426b --- /dev/null +++ b/docs/config/common.md @@ -0,0 +1,52 @@ +# 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 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`. | + +## Capturing HTTP request and response headers + +The agent can be configured to capture chosen 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) +. The following properties may be used to define which headers should be captured: + +| 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 javaagent HTTP client and server instrumentations. + +NOTE: the property/env variable names listed in the table above are still experimental, and thus are +subject to change! From 958633a9198ad7367e9212f508b3dffae1b8383c Mon Sep 17 00:00:00 2001 From: Mateusz Rzeszutek Date: Thu, 7 Oct 2021 16:16:25 +0200 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Fabrizio Ferri-Benedetti --- docs/config/common.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/config/common.md b/docs/config/common.md index f8fce221426b..2ed138b14a41 100644 --- a/docs/config/common.md +++ b/docs/config/common.md @@ -5,19 +5,20 @@ 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 being connected to. It corresponds to `service.name` in +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 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`. | +| `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 `=` 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 `?`. +attribute. All values (strings, numbers) in the query string are replaced with a question mark (`?`). Examples: @@ -26,8 +27,7 @@ Examples: * 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: +This behavior is turned on by default for all database instrumentations. Use the following property to disable it: | System property | Environment variable | Description | |-------------------------------------------------------|-------------------------------------------------------|---------------------------------------------------------------------| @@ -35,9 +35,9 @@ be used to disable it: ## Capturing HTTP request and response headers -The agent can be configured to capture chosen HTTP headers as span attributes, according to the +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) -. The following properties may be used to define which headers should be captured: +. Use the following properties to define which HTTP headers you want to capture: | System property | Environment variable | Description | | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------- | @@ -46,7 +46,7 @@ The agent can be configured to capture chosen HTTP headers as span attributes, a | `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 javaagent HTTP client and server instrumentations. +These configuration options are supported by all HTTP client and server instrumentations. -NOTE: the property/env variable names listed in the table above are still experimental, and thus are -subject to change! +> **Note**: The property/environment variable names listed in the table are still experimental, and thus are +subject to change. From 61819259710243d1a68d4dc95da610dd775f2165 Mon Sep 17 00:00:00 2001 From: Mateusz Rzeszutek Date: Thu, 7 Oct 2021 16:20:35 +0200 Subject: [PATCH 3/4] Reformatting after applying comments --- docs/config/common.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/config/common.md b/docs/config/common.md index 2ed138b14a41..a58138716385 100644 --- a/docs/config/common.md +++ b/docs/config/common.md @@ -9,11 +9,9 @@ is the name of a remote service to which a connection is made. It corresponds to 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 `=` 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`. | +| 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 `=` 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 @@ -27,11 +25,12 @@ Examples: * 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: +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`. | +| 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 @@ -48,5 +47,5 @@ You can configure the agent to capture predefined HTTP headers as span attribute 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. +> **Note**: The property/environment variable names listed in the table are still experimental, +> and thus are subject to change. From 6f6193468da86d5784a5bdc1484b8a89b6db9728 Mon Sep 17 00:00:00 2001 From: Mateusz Rzeszutek Date: Thu, 7 Oct 2021 19:33:14 +0200 Subject: [PATCH 4/4] Update docs/config/common.md Co-authored-by: Trask Stalnaker --- docs/config/common.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/config/common.md b/docs/config/common.md index a58138716385..ecf757d3b49b 100644 --- a/docs/config/common.md +++ b/docs/config/common.md @@ -35,8 +35,8 @@ to disable it: ## 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: +[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 | | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------- |