Specificationv1.47.0

18 Jul 2025since v1.46.0

4 breaking16 notable50 editorial

From the upstream release notes

Define sampling threshold field in OpenTelemetry TraceState; define the behavior
Define CompositeSampler implementation and built-in ComposableSampler interfaces.
Define how SDK implements Tracer.Enabled.
Stabilize Event Name parameter of Logger.Enabled.
Stabilize SDK and No-Op Logger.Enabled.
SeverityNumber=0 MAY be used to represent an unspecified value.
Clarify expectations about Prometheus content negotiation for metric names.
Add Supplementary Guidelines for environment variables as context carrier
Extend attributes to support complex values.
Update spec to comply with OTEP-232.

Read the full release notes

Breaking4

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

new rulerequirementtrace/sdk.md#enabledMUST added: Enabled MUST return false when either:
new rulerequirementtrace/sdk.md#getsamplingintentMUST NOT added: Note: ComposableSamplers MUST NOT modify the parameters passed to delegate GetSamplingIntent methods, as they are considered read-only state.
new rulerequirementtrace/sdk.md#getsamplingintentMUST NOT added: ComposableSamplers MUST NOT modify the OpenTelemetry TraceState (i.e., the ot sub-key of TraceState).
new rulerequirementtrace/sdk.md#getsamplingintentMUST added: The calling CompositeSampler SHOULD update the threshold of the outgoing TraceState (unless !threshold_reliable) and that the explicit randomness values MUST not be modified.

Notable16

rule droppedrequirementtrace/tracestate-probability-sampling.md#consistent-sampling-decision-approachMUST removed: 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.
rule droppedrequirementtrace/tracestate-probability-sampling.md#downstream-samplersMUST NOT removed: 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.
rule droppedrequirementtrace/tracestate-probability-sampling.md#downstream-samplersMUST removed: In this case the sampler MUST output the span with a th equal to max(input th, chosen th).
rule droppedrequirementtrace/tracestate-probability-sampling.md#downstream-samplersMUST NOT removed: 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.
rule droppedrequirementtrace/tracestate-probability-sampling.md#head-samplersMUST removed: The th key MUST be defined with a threshold value corresponding to the sampling probability the sampler used.
rule droppedrequirementtrace/tracestate-probability-sampling.md#head-samplersMUST removed: 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.
stabilitydocumentcontext/env-carriers.mdStatus changed from Experimental to Alpha.
new rulerequirementcontext/env-carriers.md#process-spawningMUST NOT added: The language implementations MUST NOT handle spawning processes.
new rulerequirementspecification/document-status.md#maturity-levelsMUST added: They also MUST communicate in which version they will be removed.| |Unmaintained |A component identified as unmaintained does not have an active code owner.
new rulerequirementlogs/data-model.md#field-severitynumberMAY added: SeverityNumber=0 MAY be used to represent an unspecified value.
new rulerequirementsdk_exporters/prometheus.md#content-negotiationMUST added: A Prometheus Exporter MUST support content negotiation to allow clients to request metrics in different formats based on the Accept header in HTTP requests.
new rulerequirementsdk_exporters/prometheus.md#content-negotiationMUST added: Content negotiation MUST follow Prometheus Content Negotiation guidelines.
new rulerequirementtrace/sdk.md#composabletraceidratiobasedSHOULD added: For the zero case a ComposableAlwaysOff instance SHOULD be returned instead.
new rulerequirementtrace/sdk.md#enabledSHOULD added: Otherwise, it SHOULD return true.
new rulerequirementtrace/sdk.md#enabledMAY added: It MAY return false to support additional optimizations and features.
new rulerequirementtrace/sdk.md#getsamplingintentMAY added: Parent context, threshold, incoming trace state, and trace flag information MAY be precomputed so that ComposableSamplers do not repeatedly probe the Context for this information.

Editorial50

removedsectionspecification/document-status.md#feature-freezeSection "Feature freeze" removed.
removedsectionspecification/document-status.md#lifecycle-statusSection "Lifecycle status" removed.
removedsectiontrace/tracestate-probability-sampling.md#consistent-sampling-decision-approachSection "Consistent Sampling Decision Approach" removed.
removedsectiontrace/tracestate-probability-sampling.md#converting-integer-threshold-to-a-th-valueSection "Converting integer threshold to a th-value" removed.
removedsectiontrace/tracestate-probability-sampling.md#downstream-samplersSection "Downstream samplers" removed.
removedsectiontrace/tracestate-probability-sampling.md#head-samplersSection "Head samplers" removed.
removedsectiontrace/tracestate-probability-sampling.md#randomness-value-rvSection "Randomness Value (rv)" removed.
removedsectiontrace/tracestate-probability-sampling.md#rejection-threshold-thSection "Rejection Threshold (th)" removed.
removedsectiontrace/tracestate-probability-sampling.md#sampler-behavior-for-initializing-and-updating-th-and-rv-valuesSection "Sampler behavior for initializing and updating th and rv values" removed.
rule droppedrequirementtrace/tracestate-probability-sampling.md#head-samplersSHOULD removed: When a span is sampled by in accordance with this specification, the output TraceState SHOULD be set to convey probability sampling:
new rulerequirementspecification/document-status.md#maturity-levelsSHOULD NOT added: The component SHOULD NOT be used in production.
new rulerequirementspecification/document-status.md#maturity-levelsMAY added: The component MAY be removed without prior notice.| |Alpha |The component is ready to be used for limited non-critical production workloads, and the authors of this component welcome user feedback.
new rulerequirementspecification/document-status.md#maturity-levelsSHOULD added: Issues and pull requests for unmaintained components SHOULD be labeled as such.
new rulerequirementspecification/document-status.md#maturity-levelsMAY added: After 6 months of being unmaintained, these components MAY be deprecated.
rewordedrequirementlogs/sdk.md#enabledMUST reworded: Enabled MUST return false when either:
movedrequirementtrace/tracestate-probability-sampling.md#decision-algorithmMUST moved here from "consistent-sampling-decision-approach": For this, two values MUST be present:
addedsectioncontext/env-carriers.md#approach-1-providing-a-dedicated-environmentcontextpropagatorNew section "Approach 1: Providing a dedicated EnvironmentContextPropagator".
addedsectioncontext/env-carriers.md#approach-2-using-the-carriers-directly-through-setters-and-gettersNew section "Approach 2: Using the carriers directly through Setters and Getters".
addedsectioncontext/env-carriers.md#common-behaviorsNew section "Common Behaviors".
addedsectioncontext/env-carriers.md#supplementary-guidelinesNew section "Supplementary Guidelines".
addedsectionspecification/document-status.md#maturity-levelsNew section "Maturity levels".
addedsectionsdk_exporters/prometheus.md#content-negotiationNew section "Content Negotiation".
addedsectiontrace/sdk.md#built-in-composablesamplersNew section "Built-in ComposableSamplers".
addedsectiontrace/sdk.md#composablealwaysoffNew section "ComposableAlwaysOff".
addedsectiontrace/sdk.md#composablealwaysonNew section "ComposableAlwaysOn".
addedsectiontrace/sdk.md#composableannotatingNew section "ComposableAnnotating".
addedsectiontrace/sdk.md#composableparentthresholdNew section "ComposableParentThreshold".
addedsectiontrace/sdk.md#composablerulebasedNew section "ComposableRuleBased".
addedsectiontrace/sdk.md#composablesamplerNew section "ComposableSampler".
addedsectiontrace/sdk.md#composabletraceidratiobasedNew section "ComposableTraceIDRatioBased".
addedsectiontrace/sdk.md#compositesamplerNew section "CompositeSampler".
addedsectiontrace/sdk.md#enabledNew section "Enabled".
addedsectiontrace/sdk.md#getsamplingintentNew section "GetSamplingIntent".
addedsectiontrace/tracestate-probability-sampling.md#approach-and-terminologyNew section "Approach and Terminology".
addedsectiontrace/tracestate-probability-sampling.md#converting-integer-threshold-to-a-t-valueNew section "Converting integer threshold to a T-value".
addedsectiontrace/tracestate-probability-sampling.md#decision-algorithmNew section "Decision algorithm".
addedsectiontrace/tracestate-probability-sampling.md#downstream-thresholdNew section "Downstream threshold".
addedsectiontrace/tracestate-probability-sampling.md#equalizing-downstream-samplerNew section "Equalizing downstream sampler".
addedsectiontrace/tracestate-probability-sampling.md#general-requirementsNew section "General requirements".
addedsectiontrace/tracestate-probability-sampling.md#independent-parentchild-thresholdNew section "Independent parent/child threshold".
addedsectiontrace/tracestate-probability-sampling.md#parent-based-thresholdNew section "Parent-based threshold".
addedsectiontrace/tracestate-probability-sampling.md#parentchild-thresholdNew section "Parent/Child threshold".
addedsectiontrace/tracestate-probability-sampling.md#proportional-downstream-samplerNew section "Proportional downstream sampler".
addedsectiontrace/tracestate-probability-sampling.md#randomness-value-rNew section "Randomness Value (R)".
addedsectiontrace/tracestate-probability-sampling.md#rejection-threshold-tNew section "Rejection Threshold (T)".
addedsectiontrace/tracestate-probability-sampling.md#sampling-base-casesNew section "Sampling base cases".
addedsectiontrace/tracestate-probability-sampling.md#sampling-related-termsNew section "Sampling related terms".
addedsectiontrace/tracestate-probability-sampling.md#sampling-stagesNew section "Sampling stages".
addedsectiontrace/tracestate-probability-sampling.md#tracestate-handling-requirementsNew section "Tracestate handling requirements".
rewrittensectioncontext/env-carriers.md#process-spawning"Process Spawning" substantially rewritten (432 to 637 characters).