Specificationv1.44.0

15 Apr 2025since v1.43.0

4 breaking31 notable75 editorial

From the upstream release notes

Add context propagation through Environment Variables specification.
On Propagators API, stabilize GetAll on the TextMap Extract.
Define sampling threshold field in OpenTelemetry TraceState; define the behavior
Clarify SDK behavior for Instrument Advisory Parameter.
Add Enabled opt-in operation to the LogRecordProcessor.
Stabilize Logger.Enabled.
Stabilize EventName.
Add context (baggage) propagation through Environment Variables specification.
Add Datamodel for Entities.
Convert declarative config env var substitution syntax to ABNF.

Read the full release notes

Breaking4

Requirements added to, removed from, or restrengthened in a document marked Stable.

rule droppedrequirementtrace/sdk.md#requirements-for-traceidratiobased-sampler-algorithmMUST removed: The sampling algorithm MUST be deterministic.
rule droppedrequirementtrace/sdk.md#requirements-for-traceidratiobased-sampler-algorithmMUST removed: A trace identified by a given TraceId is sampled or not independent of language, time, etc. To achieve this, implementations MUST use a deterministic hash of the TraceId when computing the sampling decision.
rule droppedrequirementtrace/sdk.md#requirements-for-traceidratiobased-sampler-algorithmMUST removed: A TraceIdRatioBased sampler with a given sampling rate MUST also sample all traces that any TraceIdRatioBased sampler with a lower sampling rate would sample.
new rulerequirementlogs/sdk.md#enabled-1MUST NOT added: Any modifications to parameters inside Enabled MUST NOT be propagated to the caller.

Notable31

removeddocumentspecification/project-management.mdDocument removed (was Unspecified).
removedsectiontrace/sdk.md#do-not-overwrite-explicit-trace-randomnessSection "Do not overwrite explicit trace randomness" removed.
removedsectiontrace/sdk.md#explicit-trace-randomnessSection "Explicit trace randomness" removed.
removedsectiontrace/sdk.md#requirements-for-traceidratiobased-sampler-algorithmSection "Requirements for TraceIdRatioBased sampler algorithm" removed.
removedsectiontrace/sdk.md#root-samplers-set-explicit-trace-randomness-for-non-random-traceidsSection "Root samplers set explicit trace randomness for non-random TraceIDs" removed.
rule droppedrequirementconfiguration/data-model.md#environment-variable-substitutionMUST removed: The ENVNAME MUST start with an alphabetic or ` character, and is followed by 0 or more alphanumeric or _` characters.
rule droppedrequirementconfiguration/data-model.md#environment-variable-substitutionMUST removed: When parsing a configuration file that contains a reference not matching the references regular expression but does match the following PCRE2 regular expression, the parser MUST return an empty result (no partial result...
strengthrequirementmetrics/sdk.md#measurement-processingSHOULD strengthened to MUST: If it is not possible to apply the View without producing semantic errors (e.g. the View sets an asynchronous instrument to use the Explicit bucket histogram aggregation) the implementation SHOULD em...
new rulerequirementcontext/env-carriers.md#case-sensitivityMUST added: For maximum compatibility, implementations MUST:
new rulerequirementcontext/env-carriers.md#name-restrictionsMUST NOT added: MUST NOT include characters forbidden in environment variables per platform-specific restrictions
new rulerequirementcontext/env-carriers.md#size-limitationsMUST added: When truncation is required due to size limitations, implementations MUST truncate whole entries.
new rulerequirementcontext/env-carriers.md#size-limitationsMUST added: Implementers MUST document how graceful truncation is handled and SHOULD provide the link to the corresponding specification (e.g., [W3C tracestate Truncation guidance][w3c-truncation]).
new rulerequirementcontext/env-carriers.md#value-restrictionsMUST added: MUST only use characters that are valid in HTTP header fields per RFC 9110
new rulerequirementcontext/env-carriers.md#value-restrictionsMUST added: MUST follow the format requirements of the specific propagation protocol (e.g., W3C Trace Context specification for TRACEPARENT values)
new rulerequiremententities/data-model.md#entity-data-modelMUST added: MUST not change during the lifetime of the entity.
new rulerequiremententities/data-model.md#entity-data-modelMUST added: This field is required and MUST not be empty for valid entities. </td> </tr> <tr> <td>Id </td> <td>map<string, standard attribute value> </td> <td>Attributes that identify the entity. MUST not change during th...
new rulerequirementlogs/sdk.md#enabled-1MAY added: Enabled is an operation that a LogRecordProcessor MAY implement in order to support filtering via Logger.Enabled.
new rulerequirementmetrics/sdk.md#instrument-advisory-parameter-explicitbucketboundariesMUST added: If no View matches, or if a matching View selects the default aggregation, the ExplicitBucketBoundaries advisory parameter MUST be used.
new rulerequirementmetrics/sdk.md#instrument-advisory-parametersMUST added: If both a View and advisory parameters specify the same aspect of the Stream configuration, the setting defined by the View MUST take precedence over the advisory parameters.
new rulerequirementmetrics/sdk.md#measurement-processingMUST added: Instrument advisory parameters, if any, MUST be honored.
new rulerequirementresource/data-model.md#resource-data-modelMUST added: <table> <tr> <td>Field </td> <td>Type </td> <td>Description </td> </tr> <tr> <td>Entities </td> <td>set<Entity> </td> <td>Defines the set of Entities associated w...
new rulerequirementresource/README.md#overviewMUST added: It MUST identify an entity that is producing telemetry.
new rulerequirementtrace/sdk.md#traceidratiobased-sampler-algorithmSHOULD added: When (R >= T), the OpenTelemetry TraceState SHOULD be modified to include the key-value th:T for rejection threshold value (T), as specified for the [OpenTelemetry TraceState th sub-key][TRACESTATEHANDLING].
new rulerequirementtrace/sdk.md#traceidratiobased-sampler-compatibility-warningSHOULD added: When a TraceIdRatioBased Sampler makes a decision for a non-root Span using TraceID randomness, but the Trace random flag was not set, the SDK SHOULD issue a warning statement in its log with a compatibility warning.
new rulerequirementtrace/tracestate-probability-sampling.md#consistent-sampling-decision-approachMUST added: For this, two values MUST be present in the SpanContext:
new rulerequirementtrace/tracestate-probability-sampling.md#consistent-sampling-decision-approachMUST added: If the current sampling stage applies a greater threshold value than any stage before, it MUST update (increase) the threshold correspondingly by re-encoding the OpenTelemetry TraceState value.
new rulerequirementtrace/tracestate-probability-sampling.md#downstream-samplersMUST NOT added: If the chosen sampling probability is 1, the sampler MUST NOT modify an existing th sub-key value, nor set a th sub-key value.
new rulerequirementtrace/tracestate-probability-sampling.md#downstream-samplersMUST added: In this case the sampler MUST output the span with a th equal to max(input th, chosen th).
new rulerequirementtrace/tracestate-probability-sampling.md#downstream-samplersMUST NOT added: In other words, th MUST NOT be decreased (as it is not possible to retroactively adjust an earlier stage's sampling probability), and it MUST be increased if a lower sampling probability was used.
new rulerequirementtrace/tracestate-probability-sampling.md#head-samplersMUST added: The th key MUST be defined with a threshold value corresponding to the sampling probability the sampler used.
new rulerequirementtrace/tracestate-probability-sampling.md#head-samplersMUST added: If trace randomness was derived from a OpenTelemetry TraceState rv sub-key value, the same rv value MUST be defined and equal to the incoming OpenTelemetry TraceState rv sub-key value.

Editorial75

new rulerequirementconfiguration/sdk.md#supported-sdk-extension-pluginsSHOULD added: The configuration data model SHOULD support configuration of all SDK extension plugin interfaces.
new rulerequirementconfiguration/sdk.md#supported-sdk-extension-pluginsSHOULD added: SDKs SHOULD support registration of custom implementations of SDK extension plugin interfaces via the ComponentProvider mechanism.
new rulerequirementcontext/env-carriers.md#environment-variable-immutabilitySHOULD added: Once set for a process, environment variables SHOULD be treated as immutable within that process:
new rulerequirementcontext/env-carriers.md#environment-variable-immutabilitySHOULD added: Applications SHOULD read context-related environment variables during initialization.
new rulerequirementcontext/env-carriers.md#environment-variable-immutabilitySHOULD NOT added: Applications SHOULD NOT modify context-related environment variables of the environment in which the parent process exists.
new rulerequirementcontext/env-carriers.md#environment-variable-namesRECOMMENDED added: It is RECOMMENDED to use the W3C Trace Context and W3C Baggage specifications mapped to environment variable names for consistent context propagation.
new rulerequirementcontext/env-carriers.md#environment-variable-namesSHOULD added: When using the W3C Trace Context and Baggage propagators with environment variables, the following translated standard environment variable names SHOULD be used:
new rulerequirementcontext/env-carriers.md#environment-variable-namesSHOULD added: Implementations MAY support additional propagation formats and SHOULD provide configuration options to override the default environment variable.
new rulerequirementcontext/env-carriers.md#name-restrictionsSHOULD added: SHOULD use uppercase letters, digits, and underscores for maximum cross-platform compatibility
new rulerequirementcontext/env-carriers.md#name-restrictionsSHOULD added: SHOULD follow naming conventions that align with the propagation format specification they're implementing (e.g., TRACEPARENT for W3C trace context)
new rulerequirementcontext/env-carriers.md#process-spawningSHOULD added: Parent processes SHOULD copy the current environment variables (if applicable), modify, and inject context when spawning child processes.
new rulerequirementcontext/env-carriers.md#process-spawningSHOULD added: Child processes SHOULD extract context from environment variables at startup.
new rulerequirementcontext/env-carriers.md#process-spawningSHOULD added: When spawning multiple child processes with different contexts or baggage, each child SHOULD receive its own copy of the environment variables with appropriate information.
new rulerequirementcontext/env-carriers.md#propagator-mechanismsSHOULD added: A TextMapPropagator SHOULD be used alongside its normal Get, Set, Extract, and Inject functionality as described in the API Propagators specification.
new rulerequirementcontext/env-carriers.md#securitySHOULD NOT added: Implementations SHOULD NOT store sensitive information in environment variables.
new rulerequirementcontext/env-carriers.md#securitySHOULD added: Applications running in multi-tenant environments SHOULD be aware that environment variables may be visible to other processes or users with appropriate permissions.
new rulerequirementcontext/env-carriers.md#size-limitationsSHOULD added: Implementations SHOULD follow platform-specific environment variable size limitations:
new rulerequirementcontext/env-carriers.md#size-limitationsSHOULD added: Truncation SHOULD start at the end of the entry list.
new rulerequirementcontext/env-carriers.md#value-restrictionsSHOULD NOT added: SHOULD NOT contain sensitive information
new rulerequiremententities/data-model.md#entity-data-modelSHOULD added: SHOULD follow OpenTelemetry <a href="https://github.com/open-telemetry/semantic-conventions">semantic conventions</a> for attributes. </td> </tr> <tr> <td>Description </td> <td>map<string, any> </td> <td>Descripti...
new rulerequiremententities/data-model.md#entity-data-modelMAY added: MAY be empty.
new rulerequiremententities/data-model.md#entity-data-modelSHOULD added: Arbitrary deep nesting of values for arrays and maps is allowed. SHOULD follow OpenTelemetry <a href="https://github.com/open-telemetry/semantic-conventions">semantic conventions</a> for attributes. </td> </tr> </ta...
new rulerequiremententities/data-model.md#examples-of-entitiesMAY added: Note: These examples MAY diverge from semantic conventions.
new rulerequiremententities/data-model.md#repeatable-identitySHOULD added: The identifying attributes for entity SHOULD be values that can be repeatably obtained by observers of that entity.
new rulerequiremententities/data-model.md#repeatable-identitySHOULD added: For example, a process entity SHOULD have the same identity (and be recognized as the same process), regardless of whether the identity was generated from the process itself, e.g. via SDK, or by an OpenTelemetry Colle...
new rulerequirementresource/README.md#navigationSHOULD added: > Aside: Observability signals SHOULD be actionable.
new rulerequirementresource/README.md#overviewSHOULD added: It SHOULD allow users to determine where that entity resides within their infrastructure.
new rulerequirementtrace/tracestate-probability-sampling.md#head-samplersSHOULD added: When a span is sampled by in accordance with this specification, the output TraceState SHOULD be set to convey probability sampling:
new rulerequirementtrace/tracestate-probability-sampling.md#migration-to-consistent-probability-samplersSHOULD added: To avoid inconsistency during this transition, users SHOULD follow this guidance until all Trace SDKs in a system have been upgraded to modern Trace randomness requirements based on W3C Trace Context Level 2.
rewordedrequirementconfiguration/data-model.md#environment-variable-substitutionMUST reworded: If a referenced environment variable is not defined and does not have a DEFAULT-VALUE, it MUST be replaced with an empty value.
rewordedrequirementtrace/sdk.md#traceidratiobasedMUST reworded: The TraceIdRatioBased sampler MUST ignore the parent SampledFlag.
movedrequirementtrace/sdk.md#do-not-overwrite-explicit-randomnessMUST NOT moved here from "do-not-overwrite-explicit-trace-randomness": SDKs and Samplers MUST NOT overwrite explicit randomness in an OpenTelemetry TraceState value.
movedrequirementtrace/sdk.md#root-samplers-set-explicit-randomness-for-non-random-traceidsMAY moved here from "root-samplers-set-explicit-trace-randomness-for-non-random-traceids": Root Samplers MAY insert an explicit randomness value into the OpenTelemetry TraceState value in cases where an explicit randomness value is not already set.
movedrequirementtrace/sdk.md#traceidratiobased-sampler-descriptionMUST moved here from "traceidratiobased": The TraceIdRatioBased GetDescription MUST return a string of the form "TraceIdRatioBased{RATIO}" with RATIO replaced with the Sampler instance's trace sampling ratio represented as a decimal nu...
movedrequirementtrace/sdk.md#traceidratiobased-sampler-descriptionSHOULD moved here from "traceidratiobased": The precision of the number SHOULD follow implementation language standards and SHOULD be high enough to identify when Samplers have different ratios.
addedsectionconfiguration/sdk.md#supported-sdk-extension-pluginsNew section "Supported SDK extension plugins".
addeddocumentcontext/env-carriers.mdNew document: Environment Variables as Context Propagation Carriers (Experimental).
addeddocumententities/data-model.mdNew document: Entity Data Model (Development).
addeddocumententities/README.mdNew document: Entities (Unspecified).
addedsectionlogs/sdk.md#enabled-1New section "Enabled".
addedsectionmetrics/sdk.md#instrument-advisory-parameter-attributesNew section "Instrument advisory parameter: Attributes".
addedsectionmetrics/sdk.md#instrument-advisory-parameter-explicitbucketboundariesNew section "Instrument advisory parameter: ExplicitBucketBoundaries".
addeddocumentresource/data-model.mdNew document: Resource Data Model (Development).
addedsectionresource/README.md#identityNew section "Identity".
addedsectionresource/README.md#navigationNew section "Navigation".
addedsectionresource/README.md#overviewNew section "Overview".
addedsectionresource/README.md#specificationsNew section "Specifications".
addedsectionresource/README.md#telescopingNew section "Telescoping".
addedsectiontrace/sdk.md#do-not-overwrite-explicit-randomnessNew section "Do not overwrite explicit randomness".
addedsectiontrace/sdk.md#explicit-randomnessNew section "Explicit randomness".
addedsectiontrace/sdk.md#root-samplers-set-explicit-randomness-for-non-random-traceidsNew section "Root samplers set explicit randomness for non-random TraceIDs".
addedsectiontrace/sdk.md#traceidratiobased-sampler-algorithmNew section "TraceIdRatioBased sampler algorithm".
addedsectiontrace/sdk.md#traceidratiobased-sampler-compatibility-warningNew section "TraceIdRatioBased sampler compatibility warning".
addedsectiontrace/sdk.md#traceidratiobased-sampler-configurationNew section "TraceIdRatioBased sampler configuration".
addedsectiontrace/sdk.md#traceidratiobased-sampler-descriptionNew section "TraceIdRatioBased sampler description".
addedsectiontrace/tracestate-handling.md#sampling-threshold-value-thNew section "Sampling threshold value th".
addedsectiontrace/tracestate-probability-sampling.md#algorithmsNew section "Algorithms".
addedsectiontrace/tracestate-probability-sampling.md#consistent-sampling-decisionNew section "Consistent Sampling Decision".
addedsectiontrace/tracestate-probability-sampling.md#consistent-sampling-decision-approachNew section "Consistent Sampling Decision Approach".
addedsectiontrace/tracestate-probability-sampling.md#converting-floating-point-probability-to-threshold-valueNew section "Converting floating-point probability to threshold value".
addedsectiontrace/tracestate-probability-sampling.md#converting-integer-threshold-to-a-th-valueNew section "Converting integer threshold to a th-value".
addedsectiontrace/tracestate-probability-sampling.md#converting-threshold-to-a-sampling-probabilityNew section "Converting threshold to a sampling probability".
addedsectiontrace/tracestate-probability-sampling.md#converting-threshold-to-an-adjusted-count-sampling-rateNew section "Converting threshold to an adjusted count (sampling rate)".
addedsectiontrace/tracestate-probability-sampling.md#definitionsNew section "Definitions".
addedsectiontrace/tracestate-probability-sampling.md#downstream-samplersNew section "Downstream samplers".
addedsectiontrace/tracestate-probability-sampling.md#head-samplersNew section "Head samplers".
addedsectiontrace/tracestate-probability-sampling.md#migration-to-consistent-probability-samplersNew section "Migration to consistent probability samplers".
addedsectiontrace/tracestate-probability-sampling.md#overviewNew section "Overview".
addedsectiontrace/tracestate-probability-sampling.md#randomness-value-rvNew section "Randomness Value (rv)".
addedsectiontrace/tracestate-probability-sampling.md#rejection-threshold-thNew section "Rejection Threshold (th)".
addedsectiontrace/tracestate-probability-sampling.md#sampler-behavior-for-initializing-and-updating-th-and-rv-valuesNew section "Sampler behavior for initializing and updating th and rv values".
addedsectiontrace/tracestate-probability-sampling.md#sampling-probabilityNew section "Sampling Probability".
addedsectiontrace/tracestate-probability-sampling.md#testing-randomness-vs-thresholdNew section "Testing randomness vs threshold".
rewrittensectionmetrics/sdk.md#instrument-advisory-parameters"Instrument advisory parameters" substantially rewritten (579 to 818 characters).
rewrittensectiontrace/tracestate-probability-sampling.md#tracestate-probability-sampling"TraceState: Probability Sampling" substantially rewritten (451 to 48 characters).