Specificationv1.58.0

22 Jun 2026since v1.57.0

0 breaking44 notable60 editorial

From the upstream release notes

Clarify that environment variable propagation carriers normalize requested
Specify that environment variable propagation carriers only read and return
Specify that an empty environment variable propagation name is non-normalized
Remove duplicate information from and extend Profiles documentation (README.md, pprof.md).
Add specification for communicating entity information as structured log events.
Add an in-development SDK self-observability
Clarify non-OTLP representation guidance for nested AnyValue values in
Add in-development guidance recommending a JSON object as the string
Add in-development guidance recommending a JSON object as the string
Deprecate OpenCensus compatibility requirements in the specification.

Read the full release notes

Notable44

rule droppedrequirementcompatibility/prometheus_and_openmetrics.md#histograms-1MUST removed: The final bucket metric MUST have an +Inf threshold.
stabilitydocumentcompatibility/opencensus.mdStatus changed from Stable to Deprecated.
stabilitydocumentprofiles/mappings.mdStatus changed from Development to Alpha.
stabilitydocumentprofiles/pprof.mdStatus changed from Development to Alpha.
stabilitydocumentprofiles/README.mdStatus changed from Unspecified to Alpha.
new rulerequirementcommon/README.md#arraysSHOULD added: Array elements SHOULD be represented as JSON values using the following rules:
new rulerequirementcommon/README.md#attribute-collection-representation-for-non-otlpRECOMMENDED added: For non-OTLP protocols that need to represent an Attribute Collection as a string, the RECOMMENDED form is a JSON object.
new rulerequirementcommon/README.md#attribute-collection-representation-for-non-otlpSHOULD added: Each attribute key SHOULD be represented as a JSON object member name.
new rulerequirementcommon/README.md#attribute-collection-representation-for-non-otlpSHOULD added: Each attribute value SHOULD be represented as the corresponding JSON object member value and follow the encoding rules defined in AnyValue representation for non-OTLP protocols, as it would be represented as an element ...
new rulerequirementcommon/README.md#attribute-representation-for-non-otlpRECOMMENDED added: For non-OTLP protocols that need to represent a single Attribute as a string, the RECOMMENDED form is a JSON object containing a single name/value pair (member).
new rulerequirementcommon/README.md#attribute-representation-for-non-otlpSHOULD added: The attribute key SHOULD be represented as a JSON object member name.
new rulerequirementcommon/README.md#attribute-representation-for-non-otlpSHOULD added: The attribute value SHOULD be represented as a JSON object member value and follow the encoding rules defined in AnyValue representation for non-OTLP protocols, as it would be represented as an element in an array and a...
new rulerequirementcommon/README.md#mapsSHOULD added: Map keys SHOULD be represented as JSON string member names.
new rulerequirementcommon/README.md#mapsSHOULD added: Map values SHOULD be represented using the same rules as array elements.
new rulerequirementcompatibility/prometheus_and_openmetrics.md#histograms-as-prometheus-histogramsMUST added: When converting to a Prometheus Histogram, an OpenTelemetry Histogram MUST be converted following the rules below:
new rulerequirementcompatibility/prometheus_and_openmetrics.md#histograms-as-prometheus-nhcbMUST added: When converting to a Prometheus NHCB, only a single NHCB metric MUST be created:
new rulerequirementcompatibility/prometheus_and_openmetrics.md#histograms-as-prometheus-nhcbMUST added: The flavor of the NHCB MUST be integer counter.
new rulerequirementcompatibility/prometheus_and_openmetrics.md#histograms-as-prometheus-nhcbMUST added: The ResetHint in the NHCB MUST be set to UNKNOWN.
new rulerequirementcompatibility/prometheus_and_openmetrics.md#histograms-as-prometheus-nhcbMUST added: The Schema in the NHCB MUST be set to -53.
new rulerequirementcompatibility/prometheus_and_openmetrics.md#histograms-as-prometheus-nhcbMUST NOT added: The implicit +Inf upper bound MUST NOT be written into CustomValues; it is represented by the overflow bucket at index len(CustomValues).
new rulerequirementcompatibility/prometheus_and_openmetrics.md#histograms-as-prometheus-nhcbMUST added: All fields of the NHCB that are not explicitly referenced here MUST be set to their zero value, such as zero threshold, zero count, negative spans, negative deltas, etc.
new rulerequirementcompatibility/prometheus_and_openmetrics.md#histograms-as-prometheus-nhcbMUST added: If the NoRecordedValue flag is set to true, the NHCB MUST be marked as stale:
new rulerequirementcompatibility/prometheus_and_openmetrics.md#histograms-as-prometheus-nhcbMUST added: The Native Histogram Sum MUST be set to the Stale NaN value.
new rulerequirementcompatibility/prometheus_and_openmetrics.md#histograms-as-prometheus-nhcbMUST added: The Native Histogram Count MUST be set to zero.
new rulerequirementcompatibility/prometheus_and_openmetrics.md#histograms-as-prometheus-nhcbMUST added: PositiveSpans and PositiveDeltas MUST be left empty.
new rulerequirementcompatibility/prometheus_and_openmetrics.md#histograms-as-prometheus-nhcbMUST added: Non-zero bucket counts MUST be converted into PositiveDeltas.
new rulerequirementcompatibility/prometheus_and_openmetrics.md#summaries-1MUST added: The quantile label value MUST be the stringified floating point value of each quantile (between 0.0 and 1.0), starting from lowest to highest, and all being non-negative.
new rulerequirementcontext/env-carriers.md#key-name-normalizationMUST added: To normalize a key name, implementations MUST:
new rulerequirementcontext/env-carriers.md#key-name-normalizationMUST added: Set MUST write values using the normalized form of the key provided by the propagator.
new rulerequirementcontext/env-carriers.md#key-name-normalizationMUST added: Get MUST normalize the key requested by the propagator and MUST use the normalized key name to read from the carrier.
new rulerequirementcontext/env-carriers.md#key-name-normalizationMUST added: Keys MUST return only key names that are already normalized.
new rulerequirementcontext/env-carriers.md#key-name-normalizationMUST added: For example, if a propagator requests the key x-b3-traceid, the environment-specific Get operation MUST normalize the requested key to XB3TRACEID and read the XB3TRACEID environment variable.
new rulerequirementcontext/env-carriers.md#key-name-normalizationMUST NOT added: It MUST NOT read a non-normalized environment variable named x-b3-traceid, even though that name normalizes to XB3TRACEID.
new rulerequiremententities/entity-events.md#entity-delete-eventMUST added: Recipients of entity signals MUST be prepared to handle this situation by expiring entities that are no longer seeing Entity State events reported.
new rulerequiremententities/entity-events.md#entity-delete-eventMUST added: Recipients MUST also be prepared to receive an Entity Delete event out of order, for example, before the last Entity State event.
new rulerequiremententities/entity-events.md#entity-state-eventMUST added: MUST not change during the lifetime of the entity.
new rulerequiremententities/entity-events.md#entity-state-eventMUST added: The map MUST contain at least one attribute.
new rulerequiremententities/entity-events.md#entity-state-eventMUST added: Keys and values MUST be strings.
new rulerequiremententities/entity-events.md#entity-state-eventMUST added: When absent, MUST be treated as an empty map.
new rulerequiremententities/entity-events.md#entity-state-eventMUST added: When absent, MUST be treated as an empty array. | | entity.report.interval | int64 (seconds) | The reporting period for this entity.
new rulerequiremententities/entity-events.md#entity-state-eventMUST added: MUST be a non-negative value when present.
new rulerequirementlogs/sdk.md#self-observabilitySHOULD added: The Logs SDK SHOULD support SDK self-observability.
new rulerequirementprofiles/README.md#design-goalsMUST added: Correlation with other signals: Profiles MUST be linkable to logs, metrics and traces through shared resource context and, where applicable, direct trace/span references.
new rulerequirementtrace/sdk.md#self-observabilitySHOULD added: The Tracing SDK SHOULD support SDK self-observability.

Editorial60

removedsectionsdk_exporters/prometheus.md#resource-attributes-as-metric-attributesSection "Resource Attributes as Metric Attributes" removed.
rule droppedrequirementcommon/README.md#arraysSHOULD removed: Nested byte arrays SHOULD be represented as Base64-encoded JSON strings.
rule droppedrequirementcommon/README.md#arraysSHOULD removed: Nested empty values SHOULD be represented as JSON null.
rule droppedrequirementcommon/README.md#mapsSHOULD removed: Nested byte arrays SHOULD be represented as Base64-encoded JSON strings.
rule droppedrequirementcommon/README.md#mapsSHOULD removed: Nested empty values SHOULD be represented as JSON null.
rule droppedrequirementcommon/README.md#mapsSHOULD removed: The special floating point values NaN and Infinity SHOULD be represented as JSON strings "NaN", "Infinity", and "-Infinity".
rule droppedrequirementsdk_exporters/prometheus.md#resource-attributes-as-metric-attributesMAY removed: The option MAY be named resourceconstantlabels.
new rulerequirementcompatibility/opencensus.md#opencensus-compatibilityMAY added: > [!NOTE] > OpenCensus compatibility requirements are deprecated. > Existing OpenCensus shims MAY continue to be supported for backwards > compatibility, but implementing new OpenCensus compatibility is not required > b...
new rulerequirementcompatibility/prometheus_and_openmetrics.md#histograms-as-prometheus-histogramsSHOULD added: If set, StartTimeUnixNano SHOULD be transformed into Prometheus StartTime, following the appropriate format used by each Prometheus protocol.
new rulerequirementcompatibility/prometheus_and_openmetrics.md#histograms-as-prometheus-nhcbSHOULD added: If set, StartTimeUnixNano SHOULD be transformed into Prometheus StartTime, following the appropriate format used by each Prometheus protocol.
new rulerequirementcompatibility/prometheus_and_openmetrics.md#histograms-as-prometheus-nhcbMAY added: Zero-count buckets MAY also be included in PositiveDeltas to extend an enclosing span (rather than creating a gap between spans) and reduce the number of PositiveSpans.
new rulerequirementcompatibility/prometheus_and_openmetrics.md#summaries-1SHOULD NOT added: Explicit timestamps SHOULD NOT be used for pull protocols, such as the Prometheus text exposition format, where Prometheus assigns the scrape timestamp.
new rulerequiremententities/entity-events.md#entity-delete-eventSHOULD added: In this case, recipients SHOULD apply state updates regardless, as each Entity State event represents the full current state of the entity and can be used to update a previously deleted entity record.
new rulerequiremententities/entity-events.md#entity-state-eventSHOULD added: SHOULD follow OpenTelemetry semantic conventions for attribute names. |
new rulerequiremententities/entity-events.md#entity-state-eventSHOULD added: SHOULD follow OpenTelemetry semantic conventions for attributes. | | entity.relationships | array of maps | Relationships to other entities.
new rulerequiremententities/entity-events.md#entity-state-eventSHOULD added: Implementations SHOULD emit Entity State events whenever entity descriptive attributes change, and periodically based on the entity.report.interval value to indicate the entity still exists.
new rulerequiremententities/entity-events.md#entity-state-eventSHOULD added: Implementations SHOULD also emit Entity Delete events when entities are removed.
new rulerequiremententities/entity-events.md#relationship-lifecycleSHOULD added: Backends SHOULD handle this accordingly.
new rulerequiremententities/entity-events.md#relationship-placementSHOULD added: When choosing which entity should contain a relationship in its entity.relationships array, implementations SHOULD prefer placing relationships on the entity type with the shorter lifespan or higher churn rate.
new rulerequiremententities/entity-events.md#relationship-placementSHOULD added: Semantic conventions SHOULD provide guidance on relationship placement for common entity types.
new rulerequiremententities/entity-events.md#standard-relationship-typesSHOULD added: Standard relationship types SHOULD be defined in OpenTelemetry semantic conventions.
new rulerequiremententities/entity-events.md#standard-relationship-typesMAY added: Custom relationship types MAY be defined to represent domain-specific relationships.
new rulerequirementsdk_exporters/prometheus.md#resource-attributes-as-metric-labelsSHOULD added: The option SHOULD be named resourceconstant_labels.
new rulerequirementmetrics/sdk.md#self-observabilitySHOULD added: The Metrics SDK SHOULD support SDK self-observability.
new rulerequirementprofiles/README.md#data-formatMAY added: Span context references: Samples MAY include a Link (span ID and trace ID), enabling direct linking between a profile sample and the trace/span during which it was captured.
new rulerequirementspecification/self-observability.md#sdk-self-observability-metricsSHOULD added: SDKs that implement self-observability metrics SHOULD follow these conventions.
new rulerequirementspecification/self-observability.md#self-observabilitySHOULD added: OpenTelemetry SDKs SHOULD emit self-observability ("internal") telemetry about their own behavior (for example, metrics, logs, and other signals describing the state of processors, exporters, and metric readers) to help...
rewordedrequirementcommon/README.md#arraysSHOULD reworded: Integers and floating point numbers as JSON numbers, except that the special floating point values NaN and Infinity SHOULD be represented as JSON strings "NaN", "Infinity", and "-Infinity",
rewordedrequirementcompatibility/prometheus_and_openmetrics.md#histograms-1MUST reworded: An OpenTelemetry Histogram with a cumulative aggregation temporality MUST be converted to a Prometheus Histogram by default.
rewordedrequirementcompatibility/prometheus_and_openmetrics.md#histograms-1MUST reworded: OpenTelemetry Histograms with Delta aggregation temporality MAY be aggregated into a Cumulative aggregation temporality and follow the logic below, or MUST be dropped.
rewordedrequirementcompatibility/prometheus_and_openmetrics.md#summaries-1MUST reworded: An OpenTelemetry Summary MUST be converted to a Prometheus Summary as follows:
rewordedrequirementcontext/env-carriers.md#key-name-normalizationMUST reworded: Language implementations MUST ensure that environment variable Get, Set, and Keys operations use normalized key names for context propagation.
movedrequirementcompatibility/prometheus_and_openmetrics.md#histograms-as-prometheus-histogramsSHOULD moved here from "histograms-1": If the Prometheus protocol only supports a single exemplar per-bucket, the latest exemplar that falls into each bucket SHOULD be converted.
movedrequirementsdk_exporters/prometheus.md#resource-attributes-as-metric-labelsMAY moved here from "resource-attributes-as-metric-attributes": A Prometheus Exporter MAY offer configuration to add resource attributes as metric labels.
movedrequirementsdk_exporters/prometheus.md#resource-attributes-as-metric-labelsMUST NOT moved here from "resource-attributes-as-metric-attributes": By default, it MUST NOT add any resource attributes as metric labels.
movedrequirementsdk_exporters/prometheus.md#resource-attributes-as-metric-labelsSHOULD moved here from "resource-attributes-as-metric-attributes": The configuration SHOULD allow the user to select resource attributes to include or exclude.
movedrequirementsdk_exporters/prometheus.md#resource-attributes-as-metric-labelsMUST NOT moved here from "resource-attributes-as-metric-attributes": Copied Resource attributes MUST NOT be excluded from the targetinfo metric.
addedsectioncommon/README.md#attribute-collection-representation-for-non-otlpNew section "Attribute Collection representation for non-OTLP".
addedsectioncommon/README.md#attribute-representation-for-non-otlpNew section "Attribute representation for non-OTLP".
addedsectioncompatibility/prometheus_and_openmetrics.md#histograms-as-prometheus-histogramsNew section "Histograms as Prometheus Histograms".
addedsectioncompatibility/prometheus_and_openmetrics.md#histograms-as-prometheus-nhcbNew section "Histograms as Prometheus NHCB".
addeddocumententities/entity-events.mdNew document: Entity Events (Development).
addedsectionlogs/sdk.md#self-observabilityNew section "Self-observability".
addedsectionsdk_exporters/prometheus.md#resource-attributes-as-metric-labelsNew section "Resource Attributes as Metric Labels".
addedsectionmetrics/sdk.md#self-observabilityNew section "Self-observability".
addeddocumentprofiles/data-format.mdNew document: Profiles Data Format (Development).
addedsectionprofiles/README.md#data-formatNew section "Data Format".
addedsectionprofiles/README.md#design-goalsNew section "Design goals".
addedsectionprofiles/README.md#referencesNew section "References".
addedsectionprofiles/README.md#specificationsNew section "Specifications".
addeddocumentspecification/self-observability-supplementary-guidelines.mdNew document: Self-Observability Supplementary Guidelines (Unspecified).
addeddocumentspecification/self-observability.mdNew document: Self-Observability (Development).
addedsectiontrace/sdk.md#self-observabilityNew section "Self-observability".
rewrittensectioncommon/README.md#arrays"Arrays" substantially rewritten (468 to 1245 characters).
rewrittensectioncompatibility/opencensus.md#opencensus-compatibility"OpenCensus Compatibility" substantially rewritten (246 to 644 characters).
rewrittensectioncompatibility/prometheus_and_openmetrics.md#histograms-1"Histograms" substantially rewritten (1624 to 651 characters).
rewrittensectioncontext/env-carriers.md#key-name-normalization"Key Name Normalization" substantially rewritten (522 to 1848 characters).
rewrittensectioncontext/env-carriers.md#supplementary-guidelines"Supplementary Guidelines" substantially rewritten (1785 to 2377 characters).
rewrittensectionprofiles/pprof.md#compatibility"Compatibility" substantially rewritten (369 to 576 characters).
rewrittensectionprofiles/README.md#overview"Overview" substantially rewritten (1241 to 458 characters).