Specificationv1.48.0
since v1.47.00 breaking21 notable14 editorial
From the upstream release notes
- Improve concurrency safety description of LogRecordProcessor.OnEmit.
- Clarify that SeverityNumber values are used when comparing severities.
- Mention entity references in the stability guarantees.
- Clarify protocol defaults on specification.
- Flexibilie escaping of characters that are discouraged by Prometheus Conventions in Prometheus exporters.
- Flexibilize addition of unit/type related suffixes in Prometheus exporters.
- Define the configuration option "Translation Strategies" for Prometheus exporters.
- Define conversion of Prometheus native histograms to OpenTelemetry exponential histograms.
- Clarify what to do when scope attribute conflicts with name, version and schema URL.
- Enum values provided via environment variables SHOULD be interpreted in a case-insensitive manner.
Notable21
- rule droppedrequirementsdk_exporters/prometheus.md#configurationMUST removed: The option MAY be named
without_units, and MUST befalseby default. - rule droppedrequirementsdk_exporters/prometheus.md#configurationMUST removed: The option MAY be named
withouttypesuffix, and MUST befalseby default. - strengthrequirementcompatibility/prometheus_and_openmetrics.md#metric-attributesMUST relaxed to SHOULD: Discouraged characters SHOULD be replace with the `` character.
- strengthrequirementcompatibility/prometheus_and_openmetrics.md#metric-attributesMUST relaxed to SHOULD: Multiple consecutive `
characters SHOULD be replaced with a single` character. - strengthrequirementcompatibility/prometheus_and_openmetrics.md#metric-metadata-1MUST relaxed to SHOULD: Discouraged characters in the metric name SHOULD be replaced with the `` character by default, aiming for compatibility with Prometheus conventions.
- strengthrequirementcompatibility/prometheus_and_openmetrics.md#metric-metadata-1MUST relaxed to SHOULD: Multiple consecutive `
characters SHOULD be replaced with a single_` character. - strengthrequirementcompatibility/prometheus_and_openmetrics.md#metric-metadata-1MUST relaxed to SHOULD: The resulting unit SHOULD be added to the metric as UNIT metadata.
- new rulerequirementcompatibility/prometheus_and_openmetrics.md#instrumentation-scope-1MUST added: Scope attributes with names 'name', 'version', or 'schemaurl' MUST be dropped to avoid conflicts with the already existing
otelscopename,otelscopeversion, andotelscopeschema_urllabels. - new rulerequirementcompatibility/prometheus_and_openmetrics.md#native-histogramsMUST added: A Prometheus Native Histogram with standard (exponential) schema (i.e. schemas -4 to 8) and which are of the integer and counter flavor MUST be converted to an OTLP Exponential Histogram as follows:
- new rulerequirementcompatibility/prometheus_and_openmetrics.md#native-histogramsMUST added: Native histograms of the float or gauge flavors MUST be dropped.
- new rulerequirementcompatibility/prometheus_and_openmetrics.md#native-histogramsMUST added: Native Histograms with
Schemaoutside of the range [-4, 8] MUST be dropped. - new rulerequirementconfiguration/sdk-environment-variables.md#enumSHOULD added: Enum values SHOULD be interpreted in a case-insensitive manner.
- new rulerequirementconfiguration/sdk-environment-variables.md#enumSHOULD added: When reporting configuration errors, implementations SHOULD display the original user-provided value to aid debugging.
- new rulerequirementlogs/data-model.md#comparing-severityMAY added: Special handling MAY be given to
SeverityNumber=0when it is used to represent an unspecified severity. - new rulerequirementlogs/sdk.md#onemitOPTIONAL added: However, it is OPTIONAL for
ReadWriteLogRecordto be concurrent-safe. - new rulerequirementlogs/sdk.md#onemitSHOULD added: To avoid such race conditions, implementations SHOULD recommended to users that a clone of
logRecordbe used for any concurrent processing, such as in a batching processor. - new rulerequirementsdk_exporters/prometheus.md#configurationMUST added: If the Prometheus exporter supports such configuration it MUST be named to something that resembles Prometheus configuration option
translation_strategy, and the translation options MUST be: - new rulerequirementsdk_exporters/prometheus.md#interaction-with-translation-strategyMUST added: Although a Prometheus Exporter MAY be configured with a
translation_strategyfor internal metric processing, the final output format and character escaping MUST follow what the content negotiation process determines b... - new rulerequirementsdk_exporters/prometheus.md#interaction-with-translation-strategyMUST added: The content negotiation requirements MUST take precedence over the configured translation strategy when determining the final output format.
- new rulerequirementsdk_exporters/prometheus.md#interaction-with-translation-strategyMUST added: If configured with
NoTranslationbut the client requestsescaping=underscores, the exporter MUST apply underscore escaping. - new rulerequirementprotocol/exporter.md#configuration-optionsSHOULD added: [4]: The default protocol SHOULD be
http/protobuf, unless there are strong reasons for SDKs to selectgrpcas the default.
Editorial14
- removedsectionconfiguration/sdk.md#config-operationsSection "Config operations" removed.
- rule droppedrequirementsdk_exporters/prometheus.md#configurationMAY removed: A Prometheus Exporter MAY support a configuration option to produce metrics without a unit suffix or UNIT metadata.
- rule droppedrequirementsdk_exporters/prometheus.md#configurationMAY removed: A Prometheus Exporter MAY support a configuration option to produce metrics without a type suffix.
- new rulerequirementcompatibility/prometheus_and_openmetrics.md#metric-metadata-1SHOULD added: A suffix to the metric name SHOULD be added unless the metric name already ends with the unit (before type-specific suffixes).
- new rulerequirementsdk_exporters/prometheus.md#configurationMAY added: A Prometheus Exporter MAY support a configuration option that controls the translation of metric names from OpenTelemetry Naming Conventions to Prometheus Naming conventions.
- rewordedrequirementcompatibility/prometheus_and_openmetrics.md#instrumentation-scope-1MUST reworded: Prometheus exporters MUST by default add the scope name as the
otelscopenamelabel, the scope version as theotelscopeversionlabel, the scope schema URL as theotelscopeschemaurllabel, the sc... - rewordedrequirementcompatibility/prometheus_and_openmetrics.md#metric-metadata-1MUST reworded: The Name of an OTLP metric MUST be added as the Prometheus Metric Name.
- rewordedrequirementcompatibility/prometheus_and_openmetrics.md#sumsMUST reworded: If the metric name for monotonic Sum metric points does not end in a suffix of
totala suffix oftotalSHOULD be added by default, otherwise the name MUST remain unchanged. - movedrequirementconfiguration/sdk.md#sdk-operationsMUST moved here from "config-operations": SDK implementations of configuration MUST provide the following operations.
- addedsectioncompatibility/prometheus_and_openmetrics.md#native-histogramsNew section "Native Histograms".
- addedsectionconfiguration/sdk.md#sdk-operationsNew section "SDK operations".
- addedsectionsdk_exporters/prometheus.md#interaction-with-translation-strategyNew section "Interaction with Translation Strategy".
- rewrittensectioncompatibility/prometheus_and_openmetrics.md#instrumentation-scope-1"Instrumentation Scope" substantially rewritten (434 to 635 characters).
- rewrittensectionlogs/sdk.md#onemit"OnEmit" substantially rewritten (783 to 1044 characters).