From a83b6f1d40eb6db45b76d98cfd02742729d17c96 Mon Sep 17 00:00:00 2001 From: Raj Nishtala Date: Mon, 21 Jun 2021 11:26:20 -0400 Subject: [PATCH] Issue-1147 Adding description to the environment variables (#1898) --- CHANGELOG.md | 26 +++--- .../sdk/environment_variables/__init__.py | 93 ++++++++++++++++++- 2 files changed, 103 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8a3872dcf1d..acc817a9d59 100644 --- 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 index a59ca0e5c1d..1a98d1f831e 100644 --- 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,11 +288,17 @@ 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 = ( @@ -224,6 +306,9 @@ ) """ .. 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"