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

Update the agent-config docs. #2551

Merged
merged 4 commits into from
Mar 11, 2021
Merged

Update the agent-config docs. #2551

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c1b2081
Update the agent-config docs.
Mar 10, 2021
a1732f9
spotlessly spotless
Mar 10, 2021
64e5ba3
update the title
Mar 10, 2021
3e751bd
removed super-advanced line, and pointed at the main branch in the ot…
Mar 11, 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
35 changes: 21 additions & 14 deletions docs/agent-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,40 @@
# Configuration parameters
# Agent Configuration

## 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)
Copy link
Contributor

Choose a reason for hiding this comment

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

Hmmm...I'm not convinced that linking to the specific version (instead of main branch) is a good idea. Can you convince me?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I have no idea...it's what was linked to in this document, so I stuck with it.

Copy link
Member

Choose a reason for hiding this comment

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

main sounds reasonable to me

Copy link
Contributor Author

Choose a reason for hiding this comment

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

updated to point at main

+ [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.
Expand All @@ -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.
Copy link
Member

Choose a reason for hiding this comment

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

I think this section is still relevant (though maybe too advanced for main agent config page, and scheduled to change a bit in #2442)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

yeah, I missed this line. I think we should remove it from this page, since it's not relevant for normal end-users and will probably confuse most people who are the target audience.


## Suppressing specific auto-instrumentation
Expand Down