Specificationv1.52.0

12 Dec 2025since v1.51.0

12 breaking19 notable29 editorial

From the upstream release notes

Make the W3C randomness flag required.
Deprecate Zipkin exporter document and make exporter implementation optional.
Add spec for AlwaysRecord sampler
Stabilize Enabled API for synchronous instruments.
Allow instrument Enabled implementation to have additional optimizations and features.
Stabilize LogRecordProcessor.Enabled.
Clarifies that guidance related to boolean environment variables is not applicable

Read the full release notes

Breaking12

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

rule droppedrequirementconfiguration/sdk-environment-variables.md#durationMUST removed: Any value that represents a duration MUST be an integer representing a number of milliseconds.
rule droppedrequirementconfiguration/sdk-environment-variables.md#durationMUST removed: 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.
rule droppedrequirementconfiguration/sdk-environment-variables.md#enumMUST removed: If a null object (empty, no-op) value is acceptable, then the enum value representing it MUST be "none".
rule droppedrequirementconfiguration/sdk-environment-variables.md#timeoutMUST removed: Any value that represents a timeout MUST be an integer representing a number of milliseconds.
rule droppedrequirementconfiguration/sdk-environment-variables.md#timeoutMUST removed: 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.
new rulerequirementconfiguration/common.md#durationMUST added: Any value that represents a duration MUST be an integer representing a number of milliseconds.
new rulerequirementconfiguration/common.md#durationMUST added: 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.
new rulerequirementconfiguration/common.md#enumMUST added: If a null object (empty, no-op) value is acceptable, then the enum value representing it MUST be "none".
new rulerequirementconfiguration/common.md#numericMUST added: > The following paragraph was added after stabilization and the requirements are > thus qualified as "SHOULD" to allow implementations to avoid breaking changes. > For new > implementations, these should be treated as M...
new rulerequirementconfiguration/common.md#timeoutMUST added: Any value that represents a timeout MUST be an integer representing a number of milliseconds.
new rulerequirementconfiguration/common.md#timeoutMUST added: 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.
new rulerequirementtrace/sdk.md#alwaysrecordMUST added: Based on the decision from the wrapped root sampler, AlwaysRecord MUST behave as follows:

Notable19

removedsectionconfiguration/sdk-environment-variables.md#configuration-typesSection "Configuration types" removed.
removedsectionconfiguration/sdk-environment-variables.md#durationSection "Duration" removed.
removedsectionconfiguration/sdk-environment-variables.md#integerSection "Integer" removed.
removedsectionconfiguration/sdk-environment-variables.md#timeoutSection "Timeout" removed.
strengthrequirementmetrics/sdk.md#instrument-enabledMUST relaxed to SHOULD: Otherwise, it SHOULD return true.
stabilitydocumentsdk_exporters/zipkin.mdStatus changed from Stable to Deprecated.
new rulerequirementconfiguration/common.md#enumMAY added: For configuration sources which accept a known value out of a set, i.e., an enum value, implementations MAY support additional values not listed here.
new rulerequirementconfiguration/common.md#enumSHOULD added: When reporting configuration errors, implementations SHOULD display the original user-provided value to aid debugging.
new rulerequirementconfiguration/common.md#integerSHOULD added: If an implementation chooses to support an integer-valued configuration source, it SHOULD support non-negative values between 0 and 2³¹ − 1 (inclusive).
new rulerequirementconfiguration/common.md#integerMAY added: Individual SDKs MAY choose to support a larger range of values.
new rulerequirementconfiguration/common.md#numericSHOULD added: For sources accepting a numeric value, if the user provides a value which is outside the valid range for the configuration item, the implementation SHOULD generate a warning and gracefully ignore the setting, i.e., trea...
new rulerequirementconfiguration/common.md#numericSHOULD NOT added: 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 tre...
new rulerequirementconfiguration/common.md#opentelemetry-common-configuration-specificationMAY added: Implementations MAY choose to allow configuration via any configuration source in this specification, but are not required to.
new rulerequirementconfiguration/common.md#opentelemetry-common-configuration-specificationSHOULD added: If they do, they SHOULD follow the guidance listed in this document.
new rulerequirementconfiguration/common.md#timeoutSHOULD added: Implementations SHOULD interpret timeout zero values (i.e. 0 indicating 0 milliseconds) as no limit (i.e. infinite).
new rulerequirementconfiguration/common.md#timeoutMAY added: In practice, implementations MAY treat no limit as "a very long time" and substitute a very large duration ( e.g. the maximum milliseconds representable by a 32-bit integer).
new rulerequirementconfiguration/sdk-environment-variables.md#opentelemetry-environment-variable-specificationSHOULD added: They SHOULD also follow the common configuration specification.
new rulerequirementmetrics/sdk.md#instrument-enabledMUST added: The instrument Enabled MUST return false when either:
new rulerequirementsdk_exporters/zipkin.md#opentelemetry-to-zipkin-transformationMUST added: Existing stable Zipkin exporters MUST > continue to be supported for at least one year after the artifact is deprecated, > following the SDK stability guarantees. > Implementing a Zipkin exporter is not required for new...

Editorial29

removedsectionconfiguration/data-model.md#stability-definitionSection "Stability definition" removed.
rule droppedrequirementconfiguration/sdk-environment-variables.md#enumMAY removed: For variables which accept a known value out of a set, i.e., an enum value, implementations MAY support additional values not listed here.
rule droppedrequirementconfiguration/sdk-environment-variables.md#enumSHOULD removed: When reporting configuration errors, implementations SHOULD display the original user-provided value to aid debugging.
rule droppedrequirementconfiguration/sdk-environment-variables.md#integerSHOULD removed: If an implementation chooses to support an integer-valued environment variable, it SHOULD support non-negative values between 0 and 2³¹ − 1 (inclusive).
rule droppedrequirementconfiguration/sdk-environment-variables.md#integerMAY removed: Individual SDKs MAY choose to support a larger range of values.
rule droppedrequirementconfiguration/sdk-environment-variables.md#numericSHOULD NOT removed: 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 tre...
rule droppedrequirementconfiguration/sdk-environment-variables.md#timeoutSHOULD removed: Implementations SHOULD interpret timeout zero values (i.e. 0 indicating 0 milliseconds) as no limit (i.e. infinite).
rule droppedrequirementconfiguration/sdk-environment-variables.md#timeoutMAY removed: In practice, implementations MAY treat no limit as "a very long time" and substitute a very large duration ( e.g. the maximum milliseconds representable by a 32-bit integer).
new rulerequirementmetrics/sdk.md#instrument-enabledMAY added: It MAY return false to support additional optimizations and features.
rewordedrequirementbaggage/api.md#conflict-resolutionMUST reworded: If a new name/value pair is added and its name is the same as an existing name, then the new pair MUST take precedence.
rewordedrequirementconfiguration/sdk-environment-variables.md#enumMUST reworded: For sources 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.
rewordedrequirementconfiguration/sdk-environment-variables.md#numericSHOULD reworded: For variables accepting a numeric value, if the user provides a value the implementation cannot parse, the implementation SHOULD generate a warning and gracefully ignore the setting, i.e., treat them...
rewordedrequirementconfiguration/sdk-environment-variables.md#opentelemetry-environment-variable-specificationSHOULD reworded: If they do, they SHOULD use the names and value parsing behavior specified in this document.
rewordedrequirementspecification/document-status.md#maturity-levelsMAY reworded: 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.
rewordedrequirementspecification/document-status.md#maturity-levelsMUST reworded: They also MUST communicate in which version they will be removed. | | Unmaintained | A component identified as unmaintained does not have an active code owner.
rewordedrequirementmetrics/api.md#general-operationsSHOULD reworded: All synchronous instruments SHOULD provide functions to:
rewordedrequirementresource/data-model.md#resource-data-modelMUST reworded: | Field | Type | Description | | ----- | ---- | ----------- | | Entities | set\<Entity\> | Defines the set of Entities associated with this resource.<p>Entity is defined here | | Attributes | map\<st...
rewordedrequirementresource/README.md#navigationSHOULD reworded: > [!TIP] > Observability signals SHOULD be actionable.
rewordedrequirementsdk_exporters/zipkin.md#service-nameMUST NOT reworded: Note that the attribute service.namespace MUST NOT be used for the Zipkin service name and should be sent as a Zipkin tag.
rewordedrequirementsdk_exporters/zipkin.md#statusMUST NOT reworded: MUST NOT be set if the code is UNSET. | | Description | error | Description of the Status.
rewordedrequirementspecification/versioning-and-stability.md#version-numbersMAY reworded: Each contrib package MAY have its own version number.
addeddocumentconfiguration/common.mdNew document: OpenTelemetry Common Configuration Specification (Stable).
addedsectionconfiguration/data-model.md#versioning-policy-and-stability-guaranteesNew section "Versioning policy and stability guarantees".
addedsectionconfiguration/sdk-environment-variables.md#type-specific-guidanceNew section "Type-specific guidance".
addedsectiontrace/sdk.md#alwaysrecordNew section "AlwaysRecord".
rewrittensectionconfiguration/sdk-environment-variables.md#enum"Enum" substantially rewritten (616 to 353 characters).
rewrittensectionconfiguration/sdk-environment-variables.md#numeric"Numeric" substantially rewritten (1390 to 594 characters).
rewrittensectionlogs/data-model.md#field-severitynumber"Field: SeverityNumber" substantially rewritten (1204 to 1624 characters).
rewrittensectionsdk_exporters/zipkin.md#opentelemetry-to-zipkin-transformation"OpenTelemetry to Zipkin Transformation" substantially rewritten (474 to 1216 characters).