diff --git a/CHANGELOG.md b/CHANGELOG.md index 478c360f2db..ff1a568a24d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,10 @@ release. ([#3345](https://github.com/open-telemetry/opentelemetry-specification/pull/3354)) - Drop logger include_trace_context parameter. ([#3397](https://github.com/open-telemetry/opentelemetry-specification/pull/3397)) +- Mark logs bridge API / SDK as stable. + ([#3376](https://github.com/open-telemetry/opentelemetry-specification/pull/3376)) +- Mark LogRecord Environment Variables as stable. + ([#3449](https://github.com/open-telemetry/opentelemetry-specification/pull/3449)) ### Resource @@ -54,6 +58,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/semantic_conventions/resource/telemetry.yaml b/semantic_conventions/resource/telemetry.yaml index efd8d41ef6b..6966b4a853a 100644 --- a/semantic_conventions/resource/telemetry.yaml +++ b/semantic_conventions/resource/telemetry.yaml @@ -40,10 +40,12 @@ groups: value: "python" - id: ruby value: "ruby" - - id: webjs - value: "webjs" + - id: rust + value: "rust" - id: swift value: "swift" + - id: webjs + value: "webjs" requirement_level: required brief: > The language of the telemetry SDK. 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/compatibility/opencensus.md b/specification/compatibility/opencensus.md index e0ea952376f..25dce047ff4 100644 --- a/specification/compatibility/opencensus.md +++ b/specification/compatibility/opencensus.md @@ -1,6 +1,6 @@ # OpenCensus Compatibility -**Status**: [Experimental](../document-status.md), Unless otherwise specified. +**Status**: [Stable](../document-status.md), Unless otherwise specified. The OpenTelemetry project aims to provide backwards compatibility with the [OpenCensus](https://opencensus.io) project in order to ease migration of @@ -80,8 +80,6 @@ Starting with a library using OpenCensus Instrumentation: ## Trace Bridge -**Status**: [Experimental, Feature Freeze](../document-status.md) - The trace bridge is provided as a shim layer implementing the [OpenCensus Trace API](https://github.com/census-instrumentation/opencensus-specs) using the OpenTelemetry Trace API. This layer MUST NOT rely on implementation 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..06c35251a9f 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,11 +121,11 @@ Depending on the value of `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` may b ## Batch LogRecord Processor -**Status**: [Experimental](document-status.md) +**Status**: [Stable](../document-status.md) | Name | Description | Default | Notes | | ------------------------------- | ---------------------------------------------------------------- | ------- | ------------------------------------------------------ | -| OTEL_BLRP_SCHEDULE_DELAY | Delay interval (in milliseconds) between two consecutive exports | 5000 | | +| OTEL_BLRP_SCHEDULE_DELAY | Delay interval (in milliseconds) between two consecutive exports | 1000 | | | OTEL_BLRP_EXPORT_TIMEOUT | Maximum allowed time (in milliseconds) to export data | 30000 | | | OTEL_BLRP_MAX_QUEUE_SIZE | Maximum queue size | 2048 | | | OTEL_BLRP_MAX_EXPORT_BATCH_SIZE | Maximum batch size | 512 | Must be less than or equal to OTEL_BLRP_MAX_QUEUE_SIZE | @@ -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**: [Stable](../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 d1eff3ef66f..e6aeba57e92 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) @@ -149,8 +149,9 @@ All custom identifiers SHOULD be stable across different versions of an implemen | `php` | php | | `python` | python | | `ruby` | ruby | -| `webjs` | webjs | +| `rust` | rust | | `swift` | swift | +| `webjs` | webjs | ## Telemetry SDK (Experimental) 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.