Issue-1147 Adding description to the environment variables (#1898)

open-telemetry · Jun 21, 2021 · a83b6f1 · a83b6f1
1 parent f765b48
commit a83b6f1
Show file tree

Hide file tree

Showing 2 changed files with 103 additions and 16 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - Updated `opentelemetry-opencensus-exporter` to use `service_name` of spans instead of resource
   ([#1897](https://github.com/open-telemetry/opentelemetry-python/pull/1897))
+- Added descriptions to the env variables mentioned in the opentelemetry-specification
+  ([#1898](https://github.com/open-telemetry/opentelemetry-python/pull/1898))
 - Ignore calls to `Span.set_status` with `StatusCode.UNSET` and also if previous status already
   had `StatusCode.OK`.
   ([#1902](https://github.com/open-telemetry/opentelemetry-python/pull/1902))
@@ -18,7 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [1.3.0-0.22b0](https://github.com/open-telemetry/opentelemetry-python/releases/tag/v1.3.0-0.22b0) - 2021-06-01
 
-### Added 
+### Added
 - Allow span limits to be set programatically via TracerProvider.
   ([#1877](https://github.com/open-telemetry/opentelemetry-python/pull/1877))
 - Added support for CreateKey functionality.
@@ -107,7 +109,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#1728](https://github.com/open-telemetry/opentelemetry-python/pull/1728))
 - Silence unnecessary warning when creating a new Status object without description.
   ([#1721](https://github.com/open-telemetry/opentelemetry-python/pull/1721))
-- Update bootstrap cmd to use exact version when installing instrumentation packages. 
+- Update bootstrap cmd to use exact version when installing instrumentation packages.
   ([#1722](https://github.com/open-telemetry/opentelemetry-python/pull/1722))
 - Fix B3 propagator to never return None.
   ([#1750](https://github.com/open-telemetry/opentelemetry-python/pull/1750))
@@ -139,7 +141,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#1500](https://github.com/open-telemetry/opentelemetry-python/pull/1500))
 
 ### Changed
-- remove `service_name` from constructor of jaeger and opencensus exporters and 
+- remove `service_name` from constructor of jaeger and opencensus exporters and
   use of env variable `OTEL_PYTHON_SERVICE_NAME`
   ([#1669])(https://github.com/open-telemetry/opentelemetry-python/pull/1669)
 - Rename `IdsGenerator` to `IdGenerator`
@@ -207,7 +209,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.19b0](https://github.com/open-telemetry/opentelemetry-python/releases/tag/v0.19b0) - 2021-03-26
 
 ### Changed
-- remove `service_name` from constructor of jaeger and opencensus exporters and 
+- remove `service_name` from constructor of jaeger and opencensus exporters and
   use of env variable `OTEL_PYTHON_SERVICE_NAME`
   ([#1669])(https://github.com/open-telemetry/opentelemetry-python/pull/1669)
 - Rename `IdsGenerator` to `IdGenerator`
@@ -364,8 +366,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#1373](https://github.com/open-telemetry/opentelemetry-python/pull/1373))
 - Rename `Meter` to `Accumulator`
   ([#1372](https://github.com/open-telemetry/opentelemetry-python/pull/1372))
-- Fix `ParentBased` sampler for implicit parent spans. Fix also `trace_state` 
-  erasure for dropped spans or spans sampled by the `TraceIdRatioBased` sampler. 
+- Fix `ParentBased` sampler for implicit parent spans. Fix also `trace_state`
+  erasure for dropped spans or spans sampled by the `TraceIdRatioBased` sampler.
   ([#1394](https://github.com/open-telemetry/opentelemetry-python/pull/1394))
 
 ## [0.15b0](https://github.com/open-telemetry/opentelemetry-python/releases/tag/v0.15b0) -2020-11-02
@@ -430,10 +432,10 @@ s
   ([#1143](https://github.com/open-telemetry/opentelemetry-python/pull/1143))
 - Zipkin exporter now accepts a ``max_tag_value_length`` attribute to customize the
   maximum allowed size a tag value can have.
-  ([#1151](https://github.com/open-telemetry/opentelemetry-python/pull/1151)) 
+  ([#1151](https://github.com/open-telemetry/opentelemetry-python/pull/1151))
 - Fixed OTLP events to Zipkin annotations translation.
   ([#1161](https://github.com/open-telemetry/opentelemetry-python/pull/1161))
-- Fixed bootstrap command to correctly install opentelemetry-instrumentation-falcon instead of opentelemetry-instrumentation-flask. 
+- Fixed bootstrap command to correctly install opentelemetry-instrumentation-falcon instead of opentelemetry-instrumentation-flask.
   ([#1138](https://github.com/open-telemetry/opentelemetry-python/pull/1138))
 - Update sampling result names
   ([#1128](https://github.com/open-telemetry/opentelemetry-python/pull/1128))
@@ -455,12 +457,12 @@ s
   ([#835](https://github.com/open-telemetry/opentelemetry-python/pull/835))
 - Add type hints to OTLP exporter
   ([#1121](https://github.com/open-telemetry/opentelemetry-python/pull/1121))
-- Add support for OTEL_EXPORTER_ZIPKIN_ENDPOINT env var. As part of this change, the 
+- Add support for OTEL_EXPORTER_ZIPKIN_ENDPOINT env var. As part of this change, the
   configuration of the ZipkinSpanExporter exposes a `url` argument to replace `host_name`,
   `port`, `protocol`, `endpoint`. This brings this implementation inline with other
-  implementations. 
+  implementations.
   ([#1064](https://github.com/open-telemetry/opentelemetry-python/pull/1064))
-- Zipkin exporter report instrumentation info. 
+- Zipkin exporter report instrumentation info.
   ([#1097](https://github.com/open-telemetry/opentelemetry-python/pull/1097))
 - Add status mapping to tags
   ([#1111](https://github.com/open-telemetry/opentelemetry-python/issues/1111))
@@ -513,7 +515,7 @@ s
   ([#904](https://github.com/open-telemetry/opentelemetry-python/pull/904))
 - Stop TracerProvider and MeterProvider from being overridden
   ([#959](https://github.com/open-telemetry/opentelemetry-python/pull/959))
-- Update default port to 55680 
+- Update default port to 55680
   ([#977](https://github.com/open-telemetry/opentelemetry-python/pull/977))
 - Add proper length zero padding to hex strings of traceId, spanId, parentId sent on the wire, for compatibility with jaeger-collector
   ([#908](https://github.com/open-telemetry/opentelemetry-python/pull/908))

diff --git a/opentelemetry-sdk/src/opentelemetry/sdk/environment_variables/__init__.py b/opentelemetry-sdk/src/opentelemetry/sdk/environment_variables/__init__.py
@@ -41,84 +41,131 @@
 OTEL_LOG_LEVEL = "OTEL_LOG_LEVEL"
 """
 .. envvar:: OTEL_LOG_LEVEL
+
+The :envvar:`OTEL_LOG_LEVEL` environment variable sets the log level used by the SDK logger
+Default: "info"
 """
 
 OTEL_TRACES_SAMPLER = "OTEL_TRACES_SAMPLER"
 """
 .. envvar:: OTEL_TRACES_SAMPLER
+
+The :envvar:`OTEL_TRACES_SAMPLER` environment variable sets the sampler to be used for traces.
+Sampling is a mechanism to control the noise introduced by OpenTelemetry by reducing the number
+of traces collected and sent to the backend
+Default: "parentbased_always_on"
 """
 
 OTEL_TRACES_SAMPLER_ARG = "OTEL_TRACES_SAMPLER_ARG"
 """
 .. envvar:: OTEL_TRACES_SAMPLER_ARG
+
+The :envvar:`OTEL_TRACES_SAMPLER_ARG` environment variable will only be used if OTEL_TRACES_SAMPLER is set.
+Each Sampler type defines its own expected input, if any.
+Invalid or unrecognized input is ignored,
+i.e. the SDK behaves as if OTEL_TRACES_SAMPLER_ARG is not set.
 """
 
 OTEL_BSP_SCHEDULE_DELAY = "OTEL_BSP_SCHEDULE_DELAY"
 """
 .. envvar:: OTEL_BSP_SCHEDULE_DELAY
+
+The :envvar:`OTEL_BSP_SCHEDULE_DELAY` represents the delay interval between two consecutive exports.
+Default: 5000
 """
 
 OTEL_BSP_EXPORT_TIMEOUT = "OTEL_BSP_EXPORT_TIMEOUT"
 """
 .. envvar:: OTEL_BSP_EXPORT_TIMEOUT
+
+The :envvar:`OTEL_BSP_EXPORT_TIMEOUT` represents the maximum allowed time to export data.
+Default: 30000
 """
 
 OTEL_BSP_MAX_QUEUE_SIZE = "OTEL_BSP_MAX_QUEUE_SIZE"
 """
 .. envvar:: OTEL_BSP_MAX_QUEUE_SIZE
+
+The :envvar:`OTEL_BSP_MAX_QUEUE_SIZE` represents the maximum queue size for the data export.
+Default: 2048
 """
 
 OTEL_BSP_MAX_EXPORT_BATCH_SIZE = "OTEL_BSP_MAX_EXPORT_BATCH_SIZE"
 """
 .. envvar:: OTEL_BSP_MAX_EXPORT_BATCH_SIZE
+
+The :envvar:`OTEL_BSP_MAX_EXPORT_BATCH_SIZE` represents the maximum batch size for the data export.
+Default: 512
 """
 
 OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT = "OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT"
 """
 .. envvar:: OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT
+
+The :envvar:`OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT` represents the maximum allowed span attribute count.
+Default: 128
 """
 
 OTEL_SPAN_EVENT_COUNT_LIMIT = "OTEL_SPAN_EVENT_COUNT_LIMIT"
 """
 .. envvar:: OTEL_SPAN_EVENT_COUNT_LIMIT
+
+The :envvar:`OTEL_SPAN_EVENT_COUNT_LIMIT` represents the maximum allowed span event count.
+Default: 128
 """
 
 OTEL_SPAN_LINK_COUNT_LIMIT = "OTEL_SPAN_LINK_COUNT_LIMIT"
 """
 .. envvar:: OTEL_SPAN_LINK_COUNT_LIMIT
+
+The :envvar:`OTEL_SPAN_LINK_COUNT_LIMIT` represents the maximum allowed span link count.
+Default: 128
 """
 
 OTEL_EXPORTER_JAEGER_AGENT_HOST = "OTEL_EXPORTER_JAEGER_AGENT_HOST"
 """
 .. envvar:: OTEL_EXPORTER_JAEGER_AGENT_HOST
+
+The :envvar:`OTEL_EXPORTER_JAEGER_AGENT_HOST` represents the hostname for the Jaeger agent.
+Default: "localhost"
 """
 
 OTEL_EXPORTER_JAEGER_AGENT_PORT = "OTEL_EXPORTER_JAEGER_AGENT_PORT"
 """
 .. envvar:: OTEL_EXPORTER_JAEGER_AGENT_PORT
+
+The :envvar:`OTEL_EXPORTER_JAEGER_AGENT_PORT` represents the port for the Jaeger agent.
+Default: 6831
 """
 
 OTEL_EXPORTER_JAEGER_ENDPOINT = "OTEL_EXPORTER_JAEGER_ENDPOINT"
 """
 .. envvar:: OTEL_EXPORTER_JAEGER_ENDPOINT
+
+The :envvar:`OTEL_EXPORTER_JAEGER_ENDPOINT` represents the HTTP endpoint for Jaeger traces.
+Default: "http://localhost:14250"
 """
 
 OTEL_EXPORTER_JAEGER_USER = "OTEL_EXPORTER_JAEGER_USER"
 """
 .. envvar:: OTEL_EXPORTER_JAEGER_USER
+
+The :envvar:`OTEL_EXPORTER_JAEGER_USER` represents the username to be used for HTTP basic authentication.
 """
 
 OTEL_EXPORTER_JAEGER_PASSWORD = "OTEL_EXPORTER_JAEGER_PASSWORD"
 """
 .. envvar:: OTEL_EXPORTER_JAEGER_PASSWORD
+
+The :envvar:`OTEL_EXPORTER_JAEGER_PASSWORD` represents the password to be used for HTTP basic authentication.
 """
 
 OTEL_EXPORTER_JAEGER_TIMEOUT = "OTEL_EXPORTER_JAEGER_TIMEOUT"
 """
 .. envvar:: OTEL_EXPORTER_JAEGER_TIMEOUT
 
-Maximum time the Jaeger exporter will wait for each batch export, the default
-timeout is 10s.
+Maximum time the Jaeger exporter will wait for each batch export.
+Default: 10
 """
 
 OTEL_EXPORTER_ZIPKIN_ENDPOINT = "OTEL_EXPORTER_ZIPKIN_ENDPOINT"
@@ -133,23 +180,32 @@
 """
 .. envvar:: OTEL_EXPORTER_ZIPKIN_TIMEOUT
 
-Maximum time the Zipkin exporter will wait for each batch export, the default
-timeout is 10s.
+Maximum time (in seconds) the Zipkin exporter will wait for each batch export.
+Default: 10
 """
 
 OTEL_EXPORTER_OTLP_PROTOCOL = "OTEL_EXPORTER_OTLP_PROTOCOL"
 """
 .. envvar:: OTEL_EXPORTER_OTLP_PROTOCOL
+
+The :envvar:`OTEL_EXPORTER_OTLP_PROTOCOL` represents the the transport protocol for the
+OTLP exporter.
 """
 
 OTEL_EXPORTER_OTLP_CERTIFICATE = "OTEL_EXPORTER_OTLP_CERTIFICATE"
 """
 .. envvar:: OTEL_EXPORTER_OTLP_CERTIFICATE
+
+The :envvar:`OTEL_EXPORTER_OTLP_CERTIFICATE` stores the path to the certificate file for
+TLS credentials of gRPC client. Should only be used for a secure connection.
 """
 
 OTEL_EXPORTER_OTLP_HEADERS = "OTEL_EXPORTER_OTLP_HEADERS"
 """
 .. envvar:: OTEL_EXPORTER_OTLP_HEADERS
+
+The :envvar:`OTEL_EXPORTER_OTLP_HEADERS` contains the key-value pairs to be used as headers
+associated with gRPC or HTTP requests.
 """
 
 
@@ -173,31 +229,51 @@
 OTEL_EXPORTER_OTLP_TIMEOUT = "OTEL_EXPORTER_OTLP_TIMEOUT"
 """
 .. envvar:: OTEL_EXPORTER_OTLP_TIMEOUT
+
+The :envvar:`OTEL_EXPORTER_OTLP_TIMEOUT` is the maximum time the OTLP exporter will wait for each batch export.
+Default: 10
 """
 
 OTEL_EXPORTER_OTLP_ENDPOINT = "OTEL_EXPORTER_OTLP_ENDPOINT"
 """
 .. envvar:: OTEL_EXPORTER_OTLP_ENDPOINT
+
+The :envvar:`OTEL_EXPORTER_OTLP_ENDPOINT` target to which the exporter is going to send spans or metrics.
+The endpoint MUST be a valid URL with scheme (http or https) and host, and MAY contain a port and path.
+A scheme of https indicates a secure connection.
+Default: "https://localhost:4317"
 """
 
 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"
 """
 .. envvar:: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
+
+The :envvar:`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` target to which the span exporter is going to send spans.
+The endpoint MUST be a valid URL with scheme (http or https) and host, and MAY contain a port and path.
+A scheme of https indicates a secure connection.
 """
 
 OTEL_EXPORTER_OTLP_TRACES_PROTOCOL = "OTEL_EXPORTER_OTLP_TRACES_PROTOCOL"
 """
 .. envvar:: OTEL_EXPORTER_OTLP_TRACES_PROTOCOL
+
+The :envvar:`OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` represents the the transport protocol for spans.
 """
 
 OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE = "OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE"
 """
 .. envvar:: OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE
+
+The :envvar:`OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE` stores the path to the certificate file for
+TLS credentials of gRPC client for traces. Should only be used for a secure connection for tracing.
 """
 
 OTEL_EXPORTER_OTLP_TRACES_HEADERS = "OTEL_EXPORTER_OTLP_TRACES_HEADERS"
 """
 .. envvar:: OTEL_EXPORTER_OTLP_TRACES_HEADERS
+
+The :envvar:`OTEL_EXPORTER_OTLP_TRACES_HEADERS` contains the key-value pairs to be used as headers for spans
+associated with gRPC or HTTP requests.
 """
 
 
@@ -212,18 +288,27 @@
 OTEL_EXPORTER_OTLP_TRACES_TIMEOUT = "OTEL_EXPORTER_OTLP_TRACES_TIMEOUT"
 """
 .. envvar:: OTEL_EXPORTER_OTLP_TRACES_TIMEOUT
+
+The :envvar:`OTEL_EXPORTER_OTLP_TRACES_TIMEOUT` is the maximum time the OTLP exporter will
+wait for each batch export for spans.
 """
 
 OTEL_EXPORTER_JAEGER_CERTIFICATE = "OTEL_EXPORTER_JAEGER_CERTIFICATE"
 """
 .. envvar:: OTEL_EXPORTER_JAEGER_CERTIFICATE
+
+The :envvar:`OTEL_EXPORTER_JAEGER_CERTIFICATE` stores the path to the certificate file for
+TLS credentials of gRPC client for Jaeger. Should only be used for a secure connection with Jaeger.
 """
 
 OTEL_EXPORTER_JAEGER_AGENT_SPLIT_OVERSIZED_BATCHES = (
     "OTEL_EXPORTER_JAEGER_AGENT_SPLIT_OVERSIZED_BATCHES"
 )
 """
 .. envvar:: OTEL_EXPORTER_JAEGER_AGENT_SPLIT_OVERSIZED_BATCHES
+
+The :envvar:`OTEL_EXPORTER_JAEGER_AGENT_SPLIT_OVERSIZED_BATCHES` is a boolean flag to determine whether
+to split a large span batch to admire the udp packet size limit.
 """
 
 OTEL_SERVICE_NAME = "OTEL_SERVICE_NAME"