From bc61ad5b4c5cd4a4e250eb72b2c6bfdf2c74b157 Mon Sep 17 00:00:00 2001 From: jack-berg <34418638+jack-berg@users.noreply.github.com> Date: Tue, 25 Apr 2023 16:51:27 -0500 Subject: [PATCH] Move configuration documents to configuration folder (#3434) --- CHANGELOG.md | 3 + specification/README.md | 2 +- .../configuration/file-configuration.md | 4 +- .../{ => configuration}/sdk-configuration.md | 10 +++ .../sdk-environment-variables.md | 72 +++++++++---------- specification/metrics/sdk.md | 2 +- .../metrics/sdk_exporters/in-memory.md | 2 +- specification/metrics/sdk_exporters/otlp.md | 2 +- specification/metrics/sdk_exporters/stdout.md | 2 +- .../resource/semantic_conventions/README.md | 2 +- specification/vendors.md | 2 +- specification/versioning-and-stability.md | 2 +- 12 files changed, 59 insertions(+), 46 deletions(-) rename specification/{ => configuration}/sdk-configuration.md (81%) rename specification/{ => configuration}/sdk-environment-variables.md (74%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 478c360f2db..ed69c327753 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -54,6 +54,9 @@ release. ([#3360](https://github.com/open-telemetry/opentelemetry-specification/pull/3360)) - Move file configuration schema to `opentelemetry-configuration`. ([#3412](https://github.com/open-telemetry/opentelemetry-specification/pull/3412)) +- Move `sdk-configuration.md` and `sdk-environment-variables.md` + to `/specification/configuration/`. + ([#3434](https://github.com/open-telemetry/opentelemetry-specification/pull/3434)) ### Telemetry Schemas diff --git a/specification/README.md b/specification/README.md index 60deab9e11d..505ccfc9f17 100644 --- a/specification/README.md +++ b/specification/README.md @@ -33,7 +33,7 @@ cascade: - [Metrics](metrics/sdk.md) - [Logs](logs/sdk.md) - [Resource](resource/sdk.md) - - [Configuration](sdk-configuration.md) + - [Configuration](configuration/sdk-configuration.md) - Data Specification - [Semantic Conventions](overview.md#semantic-conventions) - [Protocol](protocol/README.md) diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md index 802512710d9..41f68988f71 100644 --- a/specification/configuration/file-configuration.md +++ b/specification/configuration/file-configuration.md @@ -19,9 +19,9 @@ File configuration provides a mechanism for configuring OpenTelemetry which is more expressive and full-featured than -the [environment variable](../sdk-environment-variables.md) based scheme, and +the [environment variable](sdk-environment-variables.md) based scheme, and language agnostic in a way not possible -with [programmatic configuration](../sdk-configuration.md#programmatic). +with [programmatic configuration](sdk-configuration.md#programmatic). File configuration defines a [Configuration Model](#configuration-model), which can be expressed in a [configuration file](#configuration-file). diff --git a/specification/sdk-configuration.md b/specification/configuration/sdk-configuration.md similarity index 81% rename from specification/sdk-configuration.md rename to specification/configuration/sdk-configuration.md index 2d067911f16..f1eda1d6e5c 100644 --- a/specification/sdk-configuration.md +++ b/specification/configuration/sdk-configuration.md @@ -8,6 +8,8 @@ - [Abstract](#abstract) - [Configuration Interface](#configuration-interface) * [Programmatic](#programmatic) + * [Environment Variables](#environment-variables) + * [Configuration File](#configuration-file) * [Other Mechanisms](#other-mechanisms) @@ -34,6 +36,14 @@ struct on an SDK builder class. From that, one could build a CLI that accepts a file (YAML, JSON, TOML, ...) and then transforms into that well-defined struct consumable by the programmatic interface. +### Environment Variables + +See [OpenTelemetry Environment Variable Specification](./sdk-environment-variables.md). + +### Configuration File + +See [File Configuration](./file-configuration.md). + ### Other Mechanisms Additional configuration mechanisms SHOULD be provided in whatever diff --git a/specification/sdk-environment-variables.md b/specification/configuration/sdk-environment-variables.md similarity index 74% rename from specification/sdk-environment-variables.md rename to specification/configuration/sdk-environment-variables.md index 52582156e3a..961fad6f705 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/configuration/sdk-environment-variables.md @@ -1,18 +1,18 @@ # OpenTelemetry Environment Variable Specification -**Status**: [Mixed](document-status.md) +**Status**: [Mixed](../document-status.md) The goal of this specification is to unify the environment variable names between different OpenTelemetry SDK implementations. SDKs MAY choose to allow configuration via the environment variables in this specification, but are not required to. If they do, they SHOULD use the names listed in this document. ## Parsing empty value -**Status**: [Stable](document-status.md) +**Status**: [Stable](../document-status.md) The SDK MUST interpret an empty value of an environment variable the same way as when the variable is unset. ## Special configuration types -**Status**: [Stable](document-status.md) +**Status**: [Stable](../document-status.md) ### Boolean value @@ -64,24 +64,24 @@ For example, the value `12000` indicates 12000 milliseconds, i.e., 12 seconds. ## General SDK Configuration -**Status**: [Stable](document-status.md) +**Status**: [Stable](../document-status.md) -| Name | Description | Default | Notes | -| ------------------------ | ------------------------------------------------- | --------------------------------- | ----------------------------------- | -| OTEL_SDK_DISABLED | Disable the SDK for all signals | false | Boolean value. If "true", a no-op SDK implementation will be used for all telemetry signals. Any other value or absence of the variable will have no effect and the SDK will remain enabled. This setting has no effect on propagators configured through the OTEL_PROPAGATORS variable.| -| OTEL_RESOURCE_ATTRIBUTES | Key-value pairs to be used as resource attributes | See [Resource semantic conventions](resource/semantic_conventions/README.md#semantic-attributes-with-sdk-provided-default-value) for details. | See [Resource SDK](./resource/sdk.md#specifying-resource-information-via-an-environment-variable) for more details. | -| OTEL_SERVICE_NAME | Sets the value of the [`service.name`](./resource/semantic_conventions/README.md#service) resource attribute | | If `service.name` is also provided in `OTEL_RESOURCE_ATTRIBUTES`, then `OTEL_SERVICE_NAME` takes precedence. | -| OTEL_LOG_LEVEL | Log level used by the SDK logger | "info" | | -| OTEL_PROPAGATORS | Propagators to be used as a comma-separated list | "tracecontext,baggage" | Values MUST be deduplicated in order to register a `Propagator` only once. | -| OTEL_TRACES_SAMPLER | Sampler to be used for traces | "parentbased_always_on" | See [Sampling](./trace/sdk.md#sampling) | -| OTEL_TRACES_SAMPLER_ARG | String value to be used as the sampler argument | | The specified value will only be used if OTEL_TRACES_SAMPLER is set. Each Sampler type defines its own expected input, if any. Invalid or unrecognized input MUST be logged and MUST be otherwise ignored, i.e. the SDK MUST behave as if OTEL_TRACES_SAMPLER_ARG is not set. | +| Name | Description | Default | Notes | +|--------------------------|---------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| OTEL_SDK_DISABLED | Disable the SDK for all signals | false | Boolean value. If "true", a no-op SDK implementation will be used for all telemetry signals. Any other value or absence of the variable will have no effect and the SDK will remain enabled. This setting has no effect on propagators configured through the OTEL_PROPAGATORS variable. | +| OTEL_RESOURCE_ATTRIBUTES | Key-value pairs to be used as resource attributes | See [Resource semantic conventions](../resource/semantic_conventions/README.md#semantic-attributes-with-sdk-provided-default-value) for details. | See [Resource SDK](../resource/sdk.md#specifying-resource-information-via-an-environment-variable) for more details. | +| OTEL_SERVICE_NAME | Sets the value of the [`service.name`](../resource/semantic_conventions/README.md#service) resource attribute | | If `service.name` is also provided in `OTEL_RESOURCE_ATTRIBUTES`, then `OTEL_SERVICE_NAME` takes precedence. | +| OTEL_LOG_LEVEL | Log level used by the SDK logger | "info" | | +| OTEL_PROPAGATORS | Propagators to be used as a comma-separated list | "tracecontext,baggage" | Values MUST be deduplicated in order to register a `Propagator` only once. | +| OTEL_TRACES_SAMPLER | Sampler to be used for traces | "parentbased_always_on" | See [Sampling](../trace/sdk.md#sampling) | +| OTEL_TRACES_SAMPLER_ARG | String value to be used as the sampler argument | | The specified value will only be used if OTEL_TRACES_SAMPLER is set. Each Sampler type defines its own expected input, if any. Invalid or unrecognized input MUST be logged and MUST be otherwise ignored, i.e. the SDK MUST behave as if OTEL_TRACES_SAMPLER_ARG is not set. | Known values for `OTEL_PROPAGATORS` are: - `"tracecontext"`: [W3C Trace Context](https://www.w3.org/TR/trace-context/) - `"baggage"`: [W3C Baggage](https://www.w3.org/TR/baggage/) -- `"b3"`: [B3 Single](./context/api-propagators.md#configuration) -- `"b3multi"`: [B3 Multi](./context/api-propagators.md#configuration) +- `"b3"`: [B3 Single](../context/api-propagators.md#configuration) +- `"b3multi"`: [B3 Multi](../context/api-propagators.md#configuration) - `"jaeger"`: [Jaeger](https://www.jaegertracing.io/docs/1.21/client-libraries/#propagation-format) - `"xray"`: [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader) (_third party_) - `"ottrace"`: [OT Trace](https://github.com/opentracing?q=basic&type=&language=) (_third party_) @@ -110,7 +110,7 @@ Depending on the value of `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` may b ## Batch Span Processor -**Status**: [Stable](document-status.md) +**Status**: [Stable](../document-status.md) | Name | Description | Default | Notes | | ------------------------------ | ---------------------------------------------------------------- | ------- | ----------------------------------------------------- | @@ -121,7 +121,7 @@ Depending on the value of `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` may b ## Batch LogRecord Processor -**Status**: [Experimental](document-status.md) +**Status**: [Experimental](../document-status.md) | Name | Description | Default | Notes | | ------------------------------- | ---------------------------------------------------------------- | ------- | ------------------------------------------------------ | @@ -135,7 +135,7 @@ Depending on the value of `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` may b SDKs SHOULD only offer environment variables for the types of attributes, for which that SDK implements truncation mechanism. -See the SDK [Attribute Limits](common/README.md#attribute-limits) section for the definition of the limits. +See the SDK [Attribute Limits](../common/README.md#attribute-limits) section for the definition of the limits. | Name | Description | Default | Notes | | --------------------------------- | ------------------------------------ | ------- | ----- | @@ -144,9 +144,9 @@ See the SDK [Attribute Limits](common/README.md#attribute-limits) section for th ## Span Limits -**Status**: [Stable](document-status.md) +**Status**: [Stable](../document-status.md) -See the SDK [Span Limits](trace/sdk.md#span-limits) section for the definition of the limits. +See the SDK [Span Limits](../trace/sdk.md#span-limits) section for the definition of the limits. | Name | Description | Default | Notes | | -------------------------------------- | ---------------------------------------------- | ------- | ----- | @@ -159,9 +159,9 @@ See the SDK [Span Limits](trace/sdk.md#span-limits) section for the definition o ## LogRecord Limits -**Status**: [Experimental](document-status.md) +**Status**: [Experimental](../document-status.md) -See the SDK [LogRecord Limits](logs/sdk.md#logrecord-limits) section for the definition of the limits. +See the SDK [LogRecord Limits](../logs/sdk.md#logrecord-limits) section for the definition of the limits. | Name | Description | Default | Notes | | ------------------------------------------- | -------------------------------------------| -------- | ----- | @@ -170,11 +170,11 @@ See the SDK [LogRecord Limits](logs/sdk.md#logrecord-limits) section for the def ## OTLP Exporter -See [OpenTelemetry Protocol Exporter Configuration Options](./protocol/exporter.md). +See [OpenTelemetry Protocol Exporter Configuration Options](../protocol/exporter.md). ## Jaeger Exporter -**Status**: [Deprecated](document-status.md) +**Status**: [Deprecated](../document-status.md) Jaeger exporter support will be removed from OpenTelemetry in July 2023. @@ -238,7 +238,7 @@ Environment variables specific for the `udp/thrift.binary` transport protocol: ## Zipkin Exporter -**Status**: [Stable](document-status.md) +**Status**: [Stable](../document-status.md) | Name | Description | Default | | ----------------------------- | ---------------------------------------------------------------------------------- |------------------------------------- | @@ -256,7 +256,7 @@ _is no specified default, or configuration via environment variables_. ## Prometheus Exporter -**Status**: [Experimental](document-status.md) +**Status**: [Experimental](../document-status.md) | Name | Description | Default | | ----------------------------- | --------------------------------| ---------------------------- | @@ -265,7 +265,7 @@ _is no specified default, or configuration via environment variables_. ## Exporter Selection -**Status**: [Stable](document-status.md) +**Status**: [Stable](../document-status.md) We define environment variables for setting one or more exporters per signal. @@ -279,25 +279,25 @@ The SDK MAY accept a comma-separated list to enable setting multiple exporters. Known values for `OTEL_TRACES_EXPORTER` are: -- `"otlp"`: [OTLP](./protocol/otlp.md) +- `"otlp"`: [OTLP](../protocol/otlp.md) - `"jaeger"`: export in Jaeger data model - `"zipkin"`: [Zipkin](https://zipkin.io/zipkin-api/) (Defaults to [protobuf](https://github.com/openzipkin/zipkin-api/blob/master/zipkin.proto) format) - `"none"`: No automatically configured exporter for traces. Known values for `OTEL_METRICS_EXPORTER` are: -- `"otlp"`: [OTLP](./protocol/otlp.md) +- `"otlp"`: [OTLP](../protocol/otlp.md) - `"prometheus"`: [Prometheus](https://github.com/prometheus/docs/blob/master/content/docs/instrumenting/exposition_formats.md) - `"none"`: No automatically configured exporter for metrics. Known values for `OTEL_LOGS_EXPORTER` are: -- `"otlp"`: [OTLP](./protocol/otlp.md) +- `"otlp"`: [OTLP](../protocol/otlp.md) - `"none"`: No automatically configured exporter for logs. ## Metrics SDK Configuration -**Status**: [Mixed](document-status.md) +**Status**: [Mixed](../document-status.md) | Name | Description | Default | Notes | |-----------------|---------|-------------|---------| @@ -305,16 +305,16 @@ Known values for `OTEL_LOGS_EXPORTER` are: Known values for `OTEL_METRICS_EXEMPLAR_FILTER` are: -- `"always_on"`: [AlwaysOn](./metrics/sdk.md#alwayson) -- `"always_off"`: [AlwaysOff](./metrics/sdk.md#alwaysoff) -- `"trace_based"`: [TraceBased](./metrics/sdk.md#tracebased) +- `"always_on"`: [AlwaysOn](../metrics/sdk.md#alwayson) +- `"always_off"`: [AlwaysOff](../metrics/sdk.md#alwaysoff) +- `"trace_based"`: [TraceBased](../metrics/sdk.md#tracebased) ### Periodic exporting MetricReader -**Status**: [Stable](document-status.md) +**Status**: [Stable](../document-status.md) Environment variables specific for the push metrics exporters (OTLP, stdout, in-memory) -that use [periodic exporting MetricReader](metrics/sdk.md#periodic-exporting-metricreader). +that use [periodic exporting MetricReader](../metrics/sdk.md#periodic-exporting-metricreader). | Name | Description | Default | Notes | | ----------------------------- | ----------------------------------------------------------------------------- | ------- | ----- | diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index eab03a4dfd4..3600e1afada 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -1262,7 +1262,7 @@ If a batch of [Metric points](./data-model.md#metric-points) can include ## Defaults and configuration The SDK MUST provide configuration according to the [SDK environment -variables](../sdk-environment-variables.md) specification. +variables](../configuration/sdk-environment-variables.md) specification. ## Numerical limits handling diff --git a/specification/metrics/sdk_exporters/in-memory.md b/specification/metrics/sdk_exporters/in-memory.md index 5fcc15d06db..8171ba4be39 100644 --- a/specification/metrics/sdk_exporters/in-memory.md +++ b/specification/metrics/sdk_exporters/in-memory.md @@ -16,6 +16,6 @@ In-memory Metrics Exporter MUST support both Cumulative and Delta If a language provides a mechanism to automatically configure a [MetricReader](../sdk.md#metricreader) to pair with the associated exporter (e.g., using the [`OTEL_METRICS_EXPORTER` environment -variable](../../sdk-environment-variables.md#exporter-selection)), by +variable](../../configuration/sdk-environment-variables.md#exporter-selection)), by default the exporter MUST be paired with a [periodic exporting MetricReader](../sdk.md#periodic-exporting-metricreader). diff --git a/specification/metrics/sdk_exporters/otlp.md b/specification/metrics/sdk_exporters/otlp.md index 0943b130055..a81aab3961a 100644 --- a/specification/metrics/sdk_exporters/otlp.md +++ b/specification/metrics/sdk_exporters/otlp.md @@ -21,7 +21,7 @@ Exporter](../../protocol/exporter.md) specification. If a language provides a mechanism to automatically configure a [MetricReader](../sdk.md#metricreader) to pair with the associated Exporter (e.g., using the [`OTEL_METRICS_EXPORTER` environment -variable](../../sdk-environment-variables.md#exporter-selection)), +variable](../../configuration/sdk-environment-variables.md#exporter-selection)), then by default: * The exporter MUST be paired with a [periodic exporting diff --git a/specification/metrics/sdk_exporters/stdout.md b/specification/metrics/sdk_exporters/stdout.md index 920a6e2cc64..4b39ca2861c 100644 --- a/specification/metrics/sdk_exporters/stdout.md +++ b/specification/metrics/sdk_exporters/stdout.md @@ -20,7 +20,7 @@ StreamExporter, etc. If a language provides a mechanism to automatically configure a [MetricReader](../sdk.md#metricreader) to pair with the associated exporter (e.g., using the [`OTEL_METRICS_EXPORTER` environment -variable](../../sdk-environment-variables.md#exporter-selection)), by +variable](../../configuration/sdk-environment-variables.md#exporter-selection)), by default the exporter MUST be paired with a [periodic exporting MetricReader](../sdk.md#periodic-exporting-metricreader) with a default `exportIntervalMilliseconds` of 10000. diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md index 7d4fe1e99fd..a92bd360896 100644 --- a/specification/resource/semantic_conventions/README.md +++ b/specification/resource/semantic_conventions/README.md @@ -52,7 +52,7 @@ Given their significance some resource attributes are treated specifically as de ### Semantic Attributes with Dedicated Environment Variable These are the attributes which MAY be configurable via a dedicated environment variable -as specified in [OpenTelemetry Environment Variable Specification](../../sdk-environment-variables.md): +as specified in [OpenTelemetry Environment Variable Specification](../../configuration/sdk-environment-variables.md): - [`service.name`](#service) diff --git a/specification/vendors.md b/specification/vendors.md index 79c0a99406e..6ce2333f47e 100644 --- a/specification/vendors.md +++ b/specification/vendors.md @@ -20,7 +20,7 @@ The OpenTelemetry project consists of both a [specification](https://github.com/open-telemetry/opentelemetry-specification) for the API, SDK, protocol and semantic conventions, as well as an implementation of each for a number of languages. The default SDK implementation -is [highly configurable](sdk-configuration.md) and extendable, for example +is [highly configurable](configuration/sdk-configuration.md) and extendable, for example through [Span Processors](trace/sdk.md#span-processor), to allow for additional logic needed by particular vendors to be added without having to implement a custom SDK. By not requiring a custom SDK means for most languages a user will diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index a771d52587f..33d7a2aafa9 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -247,7 +247,7 @@ instrumentations can use schemas to change the instrumentation they produce. **Exception:** Some resource attributes are embedded in various locations of the Specification, e.g. the `service.*` attributes which are required by SDKs to be -produced and have corresponding [environment variables defined in general SDK configuration](sdk-environment-variables.md#general-sdk-configuration). These resource +produced and have corresponding [environment variables defined in general SDK configuration](configuration/sdk-environment-variables.md#general-sdk-configuration). These resource attributes MUST NOT be ever changed. They are considered a hard-coded part of this specification.