Merge branch 'main' into codeboten/env-var-exporters-console

CHANGELOG.md

@@ -11,33 +11,64 @@ release.
 
 ### Traces
 
+### Metrics
+
+### Logs
+
+- Add definition for standard output log record exporter.
+  ([#3741](https://github.com/open-telemetry/opentelemetry-specification/pull/3741))
+
+### Resource
+
+### OpenTelemetry Protocol
+
+### Compatibility
+
+### SDK Configuration
+
+### Common
+
+### Supplementary Guidelines
+
+## v1.27.0 (2023-11-08)
+
+### Context
+
+- No changes.
+
+### Traces
+
 - Add a new AddLink() operation to Span (experimental).
   ([#3678](https://github.com/open-telemetry/opentelemetry-specification/pull/3678))
 
 ### Metrics
 
+- No changes.
+
 ### Logs
 
-- Add definition for standard output log record exporter.
-  ([#3741](https://github.com/open-telemetry/opentelemetry-specification/pull/3741))
+- No changes.
 
 ### Resource
 
+- No changes.
+
 ### OpenTelemetry Protocol
 
 - New exporter implementations do not need to support
   `OTEL_EXPORTER_OTLP_SPAN_INSECURE` and `OTEL_EXPORTER_OTLP_METRIC_INSECURE`.
   ([#3719](https://github.com/open-telemetry/opentelemetry-specification/pull/3719))
-- Clarify that the configuration options MAY be implemented by the exporter,
-  the SDK, or a separate component (e.g. environment-based autoconfiguration component).
-  ([#3730](https://github.com/open-telemetry/opentelemetry-specification/pull/3730))
 
 ### Compatibility
 
+- No changes.
+
 ### SDK Configuration
 
 - Define file configuration parse and create operations.
   ([#3437](https://github.com/open-telemetry/opentelemetry-specification/pull/3437))
+- Add environment variable implementation guidelines.
+  ([#3738](https://github.com/open-telemetry/opentelemetry-specification/pull/3738))
 
 ### Common
 
@@ -48,6 +79,8 @@ release.
 
 ### Supplementary Guidelines
 
+- No changes.
+
 ## v1.26.0 (2023-10-10)
 
 ### Context

specification/baggage/api.md

@@ -146,7 +146,7 @@ reasons.
 
 The API layer or an extension package MUST include the following `Propagator`s:
 
-* A `TextMapPropagator` implementing the [W3C Baggage Specification](https://w3c.github.io/baggage).
+* A `TextMapPropagator` implementing the [W3C Baggage Specification](https://www.w3.org/TR/baggage).
 
 See [Propagators Distribution](../context/api-propagators.md#propagators-distribution)
 for how propagators are to be distributed.

specification/configuration/sdk-environment-variables.md

@@ -10,7 +10,18 @@ aliases:
 
 **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.
+The goal of this specification is to unify the environment variable names between different OpenTelemetry implementations.
+
+Implementations 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.
+
+## Implementation guidelines
+
+**Status**: [Stable](../document-status.md)
+
+Environment variables MAY be handled (implemented) directly by a component, in the SDK, or in a separate component (e.g. environment-based autoconfiguration component).
+
+The environment-based configuration MUST have a direct code configuration equivalent.
 
 ## Parsing empty value
 
@@ -25,25 +36,25 @@ The SDK MUST interpret an empty value of an environment variable the same way as
 ### Boolean value
 
 Any value that represents a Boolean MUST be set to true only by the case-insensitive string `"true"`, meaning `"True"` or `"TRUE"` are also accepted, as true.
-An SDK MUST NOT extend this definition and define additional values that are interpreted as true.
+An implementation MUST NOT extend this definition and define additional values that are interpreted as true.
 Any value not explicitly defined here as a true value, including unset and empty values, MUST be interpreted as false.
 If any value other than a true value, case-insensitive string `"false"`, empty, or unset is used, a warning SHOULD be logged to inform users about the fallback to false being applied.
 All Boolean environment variables SHOULD be named and defined such that false is the expected safe default behavior.
 Renaming or changing the default value MUST NOT happen without a major version upgrade.
 
 ### Numeric value
 
-If an SDK chooses to support an integer-valued environment variable, it SHOULD support nonnegative values between 0 and 2³¹ − 1 (inclusive). Individual SDKs MAY choose to support a larger range of values.
+If an implementation chooses to support an integer-valued environment variable, it SHOULD support nonnegative values between 0 and 2³¹ − 1 (inclusive). Individual SDKs MAY choose to support a larger range of values.
 
 > The following paragraph was added after stabilization and the requirements are
-thus qualified as "SHOULD" to allow SDKs to avoid breaking changes.
+thus qualified as "SHOULD" to allow implementations to avoid breaking changes.
 For new
 implementations, these should be treated as MUST requirements.
 
-For variables accepting a numeric value, if the user provides a value the SDK cannot parse,
-or which is outside the valid range for the configuration item, the SDK SHOULD
+For variables accepting a numeric value, if the user provides a value the implementation cannot parse,
+or which is outside the valid range for the configuration item, the implementation SHOULD
 generate a warning and gracefully ignore the setting, i.e., treat them as not set.
-In particular, SDKs
+In particular, implementations
 SHOULD NOT assign a custom interpretation e.g. to negative values if a negative
 value does not naturally apply to a configuration and does not have an explicitly specified meaning, but treat it like any other
 invalid value.
@@ -57,15 +68,15 @@ because it might reset a value set from other configuration sources with the def
 
 ### Enum value
 
-For variables which accept a known value out of a set, i.e., an enum value, SDK implementations MAY support additional values not listed here.
-For variables accepting an enum value, if the user provides a value the SDK does not recognize, the SDK MUST generate a warning and gracefully ignore the setting.
+For variables which accept a known value out of a set, i.e., an enum value, implementations MAY support additional values not listed here.
+For variables accepting an enum value, if the user provides a value the implementation does not recognize, the implementation MUST generate a warning and gracefully ignore the setting.
 
 If a null object (empty, no-op) value is acceptable, then the enum value representing it MUST be `"none"`.
 
 ### Duration
 
 Any value that represents a duration, for example a timeout, MUST be an integer representing a number of
-milliseconds. The value is non-negative - if a negative value is provided, the SDK MUST generate a warning,
+milliseconds. The value is non-negative - if a negative value is provided, the implementation MUST generate a warning,
 gracefully ignore the setting and use the default value if it is defined.
 
 For example, the value `12000` indicates 12000 milliseconds, i.e., 12 seconds.
@@ -82,7 +93,7 @@ For example, the value `12000` indicates 12000 milliseconds, i.e., 12 seconds.
 | 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.            |
+| 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 implementation MUST behave as if OTEL_TRACES_SAMPLER_ARG is not set.            |
 
 Known values for `OTEL_PROPAGATORS` are:
 
@@ -140,7 +151,7 @@ Depending on the value of `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` may b
 
 ## Attribute Limits
 
-SDKs SHOULD only offer environment variables for the types of attributes, for
+Implementations 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.
@@ -219,7 +230,7 @@ We define environment variables for setting one or more exporters per signal.
 | OTEL_METRICS_EXPORTER | Metrics exporter to be used | "otlp"  |
 | OTEL_LOGS_EXPORTER | Logs exporter to be used | "otlp"  |
 
-The SDK MAY accept a comma-separated list to enable setting multiple exporters.
+The implementation MAY accept a comma-separated list to enable setting multiple exporters.
 
 Known values for `OTEL_TRACES_EXPORTER` are:
 

specification/context/api-propagators.md

@@ -333,9 +333,9 @@ Required parameters:
 The official list of propagators that MUST be maintained by the OpenTelemetry
 organization and MUST be distributed as OpenTelemetry extension packages:
 
-* [W3C TraceContext](https://www.w3.org/TR/trace-context/). MAY alternatively
+* [W3C TraceContext](https://www.w3.org/TR/trace-context). MAY alternatively
   be distributed as part of the OpenTelemetry API.
-* [W3C Baggage](https://w3c.github.io/baggage). MAY alternatively
+* [W3C Baggage](https://www.w3.org/TR/baggage). MAY alternatively
   be distributed as part of the OpenTelemetry API.
 * [B3](https://github.com/openzipkin/b3-propagation).
 * [Jaeger](https://www.jaegertracing.io/docs/latest/client-libraries/#propagation-format).

specification/logs/README.md

@@ -284,7 +284,7 @@ auto-instrumenting solutions that modify trace logging libraries used by the
 application to automatically output the trace context such as the trace id or
 span id with every log statement. The trace context can be automatically
 extracted from incoming requests if standard compliant request propagation is
-used, e.g. via [W3C TraceContext](https://w3c.github.io/trace-context/). In
+used, e.g. via [W3C TraceContext](https://www.w3.org/TR/trace-context). In
 addition, the requests outgoing from the application may be injected with the
 same trace context data, thus resulting in context propagation through the
 application and creating an opportunity to have full trace context in logs

specification/protocol/exporter.md

@@ -11,14 +11,13 @@ This document specifies the configuration options available to the OpenTelemetry
 ## Configuration Options
 
 The following configuration options MUST be available to configure the OTLP exporter.
-The configuration options MAY be implemented directly in the OTLP exporter, in the SDK, or in a separate component (e.g. environment-based autoconfiguration component).
 Each configuration option MUST be overridable by a signal specific option.
 
-- **Endpoint (OTLP/HTTP)**: Target URL 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, MAY contain a port, SHOULD contain a path and MUST NOT contain other parts (such as query string or fragment). A scheme of https indicates a secure connection. When using `OTEL_EXPORTER_OTLP_ENDPOINT`, exporters MUST construct per-signal URLs as  [described below](#endpoint-urls-for-otlphttp). The per-signal endpoint configuration options take precedence and can be used to override this behavior (the URL is used as-is for them, without any modifications). See the [OTLP Specification][otlphttp-req] for more details.
+- **Endpoint (OTLP/HTTP)**: Target URL to which the exporter is going to send spans, metrics, or logs. The endpoint MUST be a valid URL with scheme (http or https) and host, MAY contain a port, SHOULD contain a path and MUST NOT contain other parts (such as query string or fragment). A scheme of https indicates a secure connection. When using `OTEL_EXPORTER_OTLP_ENDPOINT`, exporters MUST construct per-signal URLs as  [described below](#endpoint-urls-for-otlphttp). The per-signal endpoint configuration options take precedence and can be used to override this behavior (the URL is used as-is for them, without any modifications). See the [OTLP Specification][otlphttp-req] for more details.
   - Default:  `http://localhost:4318` [1]
   - Env vars: `OTEL_EXPORTER_OTLP_ENDPOINT` `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`
 
-- **Endpoint (OTLP/gRPC)**: Target to which the exporter is going to send spans or metrics. The endpoint SHOULD accept any form allowed by the underlying gRPC client implementation. Additionally, the endpoint MUST accept a URL with a scheme of either `http` or `https`. A scheme of `https` indicates a secure connection and takes precedence over the `insecure` configuration setting. A scheme of `http` indicates an insecure connection and takes precedence over the `insecure` configuration setting. If the gRPC client implementation does not support an endpoint with a scheme of `http` or `https` then the endpoint SHOULD be transformed to the most sensible format for that implementation.
+- **Endpoint (OTLP/gRPC)**: Target to which the exporter is going to send spans, metrics, or logs. The endpoint SHOULD accept any form allowed by the underlying gRPC client implementation. Additionally, the endpoint MUST accept a URL with a scheme of either `http` or `https`. A scheme of `https` indicates a secure connection and takes precedence over the `insecure` configuration setting. A scheme of `http` indicates an insecure connection and takes precedence over the `insecure` configuration setting. If the gRPC client implementation does not support an endpoint with a scheme of `http` or `https` then the endpoint SHOULD be transformed to the most sensible format for that implementation.
   - Default: `http://localhost:4317` [1]
   - Env vars: `OTEL_EXPORTER_OTLP_ENDPOINT` `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`
 
@@ -139,7 +138,7 @@ relative to `http://collector:4318/mycollector/`.
 
 ### Specify Protocol
 
-The `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`, and `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` environment variables specify the OTLP transport protocol. Supported values:
+The `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`, `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` and `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL` environment variables specify the OTLP transport protocol. Supported values:
 
 - `grpc` for protobuf-encoded data using gRPC wire format over HTTP/2 connection
 - `http/protobuf` for protobuf-encoded data over HTTP connection
@@ -156,7 +155,7 @@ release).
 
 ### Specifying headers via environment variables
 
-The `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_EXPORTER_OTLP_TRACES_HEADERS`, `OTEL_EXPORTER_OTLP_METRICS_HEADERS` environment variables will contain a list of key value pairs, and these are expected to be represented in a format matching to the [W3C Correlation-Context](https://github.com/w3c/baggage/blob/master/baggage/HTTP_HEADER_FORMAT.md), except that additional semi-colon delimited metadata is not supported, i.e.: key1=value1,key2=value2. All attribute values MUST be considered strings.
+The `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_EXPORTER_OTLP_TRACES_HEADERS`, `OTEL_EXPORTER_OTLP_METRICS_HEADERS`, `OTEL_EXPORTER_OTLP_LOGS_HEADERS` environment variables will contain a list of key value pairs, and these are expected to be represented in a format matching to the [W3C Baggage](https://www.w3.org/TR/baggage/#header-content), except that additional semi-colon delimited metadata is not supported, i.e.: key1=value1,key2=value2. All attribute values MUST be considered strings.
 
 ## Retry
 

specification/resource/sdk.md

@@ -137,7 +137,7 @@ has higher priority.
 
 The `OTEL_RESOURCE_ATTRIBUTES` environment variable will contain of a list of
 key value pairs, and these are expected to be represented in a format matching
-to the [W3C Baggage](https://w3c.github.io/baggage), except that additional
+to the [W3C Baggage](https://www.w3.org/TR/baggage/#header-content), except that additional
 semi-colon delimited metadata is not supported, i.e.: `key1=value1,key2=value2`.
 All attribute values MUST be considered strings and characters outside the
 `baggage-octet` range MUST be percent-encoded.