Specificationv1.62.0

22 Oct 2026since v1.61.0

22 breaking28 notable45 editorial

From the upstream release notes

Add Sampler.Shutdown operation.
Clarify that calls to the Development SpanProcessor.OnEnding method are not
Specify that Shutdown of the periodic exporting MetricReader MUST include
Add systemd-journald example mapping to the logs data model appendix and align syslog mapping.
Update resource detectors to generate entities and indicate resource detectors should be entity-aware
Add in-development entity-resource startup specification.
Remove OTEL_ENTITIES from general env var configuration spec.
Stabilize Attribute and Attribute Collection representation for non-OTLP.
Clarify that the OTLP exporter timeout bounds the entire batch export,
Stabilize Prometheus Unknown-typed metric transformation.

Read the full release notes

Breaking22

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

new rulerequirementconfiguration/sdk-environment-variables.md#booleanMUST NOT added: Renaming a Boolean environment variable MUST NOT happen without a major version upgrade.
new rulerequirementprotocol/exporter.md#configuration-optionsMUST NOT added: The timeout starts when the batch export begins and MUST NOT be reset for each request attempt.
new rulerequirementprotocol/exporter.md#retryMUST added: Each request attempt and wait between retries MUST be bounded by the remaining time allowed by the exporter timeout.
new rulerequirementprotocol/exporter.md#retryMUST added: Any earlier deadline provided by the caller (for example, a span processor, log processor, or metric reader) MUST take precedence.
new rulerequirementprotocol/exporter.md#retryMUST added: When either limit is reached, the exporter MUST stop attempting to export the batch, including any waits between retries, and complete the export with a failure result.
new rulerequirementresource/sdk.md#entitiesMUST NOT added: MUST NOT change during the lifetime of the entity.
new rulerequirementresource/sdk.md#entitiesMUST added: MUST contain at least one attribute.
new rulerequirementresource/sdk.md#entitiesMUST added: The identifying and descriptive attributes of all entities in a Resource MUST be included in the Resource's attributes.
new rulerequirementresource/sdk.md#merge-behavior-with-entitiesMUST added: When invoking the Merging An Entity into a Resource algorithm, the old resource's entities MUST be used as the initial entity set E, and the updating resource's entities MUST be processed as the incoming merge list.
new rulerequirementresource/sdk.md#merge-behavior-with-entitiesMUST added: For raw attribute merging, the updating resource's raw attributes MUST be processed as the higher-priority source in the algorithm's raw-attribute merge step.
new rulerequirementresource/sdk.md#resource-detectorMUST added: The entity MUST be included in the Resource immediately with any already-resolved attributes.
new rulerequirementresource/sdk.md#resource-detectorMUST added: As attributes resolve, the Resource Provider MUST construct a new Resource reflecting the resolved values.
new rulerequirementresource/sdk.md#resource-detectorMUST added: Identifying attributes MUST all be resolved before the first export.
new rulerequirementresource/sdk.md#resource-providerMUST added: The Resource Provider MUST:
new rulerequirementresource/sdk.md#resource-providerMUST added: When descriptive attributes are detected asynchronously, the priority for merging MUST be determined by the configured order of the resource detectors, not by the order in which asynchronous results resolve.
new rulerequirementtrace/sdk.md#concurrency-requirementsMUST added: Shutdown MUST be safe to be called concurrently with itself and the other Sampler methods.
new rulerequirementtrace/sdk.md#shutdown-1MUST added: Implementations MUST ensure these calls remain safe while shutdown releases resources.
new rulerequirementspecification/versioning-and-stability.md#security-related-changesMUST added: Changes under this exception MUST address an identified, concrete security risk and MUST be limited to what is necessary to mitigate that risk.
new rulerequirementspecification/versioning-and-stability.md#security-related-changesMUST added: They MUST preserve the existing source and ABI compatibility guarantees, including compatibility of SDK plugin interfaces, and MUST comply with Error handling.
new rulerequirementspecification/versioning-and-stability.md#security-related-changesMUST NOT added: The exception MUST NOT be used to remove or rename public APIs, change their signatures, rename or remove configuration parameters, redefine semantic conventions, bypass signal deprecation or removal requirements, or ma...
new rulerequirementspecification/versioning-and-stability.md#security-related-changesMUST added: Release notes MUST identify the affected behavior and any affected configuration settings, describe the previous and new behavior (including any newly rejected inputs or configuration values and any truncated or dropped...
new rulerequirementspecification/versioning-and-stability.md#security-related-changesMUST added: Release notes MUST describe any available migration path and the security implications of restoring the previous behavior.

Notable28

removedsectionresource/sdk.md#detecting-resource-information-from-the-environmentSection "Detecting resource information from the environment" removed.
new rulerequirementconfiguration/sdk.md#createSHOULD added: warn and skip: Create SHOULD generate a warning identifying the unrecognized name and gracefully ignore the reference.
new rulerequiremententities/data-model.md#entity-data-modelMUST added: This field is required and MUST not be empty for valid entities. | | Schema URL | string | Identifies the schema version for the entity's attributes.
new rulerequirementmetrics/sdk.md#shutdown-2MUST added: Shutdown MUST include the effects of ForceFlush.
new rulerequirementresource/sdk.md#entitiesSHOULD added: SHOULD be detected synchronously during SDK initialization.
new rulerequirementresource/sdk.md#entitiesMAY added: MAY change over the lifetime of the entity.
new rulerequirementresource/sdk.md#entitiesMAY added: A Resource MAY contain zero or more entities.
new rulerequirementresource/sdk.md#entity-aware-resource-detectorsSHOULD added: Resource detectors SHOULD produce resources with entities attached.
new rulerequirementresource/sdk.md#resource-detectorSHOULD added: Empty Schema URL SHOULD be used if the detector does not populate the resource with any known attributes that have a semantic convention or if the detector does not know what attributes it will populate (e.g. the detect...
new rulerequirementresource/sdk.md#resource-detectorMAY added: Resource detector packages MAY also return (Development) Entities alongside resource attributes.
new rulerequirementresource/sdk.md#resource-detectorSHOULD added: Entity-aware resource detectors SHOULD detect entity attributes synchronously.
new rulerequirementresource/sdk.md#resource-detectorMAY added: Entity attributes MAY be detected asynchronously (e.g. via a future or promise that resolves after initialization).
new rulerequirementresource/sdk.md#resource-detectorMAY added: Unresolved attributes MAY be represented as asynchronous values.
new rulerequirementresource/sdk.md#resource-providerMAY added: Detectors MAY run concurrently.
new rulerequirementtrace/sdk.md#shutdownSHOULD added: Shutdown SHOULD also invoke Shutdown on the configured Sampler, if supported.
new rulerequirementtrace/sdk.md#shutdown-1SHOULD added: The Sampler interface SHOULD provide a Shutdown method.
new rulerequirementtrace/sdk.md#shutdown-1SHOULD added: Samplers that delegate to other samplers, such as ParentBased and AlwaysRecord, SHOULD invoke Shutdown on each delegate that supports it.
new rulerequirementtrace/sdk.md#shutdown-1SHOULD NOT added: Repeated or concurrent calls to Shutdown SHOULD NOT repeat cleanup.
new rulerequirementtrace/sdk.md#shutdown-1SHOULD NOT added: Callers, including TracerProvider, SHOULD NOT call ShouldSample after Shutdown begins.
new rulerequirementtrace/sdk.md#shutdown-1SHOULD added: If such a call occurs, implementations SHOULD return DROP without executing their sampling logic.
new rulerequirementtrace/sdk.md#shutdown-1MAY added: Samplers that always return a static sampling decision MAY continue returning that decision.
new rulerequirementtrace/sdk.md#shutdown-1MAY added: Calls to ShouldSample already in progress MAY complete with their normal result.
new rulerequirementtrace/sdk.md#shutdown-2SHOULD added: Shutdown SHOULD be called only once for each SpanProcessor instance.
new rulerequirementtrace/sdk.md#shutdown-2SHOULD added: Shutdown SHOULD provide a way to let the caller know whether it succeeded, failed or timed out.
new rulerequirementtrace/sdk.md#shutdown-2SHOULD added: Shutdown SHOULD complete or abort within some timeout.
new rulerequirementspecification/versioning-and-stability.md#security-related-changesMAY added: Stable SDK and Contrib components MAY make backward-incompatible behavioral changes, change configuration defaults, or restrict supported configuration values without incrementing the major version when necessary to add...
new rulerequirementspecification/versioning-and-stability.md#security-related-changesMAY added: Such changes MAY be released as security fixes in a patch release, subject to the support requirements in this document.
new rulerequirementspecification/versioning-and-stability.md#security-related-changesSHOULD added: Where safe and feasible, implementations SHOULD provide a configuration override or other migration path.

Editorial45

removedsectionresource/data-model.md#merging-entities-into-a-resourceSection "Merging Entities into a Resource" removed.
new rulerequirementspecification/telemetry-stability.md#telemetry-stabilityMAY added: Changes in emitted telemetry that satisfy the security-related changes exception MAY be made without incrementing the major version, even when the stability rules below would otherwise prohibit them.
rewordedrequirementconfiguration/sdk-environment-variables.md#booleanMUST NOT reworded: Changing its default value MUST NOT happen without a major version upgrade, except as permitted by Security-related changes.
rewordedrequirementconfiguration/sdk-environment-variables.md#general-sdk-configurationMUST reworded: This setting has no effect on propagators configured through the OTELPROPAGATORS variable. | | OTELRESOURCEATTRIBUTES | Key-value pairs to be used as resource attributes | See Resource semantic conve...
rewordedrequirementconfiguration/sdk-environment-variables.md#general-sdk-configurationMUST reworded: Invalid or unrecognized input MUST be logged and MUST be otherwise ignored, i.e. the implementation MUST behave as if OTELTRACESSAMPLERARG is not set. |
rewordedrequirementconfiguration/sdk.md#createMUST reworded: If encountering a reference to an SDK plugin component which is not built-in to the SDK, and a PluginComponentProvider is registered with the corresponding type and name used to register, Creat...
rewordedrequirementconfiguration/sdk.md#createSHOULD reworded: error: Create SHOULD return an error.
rewordedrequiremententities/data-model.md#entity-data-modelMUST reworded: MAY be empty. | | ID | map<string, attribute value> | Attributes that identify the entity.<p>MUST not change during the lifetime of the entity.
rewordedrequirementresource/sdk.md#resource-detector-nameSHOULD reworded: Names SHOULD be snakecase and consist of lowercase alphanumeric and `` characters, which ensures they conform to declarative configuration property name requirements.
rewordedrequirementresource/sdk.md#resource-detector-nameSHOULD reworded: Resource detector names SHOULD reflect the root namespace of attributes and entities they populate.
rewordedrequirementresource/sdk.md#resource-detector-nameSHOULD reworded: Populates service.name from the OTELSERVICENAME environment variable and SHOULD fall back to language- or platform-specific sources (for example spring.application.name, a JAR manifest, or a Comp...
rewordedrequirementresource/sdk.md#retrieve-attributesMUST reworded: When entities are present for the Resource, this list MUST include all attributes, including those associated with entities.
rewordedrequirementtrace/sdk.md#shutdown-1SHOULD reworded: Shutdown SHOULD be called only once for each Sampler instance.
rewordedrequirementspecification/versioning-and-stability.md#contrib-stabilitySHOULD reworded: Public portions of contrib packages (constructors, configuration, interfaces) SHOULD remain backward compatible, except as permitted by Security-related changes.
rewordedrequirementspecification/versioning-and-stability.md#design-goalsMUST reworded: Except as permitted by Security-related changes, it MUST always be possible to upgrade to the latest minor version of the OpenTelemetry SDK, without creating compilation or runtime errors.
rewordedrequirementspecification/versioning-and-stability.md#sdk-stabilityMUST reworded: Public portions of SDK packages MUST remain backward compatible, except as permitted by Security-related changes.
rewordedrequirementspecification/versioning-and-stability.md#version-numbersMUST reworded: OpenTelemetry clients MUST follow Semantic Versioning 2.0.0, with the following clarifications and the explicit exception for Security-related changes.
movedrequirementmetrics/sdk.md#shutdown-3SHOULD moved here from "shutdown-2": Shutdown SHOULD be called only once for each MetricExporter instance.
movedrequirementmetrics/sdk.md#shutdown-3SHOULD NOT moved here from "shutdown-2": Shutdown SHOULD NOT block indefinitely (e.g. if it attempts to flush the data and the destination is unavailable).
movedrequirementmetrics/sdk.md#shutdown-3MAY moved here from "shutdown-2": OpenTelemetry SDK authors MAY decide if they want to make the shutdown timeout configurable.
movedrequirementresource/sdk.md#entitiesMAY moved here from "detecting-resource-information-from-the-environment": MAY be empty.
movedrequirementresource/sdk.md#resource-detectorMUST moved here from "detecting-resource-information-from-the-environment": Custom resource detectors related to generic platforms (e.g. Docker, Kubernetes) or vendor specific environments (e.g. EKS, AKS, GKE) MUST be implemented as packages separate from the SDK.
movedrequirementresource/sdk.md#resource-detectorMUST moved here from "detecting-resource-information-from-the-environment": Resource detector packages MUST provide a method that returns a resource.
movedrequirementresource/sdk.md#resource-detectorMAY moved here from "detecting-resource-information-from-the-environment": Resource detector packages MAY detect resource information from multiple possible sources and merge the result using the Merge operation described above.
movedrequirementresource/sdk.md#resource-detectorMUST NOT moved here from "detecting-resource-information-from-the-environment": Note the failure to detect any resource information MUST NOT be considered an error, whereas an error that occurs during an attempt to detect resource information SHOULD be considered an error.
movedrequirementresource/sdk.md#resource-detectorMUST moved here from "detecting-resource-information-from-the-environment": Resource detectors that populate resource attributes according to OpenTelemetry semantic conventions MUST ensure that the resource has a Schema URL set to a value that matches the semantic convention...
movedrequirementresource/sdk.md#resource-detectorMUST moved here from "detecting-resource-information-from-the-environment": If multiple detectors are combined and the detectors use different non-empty Schema URL it MUST be an error since it is impossible to merge such resources.
movedrequirementtrace/sdk.md#shutdown-2SHOULD moved here from "shutdown-1": SDKs SHOULD ignore these calls gracefully, if possible.
movedrequirementtrace/sdk.md#shutdown-2MUST moved here from "shutdown-1": Shutdown MUST include the effects of ForceFlush.
addedsectionlogs/data-model-appendix.md#systemd-journaldNew section "systemd-journald".
addedsectionmetrics/sdk.md#shutdown-3New section "Shutdown".
addedsectionresource/data-model.md#merging-an-entity-into-a-resourceNew section "Merging An Entity into a Resource".
addedsectionresource/data-model.md#merging-resource-attributes-into-a-resourceNew section "Merging Resource Attributes into a Resource".
addedsectionresource/sdk.md#entitiesNew section "Entities".
addedsectionresource/sdk.md#entity-aware-resource-detectorsNew section "Entity-aware resource detectors".
addedsectionresource/sdk.md#resource-detectorNew section "Resource Detector".
addedsectionresource/sdk.md#resource-providerNew section "Resource Provider".
addedsectiontrace/sdk.md#shutdown-3New section "Shutdown()".
addedsectionspecification/versioning-and-stability.md#security-related-changesNew section "Security-related changes".
rewrittensectionmetrics/sdk.md#shutdown-2"Shutdown" substantially rewritten (534 to 69 characters).
rewrittensectionprotocol/exporter.md#retry"Retry" substantially rewritten (228 to 646 characters).
rewrittensectionresource/sdk.md#merge-behavior-with-entities"Merge behavior with entities" substantially rewritten (470 to 1016 characters).
rewrittensectionspecification/telemetry-stability.md#telemetry-stability"Telemetry Stability" substantially rewritten (624 to 1146 characters).
rewrittensectiontrace/sdk.md#shutdown-1"Shutdown" substantially rewritten (785 to 1255 characters).
rewrittensectiontrace/sdk.md#shutdown-2"Shutdown()" substantially rewritten (517 to 815 characters).