From c1b208177cf4a2366f1dad02d5012c03a8e85535 Mon Sep 17 00:00:00 2001 From: jkwatson Date: Wed, 10 Mar 2021 14:04:09 -0800 Subject: [PATCH 1/4] Update the agent-config docs. This provides more direct linking to the auto-instrumentation docs that people might need. --- docs/agent-config.md | 35 +++++++++++++++++++++-------------- 1 file changed, 21 insertions(+), 14 deletions(-) diff --git a/docs/agent-config.md b/docs/agent-config.md index e40f049be196..a15b5fddafcc 100644 --- a/docs/agent-config.md +++ b/docs/agent-config.md @@ -1,25 +1,40 @@ -# Configuration parameters +# Configuration options ## NOTE: subject to change! -Note: These parameter names are very likely to change over time, so please check -back here when trying out a new version! Please report any bugs or unexpected -behavior you find. +Note: The environment variables/system properties in this document are very likely to change over time. +Please check back here when trying out a new version! + +Please report any bugs or unexpected behavior you find. ## Contents * [SDK Autoconfiguration](#sdk-autoconfiguration) * [Peer service name](#peer-service-name) * [DB statement sanitization](#db-statement-sanitization) -* [Customizing the OpenTelemetry SDK](#customizing-the-opentelemetry-sdk) * [Suppressing specific auto-instrumentation](#suppressing-specific-auto-instrumentation) ## SDK Autoconfiguration The SDK's autoconfiguration module is used for basic configuration of the agent. Read the -[docs](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure#customizing-the-opentelemetry-sdk) +[docs](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure) to find settings such as configuring export or sampling. +Here are some quick links into those docs for the configuration options for specific portions of the SDK & agent: + +* [Exporters](#exporters) + + [OTLP exporter (both span and metric exporters)](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#otlp-exporter-both-span-and-metric-exporters) + + [Jaeger exporter](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#jaeger-exporter) + + [Zipkin exporter](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#zipkin-exporter) + + [Prometheus exporter](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#prometheus-exporter) + + [Logging exporter](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#logging-exporter) +* [Trace context propagation](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#propagator) +* [OpenTelemetry Resource](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#opentelemetry-resource) +* [Batch span processor](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#batch-span-processor) +* [Sampler](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#sampler) +* [Span limits](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#span-limits) +* [Using SPI to further configure the SDK](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#customizing-the-opentelemetry-sdk) + ## 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. @@ -44,14 +59,6 @@ The following property may be used to disable it: |-------------------------------------------------------|-------------------------------------------------------|---------------------------------------------------------------------| | `otel.instrumentation.common.db-statement-sanitizer.enabled` | `OTEL_INSTRUMENTATION_COMMON_DB_STATEMENT_SANITIZER_ENABLED` | Enables the DB statement sanitization. The default value is `true`. | -## Customizing the OpenTelemetry SDK - -*Customizing the SDK is highly advanced behavior and is still in the prototyping phase. It may change drastically or be removed completely. Use -with caution* - -The OpenTelemetry SDK exposes SPI [hooks](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure/src/main/java/io/opentelemetry/sdk/autoconfigure/spi) -for customizing its behavior, such as the `Resource` attached to spans or the `Sampler`. - Because the automatic instrumentation runs in a different classpath than the instrumented application, it is not possible for customization in the application to take advantage of this customization. In order to provide such customization, you can provide the path to a JAR file, including an SPI implementation using the system property `otel.initializer.jar`. Note that this JAR needs to shade the OpenTelemetry API in the same way as the agent does. The simplest way to do this is to use the same shading configuration as the agent from [here](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/cfade733b899a2f02cfec7033c6a1efd7c54fd8b/java-agent/java-agent.gradle#L39). In addition, you must specify the `io.opentelemetry.javaagent.shaded.io.opentelemetry.api.trace.spi.TraceProvider` to the name of the class that implements the SPI. ## Suppressing specific auto-instrumentation From a1732f9fd75a07b0385842cf21f69b09b0350202 Mon Sep 17 00:00:00 2001 From: jkwatson Date: Wed, 10 Mar 2021 14:19:16 -0800 Subject: [PATCH 2/4] spotlessly spotless --- docs/agent-config.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/agent-config.md b/docs/agent-config.md index a15b5fddafcc..8d7c18486c4c 100644 --- a/docs/agent-config.md +++ b/docs/agent-config.md @@ -2,8 +2,8 @@ ## NOTE: subject to change! -Note: The environment variables/system properties in this document are very likely to change over time. -Please check back here when trying out a new version! +Note: The environment variables/system properties in this document are very likely to change over time. +Please check back here when trying out a new version! Please report any bugs or unexpected behavior you find. From 64e5ba3be0a67a5ee2492bc2d9cf24fd4a503d43 Mon Sep 17 00:00:00 2001 From: jkwatson Date: Wed, 10 Mar 2021 14:28:27 -0800 Subject: [PATCH 3/4] update the title --- docs/agent-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/agent-config.md b/docs/agent-config.md index 8d7c18486c4c..5eb6523fde66 100644 --- a/docs/agent-config.md +++ b/docs/agent-config.md @@ -1,4 +1,4 @@ -# Configuration options +# Agent Configuration ## NOTE: subject to change! From 3e751bd4953e0d91f2c413c1345c6dbfd01f1a19 Mon Sep 17 00:00:00 2001 From: jkwatson Date: Thu, 11 Mar 2021 07:56:48 -0800 Subject: [PATCH 4/4] removed super-advanced line, and pointed at the main branch in the otel-java repo docs --- docs/agent-config.md | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/docs/agent-config.md b/docs/agent-config.md index 5eb6523fde66..8ea580f27f98 100644 --- a/docs/agent-config.md +++ b/docs/agent-config.md @@ -17,23 +17,23 @@ Please report any bugs or unexpected behavior you find. ## SDK Autoconfiguration The SDK's autoconfiguration module is used for basic configuration of the agent. Read the -[docs](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure) +[docs](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure) to find settings such as configuring export or sampling. Here are some quick links into those docs for the configuration options for specific portions of the SDK & agent: * [Exporters](#exporters) - + [OTLP exporter (both span and metric exporters)](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#otlp-exporter-both-span-and-metric-exporters) - + [Jaeger exporter](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#jaeger-exporter) - + [Zipkin exporter](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#zipkin-exporter) - + [Prometheus exporter](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#prometheus-exporter) - + [Logging exporter](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#logging-exporter) -* [Trace context propagation](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#propagator) -* [OpenTelemetry Resource](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#opentelemetry-resource) -* [Batch span processor](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#batch-span-processor) -* [Sampler](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#sampler) -* [Span limits](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#span-limits) -* [Using SPI to further configure the SDK](https://github.com/open-telemetry/opentelemetry-java/tree/v1.0.0/sdk-extensions/autoconfigure/README.md#customizing-the-opentelemetry-sdk) + + [OTLP exporter (both span and metric exporters)](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure/README.md#otlp-exporter-both-span-and-metric-exporters) + + [Jaeger exporter](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure/README.md#jaeger-exporter) + + [Zipkin exporter](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure/README.md#zipkin-exporter) + + [Prometheus exporter](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure/README.md#prometheus-exporter) + + [Logging exporter](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure/README.md#logging-exporter) +* [Trace context propagation](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure/README.md#propagator) +* [OpenTelemetry Resource](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure/README.md#opentelemetry-resource) +* [Batch span processor](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure/README.md#batch-span-processor) +* [Sampler](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure/README.md#sampler) +* [Span limits](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure/README.md#span-limits) +* [Using SPI to further configure the SDK](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure/README.md#customizing-the-opentelemetry-sdk) ## Peer service name @@ -59,8 +59,6 @@ The following property may be used to disable it: |-------------------------------------------------------|-------------------------------------------------------|---------------------------------------------------------------------| | `otel.instrumentation.common.db-statement-sanitizer.enabled` | `OTEL_INSTRUMENTATION_COMMON_DB_STATEMENT_SANITIZER_ENABLED` | Enables the DB statement sanitization. The default value is `true`. | -Because the automatic instrumentation runs in a different classpath than the instrumented application, it is not possible for customization in the application to take advantage of this customization. In order to provide such customization, you can provide the path to a JAR file, including an SPI implementation using the system property `otel.initializer.jar`. Note that this JAR needs to shade the OpenTelemetry API in the same way as the agent does. The simplest way to do this is to use the same shading configuration as the agent from [here](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/cfade733b899a2f02cfec7033c6a1efd7c54fd8b/java-agent/java-agent.gradle#L39). In addition, you must specify the `io.opentelemetry.javaagent.shaded.io.opentelemetry.api.trace.spi.TraceProvider` to the name of the class that implements the SPI. - ## Suppressing specific auto-instrumentation See [suppressing specific auto-instrumentation](suppressing-instrumentation.md)