Skip to content

Commit 29140bd

Browse files
author
Anuraag Agrawal
authored
Add docs for autoconfiguration options. (open-telemetry#2812)
* Add docs for autoconfiguration options. * Better docs * quickstart
1 parent ebaceb7 commit 29140bd

2 files changed

Lines changed: 169 additions & 13 deletions

File tree

‎QUICKSTART.md‎

Lines changed: 1 addition & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -38,10 +38,6 @@ The first step is to get a handle to an instance of the `OpenTelemetry` interfac
3838
If you are an application developer, you need to configure an instance of the `OpenTelemetrySdk` as
3939
early as possible in your application. This can be done using the `OpenTelemetrySdk.builder()` method.
4040

41-
If you want to enable auto-configuration, via the standard set of environment variables, system
42-
properties or pre-build java SPI implementations, you will want to additionally have your project
43-
depend on the `opentelemetry-sdk-extension-autoconfigure` module.
44-
4541
For example:
4642

4743
```java
@@ -434,15 +430,7 @@ properties, you can use the `opentelemetry-sdk-extension-autoconfigure` module.
434430
OpenTelemetrySdk sdk = OpenTelemetrySdkAutoConfiguration.initialize();
435431
```
436432

437-
Some of the supported system properties and environment variables:
438-
439-
| System property | Environment variable | Purpose |
440-
|----------------------------------|----------------------------------|-----------------------------------------------------------------------------------------------------|
441-
| otel.trace.sampler | OTEL_TRACE_SAMPLER | Which sampler to use (`parentbased_traceidratio` for example)
442-
| otel.trace.sampler.arg | OTEL_TRACE_SAMPLER_ARG | Used to configured the ratio for the ratio-based sampler (default: 1) |
443-
| otel.span.attribute.count.limit | OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | Max number of attributes per span, extra will be dropped (default: 1000) |
444-
| otel.span.event.count.limit | OTEL_SPAN_EVENT_COUNT_LIMIT | Max number of Events per span, extra will be dropped (default: 1000) |
445-
| otel.span.link.count.limit | OTEL_SPAN_LINK_COUNT_LIMIT | Max number of Link entries per span, extra will be dropped (default: 1000) |
433+
See the supported configuration options in the module's [README](./sdk-extensions/autoconfigure/README.md).
446434

447435
[AlwaysOnSampler]: https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/tracing/src/main/java/io/opentelemetry/sdk/trace/samplers/Sampler.java#L29
448436
[AlwaysOffSampler]:https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/tracing/src/main/java/io/opentelemetry/sdk/trace/samplers/Sampler.java#L40

‎sdk-extensions/autoconfigure/README.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# OpenTelemetry SDK Autoconfigure
2+
3+
This artifact implements environment-based autoconfiguration of the OpenTelemetry SDK. This can be
4+
an alternative to programmatic configuration using the normal SDK builders.
5+
6+
All options support being passed as Java system properties, e.g., `-Dotel.traces.exporter=zipkin` or
7+
environment variables, e.g., `OTEL_TRACES_EXPORTER=zipkin`.
8+
9+
## Contents
10+
11+
* [Exporters](#exporters)
12+
+ [OTLP exporter (both span and metric exporters)](#otlp-exporter--both-span-and-metric-exporters-)
13+
+ [Jaeger exporter](#jaeger-exporter)
14+
+ [Zipkin exporter](#zipkin-exporter)
15+
+ [Prometheus exporter](#prometheus-exporter)
16+
+ [Logging exporter](#logging-exporter)
17+
* [Trace context propagation](#propagator)
18+
* [OpenTelemetry Resource](#opentelemetry-resource)
19+
* [Batch span processor](#batch-span-processor)
20+
* [Sampler](#sampler)
21+
* [Span limits](#span-limits)
22+
* [Interval metric reader](#interval-metric-reader)
23+
* [Customizing the OpenTelemetry SDK](#customizing-the-opentelemetry-sdk)
24+
25+
## Exporters
26+
27+
The following configuration properties are common to all exporters:
28+
29+
| System property | Environment variable | Purpose |
30+
|-----------------|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
31+
| otel.traces.exporter | OTEL_TRACES_EXPORTER | The exporter to be used for tracing. Default is `otlp`. `none` means no autoconfigured exporter. |
32+
| otel.metrics.exporter | OTEL_METRICS_EXPORTER | The exporter to be used for metrics. Default is `otlp`. `none` means no autoconfigured exporter. |
33+
34+
### OTLP exporter (both span and metric exporters)
35+
36+
The [OpenTelemetry Protocol (OTLP)](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/otlp.md) span and metric exporters
37+
38+
| System property | Environment variable | Description |
39+
|------------------------------|-----------------------------|---------------------------------------------------------------------------|
40+
| otel.traces.exporter=otlp (default) | OTEL_TRACES_EXPORTER=otlp | Select the OpenTelemetry exporter for tracing (default) |
41+
| otel.metrics.exporter=otlp (default) | OTEL_METRICS_EXPORTER=otlp | Select the OpenTelemetry exporter for metrics (default) |
42+
| otel.exporter.otlp.endpoint | OTEL_EXPORTER_OTLP_ENDPOINT | The OTLP endpoint to connect to. Must be a URL with a scheme of either `http` or `https` based on the use of TLS. Default is `http://localhost:4317`. |
43+
| otel.exporter.otlp.headers | OTEL_EXPORTER_OTLP_HEADERS | Key-value pairs separated by semicolons to pass as request headers |
44+
| otel.exporter.otlp.timeout | OTEL_EXPORTER_OTLP_TIMEOUT | The maximum waiting time allowed to send each batch. Default is `1000`. |
45+
46+
To configure the service name for the OTLP exporter, add the `service.name` key
47+
to the OpenTelemetry Resource ([see below](#opentelemetry-resource)), e.g. `OTEL_RESOURCE_ATTRIBUTES=service.name=myservice`.
48+
49+
### Jaeger exporter
50+
51+
The [Jaeger](https://www.jaegertracing.io/docs/1.21/apis/#protobuf-via-grpc-stable) exporter. This exporter uses gRPC for its communications protocol.
52+
53+
| System property | Environment variable | Description |
54+
|-----------------------------------|-----------------------------------|----------------------------------------------------------------------------------------------------|
55+
| otel.traces.exporter=jaeger | OTEL_TRACES_EXPORTER=jaeger | Select the Jaeger exporter |
56+
| otel.exporter.jaeger.endpoint | OTEL_EXPORTER_JAEGER_ENDPOINT | The Jaeger gRPC endpoint to connect to. Default is `localhost:14250`. |
57+
58+
### Zipkin exporter
59+
60+
The [Zipkin](https://zipkin.io/zipkin-api/) exporter. It sends JSON in [Zipkin format](https://zipkin.io/zipkin-api/#/default/post_spans) to a specified HTTP URL.
61+
62+
| System property | Environment variable | Description |
63+
|-----------------------------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------|
64+
| otel.traces.exporter=zipkin | OTEL_TRACES_EXPORTER=zipkin | Select the Zipkin exporter |
65+
| otel.exporter.zipkin.endpoint | OTEL_EXPORTER_ZIPKIN_ENDPOINT | The Zipkin endpoint to connect to. Default is `http://localhost:9411/api/v2/spans`. Currently only HTTP is supported. |
66+
67+
### Prometheus exporter
68+
69+
The [Prometheus](https://github.com/prometheus/docs/blob/master/content/docs/instrumenting/exposition_formats.md) exporter.
70+
71+
| System property | Environment variable | Description |
72+
|-------------------------------|-------------------------------|------------------------------------------------------------------------------------|
73+
| otel.metrics.exporter=prometheus | OTEL_METRICS_EXPORTER=prometheus | Select the Prometheus exporter |
74+
| otel.exporter.prometheus.port | OTEL_EXPORTER_PROMETHEUS_PORT | The local port used to bind the prometheus metric server. Default is `9464`. |
75+
| otel.exporter.prometheus.host | OTEL_EXPORTER_PROMETHEUS_HOST | The local address used to bind the prometheus metric server. Default is `0.0.0.0`. |
76+
77+
Note that this is a pull exporter - it opens up a server on the local process listening on the specified host and port, which
78+
a Prometheus server scrapes from.
79+
80+
### Logging exporter
81+
82+
The logging exporter prints the name of the span along with its attributes to stdout. It's mainly used for testing and debugging.
83+
84+
| System property | Environment variable | Description |
85+
|------------------------------|------------------------------|------------------------------------------------------------------------------|
86+
| otel.traces.exporter=logging | OTEL_TRACES_EXPORTER=logging | Select the logging exporter for tracing |
87+
| otel.metrics.exporter=logging | OTEL_METRICS_EXPORTER=logging | Select the logging exporter for metrics |
88+
| otel.exporter.logging.prefix | OTEL_EXPORTER_LOGGING_PREFIX | An optional string printed in front of the span name and attributes. |
89+
90+
## Propagator
91+
92+
The propagators determine which distributed tracing header formats are used, and which baggage propagation header formats are used.
93+
94+
| System property | Environment variable | Description |
95+
|------------------|----------------------|-----------------------------------------------------------------------------------------------------------------|
96+
| otel.propagators | OTEL_PROPAGATORS | The propagators to be used. Use a comma-separated list for multiple propagators. Default is `tracecontext,baggage` (W3C). |
97+
98+
Supported values are
99+
100+
- `"tracecontext"`: [W3C Trace Context](https://www.w3.org/TR/trace-context/) (add `baggage` as well to include W3C baggage)
101+
- `"baggage"`: [W3C Baggage](https://www.w3.org/TR/baggage/)
102+
- `"b3"`: [B3 Single](https://github.com/openzipkin/b3-propagation#single-header)
103+
- `"b3multi"`: [B3 Multi](https://github.com/openzipkin/b3-propagation#multiple-headers)
104+
- `"jaeger"`: [Jaeger](https://www.jaegertracing.io/docs/1.21/client-libraries/#propagation-format) (includes Jaeger baggage)
105+
- `"xray"`: [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader)
106+
- `"ottrace"`: [OT Trace](https://github.com/opentracing?q=basic&type=&language=)
107+
108+
## OpenTelemetry Resource
109+
110+
The [OpenTelemetry Resource](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/resource/sdk.md)
111+
is a representation of the entity producing telemetry.
112+
113+
| System property | Environment variable | Description |
114+
|--------------------------|--------------------------|------------------------------------------------------------------------------------|
115+
| otel.resource.attributes | OTEL_RESOURCE_ATTRIBUTES | Specify resource attributes in the following format: key1=val1,key2=val2,key3=val3 |
116+
117+
You almost always want to specify the [`service.name`](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/resource/semantic_conventions#service) for your application.
118+
It corresponds to how you describe the application, for example `authservice` could be an application that authenticates requests, and `cats` could be an application that returns information about [cats](https://en.wikipedia.org/wiki/Cat).
119+
This means you would specify resource attributes something like `OTEL_RESOURCE_ATTRIBUTES=service.name=authservice`, or `-Dotel.resource.attributes=service.name=cats,service.namespace=mammals`.
120+
121+
## Batch span processor
122+
123+
| System property | Environment variable | Description |
124+
|---------------------------|---------------------------|------------------------------------------------------------------------------------|
125+
| otel.bsp.schedule.delay | OTEL_BSP_SCHEDULE_DELAY | The interval, in milliseconds, between two consecutive exports. Default is `5000`. |
126+
| otel.bsp.max.queue.size | OTEL_BSP_MAX_QUEUE_SIZE | The maximum queue size. Default is `2048`. |
127+
| otel.bsp.max.export.batch.size | OTEL_BSP_MAX_EXPORT_BATCH_SIZE | The maximum batch size. Default is `512`. |
128+
| otel.bsp.export.timeout | OTEL_BSP_EXPORT_TIMEOUT | The maximum allowed time, in milliseconds, to export data. Default is `30000`. |
129+
130+
## Sampler
131+
132+
The sampler configures whether spans will be recorded for any call to `SpanBuilder.startSpan`.
133+
134+
| System property | Environment variable | Description |
135+
|---------------------------------|---------------------------------|--------------------------------------------------------------|
136+
| otel.traces.sampler | OTEL_TRACES_SAMPLER | The sampler to use for tracing. Defaults to `parentbased_always_on` |
137+
| otel.traces.sampler.arg | OTEL_TRACES_SAMPLER_ARG | An argument to the configured tracer if supported, for example a ratio. |
138+
139+
Supported values for `otel.traces.sampler` are
140+
141+
- "always_on": AlwaysOnSampler
142+
- "always_off": AlwaysOffSampler
143+
- "traceidratio": TraceIdRatioBased. `otel.traces.sampler.arg` sets the ratio.
144+
- "parentbased_always_on": ParentBased(root=AlwaysOnSampler)
145+
- "parentbased_always_off": ParentBased(root=AlwaysOffSampler)
146+
- "parentbased_traceidratio": ParentBased(root=TraceIdRatioBased). `otel.traces.sampler.arg` sets the ratio.
147+
148+
## Span limits
149+
150+
These properties can be used to control the maximum size of recordings per span.
151+
152+
| System property | Environment variable | Description |
153+
|---------------------------------|---------------------------------|--------------------------------------------------------------|
154+
| otel.span.attribute.count.limit | OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | The maximum number of attributes per span. Default is `128`. |
155+
| otel.span.event.count.limit | OTEL_SPAN_EVENT_COUNT_LIMIT | The maximum number of events per span. Default is `128`. |
156+
| otel.span.link.count.limit | OTEL_SPAN_LINK_COUNT_LIMIT | The maximum number of links per span. Default is `128` |
157+
158+
## Interval metric reader
159+
160+
| System property | Environment variable | Description |
161+
|--------------------------|--------------------------|-----------------------------------------------------------------------------------|
162+
| otel.imr.export.interval | OTEL_IMR_EXPORT_INTERVAL | The interval, in milliseconds, between pushes to the exporter. Default is `60000`.|
163+
164+
## Customizing the OpenTelemetry SDK
165+
166+
Autoconfiguration exposes SPI [hooks](./src/main/java/io/opentelemetry/sdk/autoconfigure/spi) for customizing behavior programmatically as needed.
167+
It's recommended to use the above configuration properties where possible, only implementing the SPI to add functionality not found in the
168+
SDK by default.

0 commit comments

Comments
 (0)