Improve documentation around environment variables

CHANGELOG.md

@@ -52,6 +52,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#1684](https://github.com/open-telemetry/opentelemetry-python/pull/1684))
 - Cleanup OTLP exporter compression options, add tests
   ([#1671](https://github.com/open-telemetry/opentelemetry-python/pull/1671))
+- Document environment variables
+  ([#1680](https://github.com/open-telemetry/opentelemetry-python/pull/1680))
 
 ### Removed
 - Removed unused `get_hexadecimal_trace_id` and `get_hexadecimal_span_id` methods.

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

@@ -59,6 +59,16 @@
     with tracer.start_as_current_span('foo'):
         print('Hello world!')
 
+You can configure the exporter with the following environment variables:
+
+- :envvar:`OTEL_EXPORTER_JAEGER_USER`
+- :envvar:`OTEL_EXPORTER_JAEGER_PASSWORD`
+- :envvar:`OTEL_EXPORTER_JAEGER_INSECURE`
+- :envvar:`OTEL_EXPORTER_JAEGER_ENDPOINT`
+- :envvar:`OTEL_EXPORTER_JAEGER_CERTIFICATE`
+- :envvar:`OTEL_EXPORTER_JAEGER_AGENT_PORT`
+- :envvar:`OTEL_EXPORTER_JAEGER_AGENT_HOST`
+
 API
 ---
 .. _Jaeger: https://www.jaegertracing.io/

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

@@ -22,20 +22,26 @@
 The **OTLP Span Exporter** allows to export `OpenTelemetry`_ traces to the
 `OTLP`_ collector.
 
+You can configure the exporter with the following environment variables:
+
+- :envvar:`OTEL_EXPORTER_OTLP_TRACES_TIMEOUT`
+- :envvar:`OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`
+- :envvar:`OTEL_EXPORTER_OTLP_TRACES_INSECURE`
+- :envvar:`OTEL_EXPORTER_OTLP_TRACES_HEADERS`
+- :envvar:`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`
+- :envvar:`OTEL_EXPORTER_OTLP_TRACES_COMPRESSION`
+- :envvar:`OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE`
+- :envvar:`OTEL_EXPORTER_OTLP_TIMEOUT`
+- :envvar:`OTEL_EXPORTER_OTLP_PROTOCOL`
+- :envvar:`OTEL_EXPORTER_OTLP_INSECURE`
+- :envvar:`OTEL_EXPORTER_OTLP_HEADERS`
+- :envvar:`OTEL_EXPORTER_OTLP_ENDPOINT`
+- :envvar:`OTEL_EXPORTER_OTLP_COMPRESSION`
+- :envvar:`OTEL_EXPORTER_OTLP_CERTIFICATE`
 
 .. _OTLP: https://github.com/open-telemetry/opentelemetry-collector/
 .. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/
 
-.. envvar:: OTEL_EXPORTER_OTLP_COMPRESSION
-
-The :envvar:`OTEL_EXPORTER_OTLP_COMPRESSION` environment variable allows a
-compression algorithm to be passed to the OTLP exporter. The compression
-algorithms that are supported include gzip and no compression. The value should
-be in the format of a string "gzip" for gzip compression, and no value specified
-if no compression is the desired choice.
-Additional details are available `in the specification
-<https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#opentelemetry-protocol-exporter>`_.
-
 .. code:: python
 
     from opentelemetry import trace

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

@@ -27,8 +27,6 @@
 .. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/
 .. _Specification: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md#zipkin-exporter
 
-.. envvar:: OTEL_EXPORTER_ZIPKIN_ENDPOINT
-
 .. code:: python
 
     from opentelemetry import trace
@@ -61,9 +59,7 @@
 
 The exporter supports the following environment variable for configuration:
 
-:envvar:`OTEL_EXPORTER_ZIPKIN_ENDPOINT`: zipkin collector endpoint to which the
-exporter will send data. This may include a path (e.g.
-http://example.com:9411/api/v2/spans).
+- :envvar:`OTEL_EXPORTER_ZIPKIN_ENDPOINT`
 
 API
 ---

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

@@ -13,9 +13,36 @@
 # limitations under the License.
 
 OTEL_PROPAGATORS = "OTEL_PROPAGATORS"
+"""
+.. envvar:: OTEL_PROPAGATORS
+"""
+
 OTEL_PYTHON_CONTEXT = "OTEL_PYTHON_CONTEXT"
+"""
+.. envvar:: OTEL_PYTHON_CONTEXT
+"""
+
 OTEL_PYTHON_DISABLED_INSTRUMENTATIONS = "OTEL_PYTHON_DISABLED_INSTRUMENTATIONS"
+"""
+.. envvar:: OTEL_PYTHON_DISABLED_INSTRUMENTATIONS
+"""
+
 OTEL_PYTHON_ID_GENERATOR = "OTEL_PYTHON_ID_GENERATOR"
+"""
+.. envvar:: OTEL_PYTHON_ID_GENERATOR
+"""
+
 OTEL_PYTHON_SERVICE_NAME = "OTEL_PYTHON_SERVICE_NAME"
+"""
+.. envvar:: OTEL_PYTHON_SERVICE_NAME
+"""
+
 OTEL_TRACES_EXPORTER = "OTEL_TRACES_EXPORTER"
+"""
+.. envvar:: OTEL_TRACES_EXPORTER
+"""
+
 OTEL_PYTHON_TRACER_PROVIDER = "OTEL_PYTHON_TRACER_PROVIDER"
+"""
+.. envvar:: OTEL_PYTHON_TRACER_PROVIDER
+"""

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

@@ -13,39 +13,215 @@
 # limitations under the License.
 
 OTEL_RESOURCE_ATTRIBUTES = "OTEL_RESOURCE_ATTRIBUTES"
+"""
+.. envvar:: OTEL_RESOURCE_ATTRIBUTES
+
+The :envvar:`OTEL_RESOURCE_ATTRIBUTES` environment variable allows resource
+attributes to be passed to the SDK at process invocation. The attributes from
+:envvar:`OTEL_RESOURCE_ATTRIBUTES` are merged with those passed to
+`Resource.create`, meaning :envvar:`OTEL_RESOURCE_ATTRIBUTES` takes *lower*
+priority. Attributes should be in the format ``key1=value1,key2=value2``.
+Additional details are available `in the specification
+<https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md#specifying-resource-information-via-an-environment-variable>`__.
+
+.. code-block:: console
+
+    $ OTEL_RESOURCE_ATTRIBUTES="service.name=shoppingcard,will_be_overridden=foo" python - <<EOF
+    import pprint
+    from opentelemetry.sdk.resources import Resource
+    pprint.pprint(Resource.create({"will_be_overridden": "bar"}).attributes)
+    EOF
+    {'service.name': 'shoppingcard',
+    'telemetry.sdk.language': 'python',
+    'telemetry.sdk.name': 'opentelemetry',
+    'telemetry.sdk.version': '0.13.dev0',
+    'will_be_overridden': 'bar'}
+"""
+
 OTEL_LOG_LEVEL = "OTEL_LOG_LEVEL"
+"""
+.. envvar:: OTEL_LOG_LEVEL
+"""
+
 OTEL_TRACES_SAMPLER = "OTEL_TRACES_SAMPLER"
+"""
+.. envvar:: OTEL_TRACES_SAMPLER
+"""
+
 OTEL_TRACES_SAMPLER_ARG = "OTEL_TRACES_SAMPLER_ARG"
+"""
+.. envvar:: OTEL_TRACES_SAMPLER_ARG
+"""
+
 OTEL_BSP_SCHEDULE_DELAY = "OTEL_BSP_SCHEDULE_DELAY"
+"""
+.. envvar:: OTEL_BSP_SCHEDULE_DELAY
+"""
+
 OTEL_BSP_EXPORT_TIMEOUT = "OTEL_BSP_EXPORT_TIMEOUT"
+"""
+.. envvar:: OTEL_BSP_EXPORT_TIMEOUT
+"""
+
 OTEL_BSP_MAX_QUEUE_SIZE = "OTEL_BSP_MAX_QUEUE_SIZE"
+"""
+.. envvar:: OTEL_BSP_MAX_QUEUE_SIZE
+"""
+
 OTEL_BSP_MAX_EXPORT_BATCH_SIZE = "OTEL_BSP_MAX_EXPORT_BATCH_SIZE"
+"""
+.. envvar:: OTEL_BSP_MAX_EXPORT_BATCH_SIZE
+"""
+
 OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT = "OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT"
+"""
+.. envvar:: OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT
+"""
+
 OTEL_SPAN_EVENT_COUNT_LIMIT = "OTEL_SPAN_EVENT_COUNT_LIMIT"
+"""
+.. envvar:: OTEL_SPAN_EVENT_COUNT_LIMIT
+"""
+
 OTEL_SPAN_LINK_COUNT_LIMIT = "OTEL_SPAN_LINK_COUNT_LIMIT"
+"""
+.. envvar:: OTEL_SPAN_LINK_COUNT_LIMIT
+"""
+
 OTEL_EXPORTER_JAEGER_AGENT_HOST = "OTEL_EXPORTER_JAEGER_AGENT_HOST"
+"""
+.. envvar:: OTEL_EXPORTER_JAEGER_AGENT_HOST
+"""
+
 OTEL_EXPORTER_JAEGER_AGENT_PORT = "OTEL_EXPORTER_JAEGER_AGENT_PORT"
+"""
+.. envvar:: OTEL_EXPORTER_JAEGER_AGENT_PORT
+"""
+
 OTEL_EXPORTER_JAEGER_ENDPOINT = "OTEL_EXPORTER_JAEGER_ENDPOINT"
+"""
+.. envvar:: OTEL_EXPORTER_JAEGER_ENDPOINT
+"""
+
 OTEL_EXPORTER_JAEGER_USER = "OTEL_EXPORTER_JAEGER_USER"
+"""
+.. envvar:: OTEL_EXPORTER_JAEGER_USER
+"""
+
 OTEL_EXPORTER_JAEGER_PASSWORD = "OTEL_EXPORTER_JAEGER_PASSWORD"
+"""
+.. envvar:: OTEL_EXPORTER_JAEGER_PASSWORD
+"""
+
+
 OTEL_EXPORTER_ZIPKIN_ENDPOINT = "OTEL_EXPORTER_ZIPKIN_ENDPOINT"
-OTEL_EXPORTER_ENDPOINT = "OTEL_EXPORTER_ENDPOINT"
+"""
+.. envvar:: OTEL_EXPORTER_ZIPKIN_ENDPOINT
+
+Zipkin collector endpoint to which the exporter will send data. This may
+include a path (e.g. ``http://example.com:9411/api/v2/spans``).
+"""
+
 OTEL_EXPORTER_OTLP_PROTOCOL = "OTEL_EXPORTER_OTLP_PROTOCOL"
+"""
+.. envvar:: OTEL_EXPORTER_OTLP_PROTOCOL
+"""
+
 OTEL_EXPORTER_OTLP_CERTIFICATE = "OTEL_EXPORTER_OTLP_CERTIFICATE"
+"""
+.. envvar:: OTEL_EXPORTER_OTLP_CERTIFICATE
+"""
+
 OTEL_EXPORTER_OTLP_HEADERS = "OTEL_EXPORTER_OTLP_HEADERS"
+"""
+.. envvar:: OTEL_EXPORTER_OTLP_HEADERS
+"""
+
+
 OTEL_EXPORTER_OTLP_COMPRESSION = "OTEL_EXPORTER_OTLP_COMPRESSION"
+"""
+.. envvar:: OTEL_EXPORTER_OTLP_COMPRESSION
+
+Specifies a gRPC compression method to be used in the OTLP exporters.
+Possible values are:
+
+- ``gzip`` corresponding to `grpc.Compression.Gzip`.
+- ``deflate`` corresponding to `grpc.Compression.Deflate`.
+
+If no ``OTEL_EXPORTER_OTLP_*COMPRESSION`` environment variable is present or
+``compression`` argument passed to the exporter, the default
+`grpc.Compression.NoCompression` will be used. Additional details are
+available `in the specification
+<https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#opentelemetry-protocol-exporter>`__.
+"""
+
 OTEL_EXPORTER_OTLP_TIMEOUT = "OTEL_EXPORTER_OTLP_TIMEOUT"
+"""
+.. envvar:: OTEL_EXPORTER_OTLP_TIMEOUT
+"""
+
 OTEL_EXPORTER_OTLP_ENDPOINT = "OTEL_EXPORTER_OTLP_ENDPOINT"
+"""
+.. envvar:: OTEL_EXPORTER_OTLP_ENDPOINT
+"""
+
 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"
+"""
+.. envvar:: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
+"""
+
 OTEL_EXPORTER_OTLP_TRACES_PROTOCOL = "OTEL_EXPORTER_OTLP_TRACES_PROTOCOL"
+"""
+.. envvar:: OTEL_EXPORTER_OTLP_TRACES_PROTOCOL
+"""
+
 OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE = "OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE"
+"""
+.. envvar:: OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE
+"""
+
 OTEL_EXPORTER_OTLP_TRACES_HEADERS = "OTEL_EXPORTER_OTLP_TRACES_HEADERS"
+"""
+.. envvar:: OTEL_EXPORTER_OTLP_TRACES_HEADERS
+"""
+
+
 OTEL_EXPORTER_OTLP_TRACES_COMPRESSION = "OTEL_EXPORTER_OTLP_TRACES_COMPRESSION"
+"""
+.. envvar:: OTEL_EXPORTER_OTLP_TRACES_COMPRESSION
+
+Same as :envvar:`OTEL_EXPORTER_OTLP_COMPRESSION` but only for the span
+exporter. If both are present, this takes higher precendence.
+"""
+
 OTEL_EXPORTER_OTLP_TRACES_TIMEOUT = "OTEL_EXPORTER_OTLP_TRACES_TIMEOUT"
+"""
+.. envvar:: OTEL_EXPORTER_OTLP_TRACES_TIMEOUT
+"""
+
 OTEL_EXPORTER_JAEGER_INSECURE = "OTEL_EXPORTER_JAEGER_INSECURE"
+"""
+.. envvar:: OTEL_EXPORTER_JAEGER_INSECURE
+"""
+
 OTEL_EXPORTER_JAEGER_CERTIFICATE = "OTEL_EXPORTER_JAEGER_CERTIFICATE"
-OTEL_EXPORTER_OTLP_INSECURE = "OTEL_EXPORTER_OTLP_INSECURE"
-OTEL_EXPORTER_OTLP_TRACES_INSECURE = "OTEL_EXPORTER_OTLP_TRACES_INSECURE"
+"""
+.. envvar:: OTEL_EXPORTER_JAEGER_CERTIFICATE
+"""
+
 OTEL_EXPORTER_JAEGER_AGENT_SPLIT_OVERSIZED_BATCHES = (
     "OTEL_EXPORTER_JAEGER_AGENT_SPLIT_OVERSIZED_BATCHES"
 )
+"""
+.. envvar:: OTEL_EXPORTER_JAEGER_AGENT_SPLIT_OVERSIZED_BATCHES
+"""
+
+OTEL_EXPORTER_OTLP_INSECURE = "OTEL_EXPORTER_OTLP_INSECURE"
+"""
+.. envvar:: OTEL_EXPORTER_OTLP_INSECURE
+"""
+
+OTEL_EXPORTER_OTLP_TRACES_INSECURE = "OTEL_EXPORTER_OTLP_TRACES_INSECURE"
+"""
+.. envvar:: OTEL_EXPORTER_OTLP_TRACES_INSECURE
+"""

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

@@ -51,29 +51,6 @@
 <https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/README.md>`_
 that have prescribed semantic meanings, for example ``service.name`` in the
 above example.
-
-.. envvar:: OTEL_RESOURCE_ATTRIBUTES
-
-The :envvar:`OTEL_RESOURCE_ATTRIBUTES` environment variable allows resource
-attributes to be passed to the SDK at process invocation. The attributes from
-:envvar:`OTEL_RESOURCE_ATTRIBUTES` are merged with those passed to
-`Resource.create`, meaning :envvar:`OTEL_RESOURCE_ATTRIBUTES` takes *lower*
-priority. Attributes should be in the format ``key1=value1,key2=value2``.
-Additional details are available `in the specification
-<https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md#specifying-resource-information-via-an-environment-variable>`_.
-
-.. code-block:: console
-
-    $ OTEL_RESOURCE_ATTRIBUTES="service.name=shoppingcard,will_be_overridden=foo" python - <<EOF
-    import pprint
-    from opentelemetry.sdk.resources import Resource
-    pprint.pprint(Resource.create({"will_be_overridden": "bar"}).attributes)
-    EOF
-    {'service.name': 'shoppingcard',
-    'telemetry.sdk.language': 'python',
-    'telemetry.sdk.name': 'opentelemetry',
-    'telemetry.sdk.version': '0.13.dev0',
-    'will_be_overridden': 'bar'}
  """
 
 import abc

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

@@ -115,8 +115,16 @@ def __init__(self):
 class BatchSpanProcessor(SpanProcessor):
     """Batch span processor implementation.
 
-    BatchSpanProcessor is an implementation of `SpanProcessor` that
+    `BatchSpanProcessor` is an implementation of `SpanProcessor` that
     batches ended spans and pushes them to the configured `SpanExporter`.
+
+    `BatchSpanProcessor` is configurable with the following environment
+    variables which correspond to constructor parameters:
+
+    - :envvar:`OTEL_BSP_SCHEDULE_DELAY`
+    - :envvar:`OTEL_BSP_MAX_QUEUE_SIZE`
+    - :envvar:`OTEL_BSP_MAX_EXPORT_BATCH_SIZE`
+    - :envvar:`OTEL_BSP_EXPORT_TIMEOUT`
     """
 
     def __init__(