Skip to content

Commit 7662d83

Browse files
aabmassaabmass
authored
Improve documentation around environment variables (#1680)
1 parent 826a790 commit 7662d83

File tree

8 files changed

+244
-42
lines changed

8 files changed

+244
-42
lines changed

‎CHANGELOG.md

+2
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
5252
([#1684](https://github.com/open-telemetry/opentelemetry-python/pull/1684))
5353
- Cleanup OTLP exporter compression options, add tests
5454
([#1671](https://github.com/open-telemetry/opentelemetry-python/pull/1671))
55+
- Initial documentation for environment variables
56+
([#1680](https://github.com/open-telemetry/opentelemetry-python/pull/1680))
5557

5658
### Removed
5759
- Removed unused `get_hexadecimal_trace_id` and `get_hexadecimal_span_id` methods.

‎exporter/opentelemetry-exporter-jaeger/src/opentelemetry/exporter/jaeger/__init__.py

+10
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,16 @@
5959
with tracer.start_as_current_span('foo'):
6060
print('Hello world!')
6161
62+
You can configure the exporter with the following environment variables:
63+
64+
- :envvar:`OTEL_EXPORTER_JAEGER_USER`
65+
- :envvar:`OTEL_EXPORTER_JAEGER_PASSWORD`
66+
- :envvar:`OTEL_EXPORTER_JAEGER_INSECURE`
67+
- :envvar:`OTEL_EXPORTER_JAEGER_ENDPOINT`
68+
- :envvar:`OTEL_EXPORTER_JAEGER_CERTIFICATE`
69+
- :envvar:`OTEL_EXPORTER_JAEGER_AGENT_PORT`
70+
- :envvar:`OTEL_EXPORTER_JAEGER_AGENT_HOST`
71+
6272
API
6373
---
6474
.. _Jaeger: https://www.jaegertracing.io/

‎exporter/opentelemetry-exporter-otlp/src/opentelemetry/exporter/otlp/__init__.py

+16-10
Original file line numberDiff line numberDiff line change
@@ -22,20 +22,26 @@
2222
The **OTLP Span Exporter** allows to export `OpenTelemetry`_ traces to the
2323
`OTLP`_ collector.
2424
25+
You can configure the exporter with the following environment variables:
26+
27+
- :envvar:`OTEL_EXPORTER_OTLP_TRACES_TIMEOUT`
28+
- :envvar:`OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`
29+
- :envvar:`OTEL_EXPORTER_OTLP_TRACES_INSECURE`
30+
- :envvar:`OTEL_EXPORTER_OTLP_TRACES_HEADERS`
31+
- :envvar:`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`
32+
- :envvar:`OTEL_EXPORTER_OTLP_TRACES_COMPRESSION`
33+
- :envvar:`OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE`
34+
- :envvar:`OTEL_EXPORTER_OTLP_TIMEOUT`
35+
- :envvar:`OTEL_EXPORTER_OTLP_PROTOCOL`
36+
- :envvar:`OTEL_EXPORTER_OTLP_INSECURE`
37+
- :envvar:`OTEL_EXPORTER_OTLP_HEADERS`
38+
- :envvar:`OTEL_EXPORTER_OTLP_ENDPOINT`
39+
- :envvar:`OTEL_EXPORTER_OTLP_COMPRESSION`
40+
- :envvar:`OTEL_EXPORTER_OTLP_CERTIFICATE`
2541
2642
.. _OTLP: https://github.com/open-telemetry/opentelemetry-collector/
2743
.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/
2844
29-
.. envvar:: OTEL_EXPORTER_OTLP_COMPRESSION
30-
31-
The :envvar:`OTEL_EXPORTER_OTLP_COMPRESSION` environment variable allows a
32-
compression algorithm to be passed to the OTLP exporter. The compression
33-
algorithms that are supported include gzip and no compression. The value should
34-
be in the format of a string "gzip" for gzip compression, and no value specified
35-
if no compression is the desired choice.
36-
Additional details are available `in the specification
37-
<https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#opentelemetry-protocol-exporter>`_.
38-
3945
.. code:: python
4046
4147
from opentelemetry import trace

‎exporter/opentelemetry-exporter-zipkin/src/opentelemetry/exporter/zipkin/__init__.py

+1-5
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,6 @@
2727
.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/
2828
.. _Specification: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md#zipkin-exporter
2929
30-
.. envvar:: OTEL_EXPORTER_ZIPKIN_ENDPOINT
31-
3230
.. code:: python
3331
3432
from opentelemetry import trace
@@ -61,9 +59,7 @@
6159
6260
The exporter supports the following environment variable for configuration:
6361
64-
:envvar:`OTEL_EXPORTER_ZIPKIN_ENDPOINT`: zipkin collector endpoint to which the
65-
exporter will send data. This may include a path (e.g.
66-
http://example.com:9411/api/v2/spans).
62+
- :envvar:`OTEL_EXPORTER_ZIPKIN_ENDPOINT`
6763
6864
API
6965
---

‎opentelemetry-api/src/opentelemetry/environment_variables/__init__.py

+27
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,36 @@
1313
# limitations under the License.
1414

1515
OTEL_PROPAGATORS = "OTEL_PROPAGATORS"
16+
"""
17+
.. envvar:: OTEL_PROPAGATORS
18+
"""
19+
1620
OTEL_PYTHON_CONTEXT = "OTEL_PYTHON_CONTEXT"
21+
"""
22+
.. envvar:: OTEL_PYTHON_CONTEXT
23+
"""
24+
1725
OTEL_PYTHON_DISABLED_INSTRUMENTATIONS = "OTEL_PYTHON_DISABLED_INSTRUMENTATIONS"
26+
"""
27+
.. envvar:: OTEL_PYTHON_DISABLED_INSTRUMENTATIONS
28+
"""
29+
1830
OTEL_PYTHON_ID_GENERATOR = "OTEL_PYTHON_ID_GENERATOR"
31+
"""
32+
.. envvar:: OTEL_PYTHON_ID_GENERATOR
33+
"""
34+
1935
OTEL_PYTHON_SERVICE_NAME = "OTEL_PYTHON_SERVICE_NAME"
36+
"""
37+
.. envvar:: OTEL_PYTHON_SERVICE_NAME
38+
"""
39+
2040
OTEL_TRACES_EXPORTER = "OTEL_TRACES_EXPORTER"
41+
"""
42+
.. envvar:: OTEL_TRACES_EXPORTER
43+
"""
44+
2145
OTEL_PYTHON_TRACER_PROVIDER = "OTEL_PYTHON_TRACER_PROVIDER"
46+
"""
47+
.. envvar:: OTEL_PYTHON_TRACER_PROVIDER
48+
"""

‎opentelemetry-sdk/src/opentelemetry/sdk/environment_variables/__init__.py

+179-3
Original file line numberDiff line numberDiff line change
@@ -13,39 +13,215 @@
1313
# limitations under the License.
1414

1515
OTEL_RESOURCE_ATTRIBUTES = "OTEL_RESOURCE_ATTRIBUTES"
16+
"""
17+
.. envvar:: OTEL_RESOURCE_ATTRIBUTES
18+
19+
The :envvar:`OTEL_RESOURCE_ATTRIBUTES` environment variable allows resource
20+
attributes to be passed to the SDK at process invocation. The attributes from
21+
:envvar:`OTEL_RESOURCE_ATTRIBUTES` are merged with those passed to
22+
`Resource.create`, meaning :envvar:`OTEL_RESOURCE_ATTRIBUTES` takes *lower*
23+
priority. Attributes should be in the format ``key1=value1,key2=value2``.
24+
Additional details are available `in the specification
25+
<https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md#specifying-resource-information-via-an-environment-variable>`__.
26+
27+
.. code-block:: console
28+
29+
$ OTEL_RESOURCE_ATTRIBUTES="service.name=shoppingcard,will_be_overridden=foo" python - <<EOF
30+
import pprint
31+
from opentelemetry.sdk.resources import Resource
32+
pprint.pprint(Resource.create({"will_be_overridden": "bar"}).attributes)
33+
EOF
34+
{'service.name': 'shoppingcard',
35+
'telemetry.sdk.language': 'python',
36+
'telemetry.sdk.name': 'opentelemetry',
37+
'telemetry.sdk.version': '0.13.dev0',
38+
'will_be_overridden': 'bar'}
39+
"""
40+
1641
OTEL_LOG_LEVEL = "OTEL_LOG_LEVEL"
42+
"""
43+
.. envvar:: OTEL_LOG_LEVEL
44+
"""
45+
1746
OTEL_TRACES_SAMPLER = "OTEL_TRACES_SAMPLER"
47+
"""
48+
.. envvar:: OTEL_TRACES_SAMPLER
49+
"""
50+
1851
OTEL_TRACES_SAMPLER_ARG = "OTEL_TRACES_SAMPLER_ARG"
52+
"""
53+
.. envvar:: OTEL_TRACES_SAMPLER_ARG
54+
"""
55+
1956
OTEL_BSP_SCHEDULE_DELAY = "OTEL_BSP_SCHEDULE_DELAY"
57+
"""
58+
.. envvar:: OTEL_BSP_SCHEDULE_DELAY
59+
"""
60+
2061
OTEL_BSP_EXPORT_TIMEOUT = "OTEL_BSP_EXPORT_TIMEOUT"
62+
"""
63+
.. envvar:: OTEL_BSP_EXPORT_TIMEOUT
64+
"""
65+
2166
OTEL_BSP_MAX_QUEUE_SIZE = "OTEL_BSP_MAX_QUEUE_SIZE"
67+
"""
68+
.. envvar:: OTEL_BSP_MAX_QUEUE_SIZE
69+
"""
70+
2271
OTEL_BSP_MAX_EXPORT_BATCH_SIZE = "OTEL_BSP_MAX_EXPORT_BATCH_SIZE"
72+
"""
73+
.. envvar:: OTEL_BSP_MAX_EXPORT_BATCH_SIZE
74+
"""
75+
2376
OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT = "OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT"
77+
"""
78+
.. envvar:: OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT
79+
"""
80+
2481
OTEL_SPAN_EVENT_COUNT_LIMIT = "OTEL_SPAN_EVENT_COUNT_LIMIT"
82+
"""
83+
.. envvar:: OTEL_SPAN_EVENT_COUNT_LIMIT
84+
"""
85+
2586
OTEL_SPAN_LINK_COUNT_LIMIT = "OTEL_SPAN_LINK_COUNT_LIMIT"
87+
"""
88+
.. envvar:: OTEL_SPAN_LINK_COUNT_LIMIT
89+
"""
90+
2691
OTEL_EXPORTER_JAEGER_AGENT_HOST = "OTEL_EXPORTER_JAEGER_AGENT_HOST"
92+
"""
93+
.. envvar:: OTEL_EXPORTER_JAEGER_AGENT_HOST
94+
"""
95+
2796
OTEL_EXPORTER_JAEGER_AGENT_PORT = "OTEL_EXPORTER_JAEGER_AGENT_PORT"
97+
"""
98+
.. envvar:: OTEL_EXPORTER_JAEGER_AGENT_PORT
99+
"""
100+
28101
OTEL_EXPORTER_JAEGER_ENDPOINT = "OTEL_EXPORTER_JAEGER_ENDPOINT"
102+
"""
103+
.. envvar:: OTEL_EXPORTER_JAEGER_ENDPOINT
104+
"""
105+
29106
OTEL_EXPORTER_JAEGER_USER = "OTEL_EXPORTER_JAEGER_USER"
107+
"""
108+
.. envvar:: OTEL_EXPORTER_JAEGER_USER
109+
"""
110+
30111
OTEL_EXPORTER_JAEGER_PASSWORD = "OTEL_EXPORTER_JAEGER_PASSWORD"
112+
"""
113+
.. envvar:: OTEL_EXPORTER_JAEGER_PASSWORD
114+
"""
115+
116+
31117
OTEL_EXPORTER_ZIPKIN_ENDPOINT = "OTEL_EXPORTER_ZIPKIN_ENDPOINT"
32-
OTEL_EXPORTER_ENDPOINT = "OTEL_EXPORTER_ENDPOINT"
118+
"""
119+
.. envvar:: OTEL_EXPORTER_ZIPKIN_ENDPOINT
120+
121+
Zipkin collector endpoint to which the exporter will send data. This may
122+
include a path (e.g. ``http://example.com:9411/api/v2/spans``).
123+
"""
124+
33125
OTEL_EXPORTER_OTLP_PROTOCOL = "OTEL_EXPORTER_OTLP_PROTOCOL"
126+
"""
127+
.. envvar:: OTEL_EXPORTER_OTLP_PROTOCOL
128+
"""
129+
34130
OTEL_EXPORTER_OTLP_CERTIFICATE = "OTEL_EXPORTER_OTLP_CERTIFICATE"
131+
"""
132+
.. envvar:: OTEL_EXPORTER_OTLP_CERTIFICATE
133+
"""
134+
35135
OTEL_EXPORTER_OTLP_HEADERS = "OTEL_EXPORTER_OTLP_HEADERS"
136+
"""
137+
.. envvar:: OTEL_EXPORTER_OTLP_HEADERS
138+
"""
139+
140+
36141
OTEL_EXPORTER_OTLP_COMPRESSION = "OTEL_EXPORTER_OTLP_COMPRESSION"
142+
"""
143+
.. envvar:: OTEL_EXPORTER_OTLP_COMPRESSION
144+
145+
Specifies a gRPC compression method to be used in the OTLP exporters.
146+
Possible values are:
147+
148+
- ``gzip`` corresponding to `grpc.Compression.Gzip`.
149+
- ``deflate`` corresponding to `grpc.Compression.Deflate`.
150+
151+
If no ``OTEL_EXPORTER_OTLP_*COMPRESSION`` environment variable is present or
152+
``compression`` argument passed to the exporter, the default
153+
`grpc.Compression.NoCompression` will be used. Additional details are
154+
available `in the specification
155+
<https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#opentelemetry-protocol-exporter>`__.
156+
"""
157+
37158
OTEL_EXPORTER_OTLP_TIMEOUT = "OTEL_EXPORTER_OTLP_TIMEOUT"
159+
"""
160+
.. envvar:: OTEL_EXPORTER_OTLP_TIMEOUT
161+
"""
162+
38163
OTEL_EXPORTER_OTLP_ENDPOINT = "OTEL_EXPORTER_OTLP_ENDPOINT"
164+
"""
165+
.. envvar:: OTEL_EXPORTER_OTLP_ENDPOINT
166+
"""
167+
39168
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"
169+
"""
170+
.. envvar:: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
171+
"""
172+
40173
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL = "OTEL_EXPORTER_OTLP_TRACES_PROTOCOL"
174+
"""
175+
.. envvar:: OTEL_EXPORTER_OTLP_TRACES_PROTOCOL
176+
"""
177+
41178
OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE = "OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE"
179+
"""
180+
.. envvar:: OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE
181+
"""
182+
42183
OTEL_EXPORTER_OTLP_TRACES_HEADERS = "OTEL_EXPORTER_OTLP_TRACES_HEADERS"
184+
"""
185+
.. envvar:: OTEL_EXPORTER_OTLP_TRACES_HEADERS
186+
"""
187+
188+
43189
OTEL_EXPORTER_OTLP_TRACES_COMPRESSION = "OTEL_EXPORTER_OTLP_TRACES_COMPRESSION"
190+
"""
191+
.. envvar:: OTEL_EXPORTER_OTLP_TRACES_COMPRESSION
192+
193+
Same as :envvar:`OTEL_EXPORTER_OTLP_COMPRESSION` but only for the span
194+
exporter. If both are present, this takes higher precendence.
195+
"""
196+
44197
OTEL_EXPORTER_OTLP_TRACES_TIMEOUT = "OTEL_EXPORTER_OTLP_TRACES_TIMEOUT"
198+
"""
199+
.. envvar:: OTEL_EXPORTER_OTLP_TRACES_TIMEOUT
200+
"""
201+
45202
OTEL_EXPORTER_JAEGER_INSECURE = "OTEL_EXPORTER_JAEGER_INSECURE"
203+
"""
204+
.. envvar:: OTEL_EXPORTER_JAEGER_INSECURE
205+
"""
206+
46207
OTEL_EXPORTER_JAEGER_CERTIFICATE = "OTEL_EXPORTER_JAEGER_CERTIFICATE"
47-
OTEL_EXPORTER_OTLP_INSECURE = "OTEL_EXPORTER_OTLP_INSECURE"
48-
OTEL_EXPORTER_OTLP_TRACES_INSECURE = "OTEL_EXPORTER_OTLP_TRACES_INSECURE"
208+
"""
209+
.. envvar:: OTEL_EXPORTER_JAEGER_CERTIFICATE
210+
"""
211+
49212
OTEL_EXPORTER_JAEGER_AGENT_SPLIT_OVERSIZED_BATCHES = (
50213
"OTEL_EXPORTER_JAEGER_AGENT_SPLIT_OVERSIZED_BATCHES"
51214
)
215+
"""
216+
.. envvar:: OTEL_EXPORTER_JAEGER_AGENT_SPLIT_OVERSIZED_BATCHES
217+
"""
218+
219+
OTEL_EXPORTER_OTLP_INSECURE = "OTEL_EXPORTER_OTLP_INSECURE"
220+
"""
221+
.. envvar:: OTEL_EXPORTER_OTLP_INSECURE
222+
"""
223+
224+
OTEL_EXPORTER_OTLP_TRACES_INSECURE = "OTEL_EXPORTER_OTLP_TRACES_INSECURE"
225+
"""
226+
.. envvar:: OTEL_EXPORTER_OTLP_TRACES_INSECURE
227+
"""

‎opentelemetry-sdk/src/opentelemetry/sdk/resources/__init__.py

-23
Original file line numberDiff line numberDiff line change
@@ -53,29 +53,6 @@
5353
<https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/README.md>`_
5454
that have prescribed semantic meanings, for example ``service.name`` in the
5555
above example.
56-
57-
.. envvar:: OTEL_RESOURCE_ATTRIBUTES
58-
59-
The :envvar:`OTEL_RESOURCE_ATTRIBUTES` environment variable allows resource
60-
attributes to be passed to the SDK at process invocation. The attributes from
61-
:envvar:`OTEL_RESOURCE_ATTRIBUTES` are merged with those passed to
62-
`Resource.create`, meaning :envvar:`OTEL_RESOURCE_ATTRIBUTES` takes *lower*
63-
priority. Attributes should be in the format ``key1=value1,key2=value2``.
64-
Additional details are available `in the specification
65-
<https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md#specifying-resource-information-via-an-environment-variable>`_.
66-
67-
.. code-block:: console
68-
69-
$ OTEL_RESOURCE_ATTRIBUTES="service.name=shoppingcard,will_be_overridden=foo" python - <<EOF
70-
import pprint
71-
from opentelemetry.sdk.resources import Resource
72-
pprint.pprint(Resource.create({"will_be_overridden": "bar"}).attributes)
73-
EOF
74-
{'service.name': 'shoppingcard',
75-
'telemetry.sdk.language': 'python',
76-
'telemetry.sdk.name': 'opentelemetry',
77-
'telemetry.sdk.version': '0.13.dev0',
78-
'will_be_overridden': 'bar'}
7956
"""
8057

8158
import abc

‎opentelemetry-sdk/src/opentelemetry/sdk/trace/export/__init__.py

+9-1
Original file line numberDiff line numberDiff line change
@@ -115,8 +115,16 @@ def __init__(self):
115115
class BatchSpanProcessor(SpanProcessor):
116116
"""Batch span processor implementation.
117117
118-
BatchSpanProcessor is an implementation of `SpanProcessor` that
118+
`BatchSpanProcessor` is an implementation of `SpanProcessor` that
119119
batches ended spans and pushes them to the configured `SpanExporter`.
120+
121+
`BatchSpanProcessor` is configurable with the following environment
122+
variables which correspond to constructor parameters:
123+
124+
- :envvar:`OTEL_BSP_SCHEDULE_DELAY`
125+
- :envvar:`OTEL_BSP_MAX_QUEUE_SIZE`
126+
- :envvar:`OTEL_BSP_MAX_EXPORT_BATCH_SIZE`
127+
- :envvar:`OTEL_BSP_EXPORT_TIMEOUT`
120128
"""
121129

122130
def __init__(

0 commit comments

Comments
 (0)