Specificationv1.50.0

17 Oct 2025since v1.49.0

15 breaking26 notable24 editorial

From the upstream release notes

Restore TraceIdRatioBased and give it a deprecation timeline. Update recommended
Changes of TracerConfig.disabled MUST be eventually visible.
Remove text related to the former expermental probability sampling specification.
Changes of MeterConfig.disabled MUST be eventually visible.
Add minimum_severity and trace_based logger configuration parameters.
Changes of LoggerConfig.disabled MUST be eventually visible.

Read the full release notes

Breaking15

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

rule droppedrequirementlogs/sdk.md#loggerconfigMUST removed: The value of disabled MUST be used to resolve whether a Logger is Enabled.
new rulerequirementlogs/sdk.md#emit-a-logrecordMUST added: Status: Development Before processing a log record, the implementation MUST apply the filtering rules defined by the LoggerConfig (in case Enabled was not called prior to emitting the record):
new rulerequirementlogs/sdk.md#emit-a-logrecordMUST added: Minimum severity: If the log record's SeverityNumber is specified (i.e. not 0) and is less than the configured minimum_severity, the log record MUST be dropped.
new rulerequirementlogs/sdk.md#emit-a-logrecordMUST added: Trace-based: If trace_based is true, and if the log record has a SpanId and the TraceFlags SAMPLED flag is unset, the log record MUST be dropped.
new rulerequirementlogs/sdk.md#loggerconfigMUST added: If not explicitly set, the minimum_severity parameter MUST default to 0.
new rulerequirementlogs/sdk.md#loggerconfigMUST added: If a log record's SeverityNumber is specified (i.e. not 0) and is less than the configured minimum_severity, the log record MUST be dropped by the Logger.
new rulerequirementlogs/sdk.md#loggerconfigMUST added: If not explicitly set, the trace_based parameter MUST default to false.
new rulerequirementlogs/sdk.md#loggerconfigMUST added: If trace_based is true, log records associated with unsampled traces MUST be dropped by the Logger.
new rulerequirementlogs/sdk.md#loggerconfigMUST added: However, the changes MUST be eventually visible.
new rulerequirementtrace/sdk.md#probabilitysamplerMUST added: The ProbabilitySampler sampler MUST ignore the parent SampledFlag.
new rulerequirementtrace/sdk.md#requirements-for-traceidratiobased-sampler-algorithmMUST added: The sampling algorithm MUST be deterministic.
new rulerequirementtrace/sdk.md#requirements-for-traceidratiobased-sampler-algorithmMUST added: 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.
new rulerequirementtrace/sdk.md#requirements-for-traceidratiobased-sampler-algorithmMUST added: A TraceIdRatioBased sampler with a given sampling probability MUST also sample all traces that any TraceIdRatioBased sampler with a lower sampling probability would sample.
new rulerequirementtrace/sdk.md#traceidratiobasedSHALL NOT added: OpenTelemetry SDK implementors SHALL NOT remove or modify the behavior of the original TraceIdRatioBased sampler until at least January 1,
new rulerequirementtrace/sdk.md#tracerconfigMUST added: However, the changes MUST be eventually visible.

Notable26

removedsectiontrace/sdk.md#composabletraceidratiobasedSection "ComposableTraceIDRatioBased" removed.
removedsectiontrace/sdk.md#traceidratiobased-sampler-algorithmSection "TraceIdRatioBased sampler algorithm" removed.
removedsectiontrace/sdk.md#traceidratiobased-sampler-compatibility-warningSection "TraceIdRatioBased sampler compatibility warning" removed.
removedsectiontrace/sdk.md#traceidratiobased-sampler-configurationSection "TraceIdRatioBased sampler configuration" removed.
removedsectiontrace/sdk.md#traceidratiobased-sampler-descriptionSection "TraceIdRatioBased sampler description" removed.
removeddocumenttrace/tracestate-probability-sampling-experimental.mdDocument removed (was Development).
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-combine-multiple-consistent-probability-samplers-using-the-minimum-p-valueMUST removed: When combining Sampler decisions for multiple consistent probability Samplers and at least one decides to sample, the minimum of the "yes" decision p values MUST be set in the tracestate.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-combining-multiple-sampling-decisions-using-logical-orMUST removed: When multiple samplers are combined using composition, the sampling decision MUST be to sample if at least one of the combined samplers decides to sample.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-consistentprobabilitybased-sampler-decides-not-to-sample-for-probabilities-less-than-2-62MUST removed: If the configured sampling probability is in the interval [0, 2**-62), the Sampler MUST decide not to sample.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-consistentprobabilitybased-sampler-records-unbiased-adjusted-countsMUST removed: The ConsistentProbabilityBased Sampler with non-zero probability MUST set p so that the adjusted count interpreted from the tracestate is an unbiased estimate of the number of representative spans in the populatio...
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-consistentprobabilitybased-sampler-sets-p-when-sampledMUST removed: The ConsistentProbabilityBased Sampler MUST set p when it decides to sample according to its configured sampling probability.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-consistentprobabilitybased-sampler-sets-r-for-root-spanMUST removed: The ConsistentProbabilityBased Sampler MUST set r when it makes a root sampling decision.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-consistentprobabilitybased-sampler-unsets-p-when-not-sampledMUST removed: The ConsistentProbabilityBased Sampler MUST unset p from the tracestate when it decides not to sample.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-parentconsistentprobabilitybased-calls-the-configured-root-sampler-for-root-spansMUST removed: The ParentConsistentProbabilityBased Sampler MUST delegate to the configured root Sampler when there is not a valid parent trace context.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-parentconsistentprobabilitybased-does-not-modify-valid-tracestateMUST NOT removed: The ParentConsistentProbabilityBased Sampler MUST NOT modify a valid tracestate.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-parentconsistentprobabilitybased-respects-the-sampled-flag-for-non-root-spansMUST removed: The ParentConsistentProbabilityBased Sampler MUST decide to sample the span according to the value of the sampled flag in the W3C traceparent header.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-pass-12-non-power-of-two-statistical-testsMUST removed: For the test with 20 trials and 100,000 spans each, the test MUST demonstrate a random number generator seed such that the ChiSquared test statistic is below 0.102587 exactly 1 out of 20 times.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-pass-3-power-of-two-statistical-testsMUST removed: For the test with 20 trials and 100,000 spans each, the test MUST demonstrate a random number generator seed such that the ChiSquared test statistic is below 0.003932 exactly 1 out of 20 times.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-r-value-is-generated-with-the-correct-probabilitiesMUST removed: Samplers MUST generate r-values using a randomized scheme that produces each value with the probabilities equivalent to those produced by counting the number of leading 0s in a string of 62 random bits.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-traceidratiobased-api-compatibilityMUST removed: The ConsistentProbabilityBased Sampler MUST have the same constructor signature as the built-in TraceIdRatioBased sampler in each OpenTelemetry SDK.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-unset-p-when-multiple-consistent-probability-samplers-decide-not-to-sampleMUST removed: When combining Sampler decisions for multiple consistent probability Samplers and none decides to sample, p-value MUST be unset in the tracestate.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-use-p-value-63-when-a-probability-sampler-decision-not-to-sample-is-combined-with-a-non-probability-sampler-decision-to-sampleMUST removed: When combining Sampler decisions for a consistent probability Sampler and a non-probability Sampler, and the probability Sampler decides not to sample but the non-probability does sample, p-value 63 MUST be set in the `...
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-use-probability-sampler-p-value-when-its-decision-to-sample-is-combined-with-non-probability-samplersMUST removed: When combining Sampler decisions for a consistent probability Sampler and a non-probability Sampler, and the probability Sampler decides to sample, its p-value MUST be set in the tracestate regardless of the non-proba...
new rulerequirementmetrics/sdk.md#instrument-enabledMUST added: However, the changes MUST be eventually visible.
new rulerequirementtrace/sdk.md#compatibility-warnings-for-traceidratiobased-samplerSHOULD added: When this sampler observes a non-empty parent span context, meaning when it is used not as a root sampler, the SDK SHOULD emit a warning such as:
new rulerequirementtrace/sdk.md#compatibility-warnings-for-traceidratiobased-samplerMAY added: In such a scenario, this sampler can also detect the use of a ProbabilitySampler by inspecting Tracestate for OpenTelemetry tracestate (ot=...) with th or rv subkeys, in which case the warning MAY be more direct:

Editorial24

rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#recommendation-recognize-inconsistent-r-valuesSHOULD removed: When a single trace contains spans with tracestate values containing more than one distinct value for r, the consumer SHOULD recognize the trace as inconsistently sampled.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#recommendation-sampler-delegationSHOULD NOT removed: For non-root spans, composite samplers SHOULD NOT condition the choice of delegated-to sampler based on the parent's sampled flag or OpenTelemetry tracestate.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#recommendation-use-non-descending-power-of-two-probabilitiesSHOULD removed: To ensure complete sub-traces are produced, child samplers SHOULD be configured with a power-of-two probability greater than or equal to the parent span's sampling probability.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-consistentprobabilitybased-sampler-sets-r-for-non-root-spanSHOULD removed: If r is not set on the input tracecontext and the Span is not a root span, ConsistentProbabilityBased SHOULD set r as if it were a root span and warn the user that a potentially inconsistent trace is being produ...
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-inconsistent-p-values-are-unsetSHOULD removed: Samplers SHOULD unset p when the invariant between the sampled, p, and r values is violated before using the tracestate to make a sampling decision or interpret adjusted count.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-out-of-range-p-values-are-unsetSHOULD removed: Consumers SHOULD unset p from the tracestate if the unsigned decimal value is greater than 63 before using the tracestate to make a sampling decision or interpret adjusted count.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-out-of-range-r-values-unset-both-p-and-rSHOULD removed: Samplers SHOULD unset both r and p from the tracestate if the unsigned decimal value of r is greater than 62 before using the tracestate to make a sampling decision.
rule droppedrequirementtrace/tracestate-probability-sampling-experimental.md#requirement-parentconsistentprobabilitybased-apiSHOULD removed: The ParentConsistentProbabilityBased Sampler constructor SHOULD take a single Sampler argument, which is the Sampler to use in case the ParentConsistentProbabilityBased Sampler is called for a root span.
rewordedrequirementtrace/sdk.md#traceidratiobasedMUST reworded: The TraceIdRatioBased MUST ignore the parent SampledFlag.
movedrequirementtrace/sdk.md#compatibility-warnings-for-probabilitysamplerSHOULD moved here from "traceidratiobased-sampler-compatibility-warning": When a ProbabilitySampler Sampler makes a decision for a non-root Span using TraceID randomness when the Trace random flag was not set, the SDK SHOULD issue a warning statement in its log with a comp...
movedrequirementtrace/sdk.md#composableprobabilitySHOULD moved here from "composabletraceidratiobased": For the zero case a ComposableAlwaysOff instance SHOULD be returned instead.
movedrequirementtrace/sdk.md#probabilitysampler-sampler-algorithmSHOULD moved here from "traceidratiobased-sampler-algorithm": 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][TRACESTA...
movedrequirementtrace/sdk.md#traceidratiobasedMUST moved here from "traceidratiobased-sampler-description": Description MUST return a string of the form "TraceIdRatioBased{RATIO}" with RATIO replaced with the Sampler instance's trace sampling ratio represented as a decimal number.
movedrequirementtrace/sdk.md#traceidratiobasedSHOULD moved here from "traceidratiobased-sampler-description": The precision of the number SHOULD follow implementation language standards and SHOULD be high enough to identify when Samplers have different ratios.
addedsectiontrace/sdk.md#compatibility-warnings-for-probabilitysamplerNew section "Compatibility warnings for ProbabilitySampler".
addedsectiontrace/sdk.md#compatibility-warnings-for-traceidratiobased-samplerNew section "Compatibility warnings for TraceIdRatioBased sampler".
addedsectiontrace/sdk.md#composableprobabilityNew section "ComposableProbability".
addedsectiontrace/sdk.md#probabilitysamplerNew section "ProbabilitySampler".
addedsectiontrace/sdk.md#probabilitysampler-sampler-algorithmNew section "ProbabilitySampler sampler algorithm".
addedsectiontrace/sdk.md#probabilitysampler-sampler-configurationNew section "ProbabilitySampler sampler configuration".
addedsectiontrace/sdk.md#requirements-for-traceidratiobased-sampler-algorithmNew section "Requirements for TraceIdRatioBased sampler algorithm".
rewrittensectionlogs/sdk.md#emit-a-logrecord"Emit a LogRecord" substantially rewritten (140 to 843 characters).
rewrittensectionlogs/sdk.md#enabled"Enabled" substantially rewritten (540 to 921 characters).
rewrittensectionlogs/sdk.md#loggerconfig"LoggerConfig" substantially rewritten (798 to 1832 characters).