From aa4bf33591afde4bd1f5ab103b00bbf9b1718553 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 6 Dec 2024 09:27:04 -0800 Subject: [PATCH 1/8] Deprecate Event API and SDK in favor of Emit Event in the Log API (#4319) --- CHANGELOG.md | 3 +++ spec-compliance-matrix.md | 21 +-------------------- specification/README.md | 1 - specification/logs/README.md | 4 +--- specification/logs/event-api.md | 13 ++----------- specification/logs/event-sdk.md | 3 ++- specification/versioning-and-stability.md | 4 +--- 7 files changed, 10 insertions(+), 39 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a781750a2d2..dcc08f63fca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -35,6 +35,9 @@ release. ### Events +- Deprecate Events API and SDK in favor of having Events support in the Logs API and SDK. + ([#4319](https://github.com/open-telemetry/opentelemetry-specification/pull/4319)) + ### Baggage ### Resource diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index d2c47e48ea5..192e9aab745 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -193,6 +193,7 @@ Disclaimer: this list of features is still a work in progress, please refer to t | LoggerProvider.Shutdown | | | + | | + | | | + | | + | - | | | LoggerProvider.ForceFlush | | | + | | + | | | + | | + | - | | | Logger.Emit(LogRecord) | | | + | | + | | | + | | + | - | | +| Logger.EmitEvent(LogRecord) | | | | | | | | | | | | | | Logger.Enabled | X | + | | | | | | | + | + | | | | SimpleLogRecordProcessor | | | + | | + | | | + | | + | | | | BatchLogRecordProcessor | | | + | | + | | | + | | + | | | @@ -203,26 +204,6 @@ Disclaimer: this list of features is still a work in progress, please refer to t | Can plug custom LogRecordExporter | | | + | | + | | | + | | + | | | | Trace Context Injection | | | + | | + | | | + | | + | + | | -## Events - -Features for the [Events API](specification/logs/event-api.md) and the [Events SDK](specification/logs/event-sdk.md). -Disclaimer: Events are currently in Development status - work in progress. - -| Feature | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | -|----------------------------------------------------------------------------|----------|----|------|----|--------|------|--------|-----|------|-----|------|-------| -| [EventLoggerProvider](specification/logs/event-api.md#eventloggerprovider) | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | -| Get EventLogger | | | | | | | | | | | | | -| Get EventLogger accepts version | X | | | | | | | | | | | | -| Get EventLogger accepts schema_url | X | | | | | | | | | | | | -| Get EventLogger accepts attributes | X | | | | | | | | | | | | -| [EventLogger](specification/logs/event-api.md#eventlogger) | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | -| Emit event accepts name | | | | | | | | | | | | | -| Emit event accepts AnyValue body | X | | | | | | | | | | | | -| Emit event accepts severity | X | | | | | | | | | | | | -| Emit event accepts timestamp | X | | | | | | | | | | | | -| Emit event accepts attributes | X | | | | | | | | | | | | -| Emit event accepts context | X | | | | | | | | | | | | - ## Resource | Feature | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | diff --git a/specification/README.md b/specification/README.md index ecc8ee3a033..32a653e04d6 100644 --- a/specification/README.md +++ b/specification/README.md @@ -33,7 +33,6 @@ path_base_for_github_subdir: - [Metrics](metrics/api.md) - [Logs](logs/README.md) - [API](logs/api.md) - - [Event API](logs/event-api.md) - SDK Specification - [Tracing](trace/sdk.md) - [Metrics](metrics/sdk.md) diff --git a/specification/logs/README.md b/specification/logs/README.md index ecf0e84d0cd..38d611d779b 100644 --- a/specification/logs/README.md +++ b/specification/logs/README.md @@ -230,8 +230,7 @@ processor. ### Infrastructure Logs These are logs generated by various infrastructure components, such as -Kubernetes events (if you are wondering why events are discussed in the context -of logs see [Event API Data model](./event-api.md#event-data-model)). Like system logs, the +Kubernetes events. Like system logs, the infrastructure logs lack a trace context and can be enriched by the resource context - information about the node, pod, container, etc. @@ -447,7 +446,6 @@ standard output. * [Logs API](./api.md) * [Logs SDK](./sdk.md) * [Logs Data Model](./data-model.md) -* [Event API](./event-api.md) * [Trace Context in non-OTLP Log Formats](../compatibility/logging_trace_context.md) ## References diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 5a89336cde0..7d17f7f9e74 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -1,6 +1,7 @@ # Events API -**Status**: [Development](../document-status.md) +**Status**: [Deprecated](../document-status.md) (was never stabilized), +see [Emit Event](./api.md#emit-an-event) in the Logs API for replacement.
Table of Contents @@ -9,7 +10,6 @@ -- [Logs API Development](#logs-api-development) - [Event Data model](#event-data-model) - [Event API use cases](#event-api-use-cases) - [EventLoggerProvider](#eventloggerprovider) @@ -31,15 +31,6 @@ The Event API consists of these main components: provides access to `EventLogger`s. * [EventLogger](#eventlogger) is the component responsible for emitting events. -## Logs API Development - -> [!NOTE] -> We are currently in the process of defining a new [Logs API](./api.md). - -The intent is that this Logs API will incorporate the current functionality of this existing Events API and once it is defined and implemented, the Events API usage will be migrated, deprecated, renamed and eventually removed. - -No further work is scheduled for the current Events API definition at this time. - ## Event Data model Wikipedia’s [definition of log file](https://en.wikipedia.org/wiki/Log_file): diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index b0322f1f77b..25a66a1734b 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -1,6 +1,7 @@ # Events SDK -**Status**: [Development](../document-status.md) +**Status**: [Deprecated](../document-status.md) (was never stabilized), +see the [Logs SDK](./sdk.md) and [Emit Event](./api.md#emit-an-event) in the Logs API for replacement.
Table of Contents diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index 570aa11ba9e..22f9f8e96b0 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -247,9 +247,7 @@ Semantic Conventions defines the set of fields in the OTLP data model: - The attribute keys provided on the LogRecord - The attribute values provided on the LogRecord that are defined in a list of well-known values. - - For log records that are [Log Events](logs/event-api.md) - - The following data provided to [emit event](logs/event-api.md#emit-event): - - The event name (the value of the `event.name` attribute) + - The event name (the value of the `event.name` attribute) Things not listed in the above are not expected to remain stable via semantic convention and are allowed (or expected) to change. A few examples: From 51cb58cddbb3abe701f8ed27f063098e03b71fa2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 6 Dec 2024 18:39:02 +0100 Subject: [PATCH 2/8] [Logs] Remove the in-development isolating log record processor (#4301) --- CHANGELOG.md | 2 ++ specification/logs/sdk.md | 23 +---------------------- 2 files changed, 3 insertions(+), 22 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dcc08f63fca..08ce1ef2a1b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,6 +32,8 @@ release. ([#4183](https://github.com/open-telemetry/opentelemetry-specification/pull/4183)) - Remove the recommendation to not synchronize access to `LoggerConfig.disabled`. ([#4310](https://github.com/open-telemetry/opentelemetry-specification/pull/4310)) +- Remove the in-development isolating log record processor. + ([#4301](https://github.com/open-telemetry/opentelemetry-specification/pull/4301)) ### Events diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 190c723dda4..1de732275fd 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -28,7 +28,6 @@ * [Built-in processors](#built-in-processors) + [Simple processor](#simple-processor) + [Batching processor](#batching-processor) - + [Isolating processor](#isolating-processor) - [LogRecordExporter](#logrecordexporter) * [LogRecordExporter operations](#logrecordexporter-operations) + [Export](#export) @@ -235,8 +234,7 @@ the following information added to the [LogRecord](data-model.md#log-and-event-r * [`TraceFlags`](./data-model.md#field-traceflags) The SDK MAY provide an operation that makes a deep clone of a `ReadWriteLogRecord`. -The operation can be used to implement the [isolating processor](#isolating-processor) -or by asynchronous processors (e.g. [Batching processor](#batching-processor)) +The operation can be used by asynchronous processors (e.g. [Batching processor](#batching-processor)) to avoid race conditions on the log record that is not required to be concurrent safe. @@ -383,10 +381,6 @@ make the flush timeout configurable. The standard OpenTelemetry SDK MUST implement both simple and batch processors, as described below. -**Status**: [Development](../document-status.md) - -The standard OpenTelemetry SDK SHOULD implement an isolating processor, -as described below. - Other common processing scenarios SHOULD be first considered for implementation out-of-process in [OpenTelemetry Collector](../overview.md#collector). @@ -426,21 +420,6 @@ to make sure that they are not invoked concurrently. * `maxExportBatchSize` - the maximum batch size of every export. It must be smaller or equal to `maxQueueSize`. The default value is `512`. -#### Isolating processor - -**Status**: [Development](../document-status.md) - -This is an implementation of `LogRecordProcessor` ensuring the log record -passed to `OnEmit` of the configured `processor` does not share mutable data -with subsequent registered processors. -For example, the `OnEmit` implementation of the isolating processor can be -a decorator that makes a deep copy of the log record before passing it to -the configured `processor`. - -**Configurable parameters:** - -* `processor` - processor to be isolated. - ## LogRecordExporter `LogRecordExporter` defines the interface that protocol-specific exporters must From 52e9be7b61da92afb27b4b2f2dc28c03450758c3 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 6 Dec 2024 11:20:05 -0800 Subject: [PATCH 3/8] Remove auto-assignment of PRs (#4329) --- .github/auto_assign_issue.yml | 22 ---------------------- .github/auto_assign_pr.yml | 25 ------------------------- .github/workflows/auto-assign-pr.yml | 14 -------------- 3 files changed, 61 deletions(-) delete mode 100644 .github/auto_assign_issue.yml delete mode 100644 .github/auto_assign_pr.yml delete mode 100644 .github/workflows/auto-assign-pr.yml diff --git a/.github/auto_assign_issue.yml b/.github/auto_assign_issue.yml deleted file mode 100644 index 5fe775fc287..00000000000 --- a/.github/auto_assign_issue.yml +++ /dev/null @@ -1,22 +0,0 @@ -# Set to true to add reviewers to issues/PRs -addReviewers: false - -# Set to true to add assignees to issues/PRs -addAssignees: true - -# A list of assignees, overrides reviewers if set -assignees: - - arminru - - bogdandrutu - - carlosalberto - - jack-berg - - jmacd - - jsuereth - - reyang - - tigrannajaryan - - yurishkuro - -# A number of assignees to add to the issues/PRs -# Set to 0 to add all of the assignees. -# Uses numberOfReviewers if unset. -numberOfAssignees: 1 diff --git a/.github/auto_assign_pr.yml b/.github/auto_assign_pr.yml deleted file mode 100644 index 4c9716df204..00000000000 --- a/.github/auto_assign_pr.yml +++ /dev/null @@ -1,25 +0,0 @@ -# Set to true to add reviewers to pull requests -addReviewers: false - -# Set to true to add assignees to pull requests -addAssignees: true - -# Set to true to add assignees from different groups to pull requests -useAssigneeGroups: true - -# A list of assignees, split into different groups, to be added to pull requests (GitHub user name) -assigneeGroups: - tc: - - arminru - - bogdandrutu - - carlosalberto - - jack-berg - - jmacd - - jsuereth - - reyang - - tigrannajaryan - - yurishkuro - -# A number of assignees added to the pull request -# Set 0 to add all the assignees (default: 0) -numberOfAssignees: 1 diff --git a/.github/workflows/auto-assign-pr.yml b/.github/workflows/auto-assign-pr.yml deleted file mode 100644 index 694e4fea22b..00000000000 --- a/.github/workflows/auto-assign-pr.yml +++ /dev/null @@ -1,14 +0,0 @@ -name: 'Auto Assign PR' -on: - pull_request_target: - types: [opened, ready_for_review] - -jobs: - add-owner: - runs-on: ubuntu-latest - steps: - - name: run - uses: kentaro-m/auto-assign-action@v1.1.1 - with: - configuration-path: ".github/auto_assign_pr.yml" - repo-token: '${{ secrets.GITHUB_TOKEN }}' From a265ae0628177be25dc477ea8fe200f1c825b871 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 6 Dec 2024 11:23:29 -0800 Subject: [PATCH 4/8] Change `event.name` attribute into top-level event name field (#4320) --- CHANGELOG.md | 2 ++ specification/logs/api.md | 4 ++-- specification/logs/data-model.md | 14 +++++++++++++- specification/logs/sdk.md | 1 + specification/versioning-and-stability.md | 2 +- 5 files changed, 19 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 08ce1ef2a1b..852e94c7700 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -34,6 +34,8 @@ release. ([#4310](https://github.com/open-telemetry/opentelemetry-specification/pull/4310)) - Remove the in-development isolating log record processor. ([#4301](https://github.com/open-telemetry/opentelemetry-specification/pull/4301)) +- Change `event.name` attribute into top-level event name field. + ([#4320](https://github.com/open-telemetry/opentelemetry-specification/pull/4320)) ### Events diff --git a/specification/logs/api.md b/specification/logs/api.md index aa7638351a6..f04062c1348 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -137,6 +137,7 @@ The API MUST accept the following parameters: - [Severity Text](./data-model.md#field-severitytext) (optional) - [Body](./data-model.md#field-body) (optional) - [Attributes](./data-model.md#field-attributes) (optional) +- **Status**: [Development](../document-status.md) - [Event Name](./data-model.md#event-name) (optional) #### Enabled @@ -173,8 +174,7 @@ formatted as an [event](./data-model.md#events). **Parameters:** -* The [`Name`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md) - of the Event. +* [Event Name](./data-model.md#event-name) (required) * [Timestamp](./data-model.md#field-timestamp) (optional) * [Observed Timestamp](./data-model.md#field-observedtimestamp) (optional). If unspecified the implementation SHOULD set it equal to the current time. diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index c7e88dd745b..3fed63c0ba4 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -1,6 +1,6 @@ # Logs Data Model -**Status**: [Stable](../document-status.md) +**Status**: [Stable](../document-status.md), except where otherwise specified
Table of Contents @@ -34,6 +34,7 @@ * [Field: `InstrumentationScope`](#field-instrumentationscope) * [Field: `Attributes`](#field-attributes) + [Errors and Exceptions](#errors-and-exceptions) + * [Field: `EventName`](#field-eventname) - [Example Log Records](#example-log-records) - [Example Mappings](#example-mappings) - [References](#references) @@ -208,6 +209,7 @@ Body |The body of the log record. Resource |Describes the source of the log. InstrumentationScope|Describes the scope that emitted the log. Attributes |Additional information about the event. +**Status**: [Development](../document-status.md) - EventName | Name that identifies the class / type of event. Below is the detailed description of each field. @@ -477,6 +479,16 @@ of the record. If included, they MUST follow the OpenTelemetry [semantic conventions for exception-related attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/exceptions/exceptions-logs.md). +### Field: `EventName` + +**Status**: [Development](../document-status.md) + +Type: string. + +Description: Name that identifies the class / type of the [Event](#events). +This name SHOULD uniquely identify the event structure (both attributes and body). +A log record with a non-empty event name is an [Event](#events). + ## Example Log Records For example log records see diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 1de732275fd..930d900c3f4 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -232,6 +232,7 @@ the following information added to the [LogRecord](data-model.md#log-and-event-r * [`TraceId`](./data-model.md#field-traceid) * [`SpanId`](./data-model.md#field-spanid) * [`TraceFlags`](./data-model.md#field-traceflags) +* **Status**: [Development](../document-status.md) - [`EventName`](./data-model.md#event-name) The SDK MAY provide an operation that makes a deep clone of a `ReadWriteLogRecord`. The operation can be used by asynchronous processors (e.g. [Batching processor](#batching-processor)) diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index 22f9f8e96b0..a9a9ce9c9d4 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -247,7 +247,7 @@ Semantic Conventions defines the set of fields in the OTLP data model: - The attribute keys provided on the LogRecord - The attribute values provided on the LogRecord that are defined in a list of well-known values. - - The event name (the value of the `event.name` attribute) + - The event name Things not listed in the above are not expected to remain stable via semantic convention and are allowed (or expected) to change. A few examples: From 0d046c07e2b24bc2405a3e1d367f93ab102d889d Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 12 Dec 2024 22:31:31 -0600 Subject: [PATCH 5/8] Release 1.40.0 (#4328) December 2024 Release. Mostly in-development additions, e.g. * https://github.com/open-telemetry/opentelemetry-specification/pull/4183 * https://github.com/open-telemetry/opentelemetry-specification/pull/4295 --- CHANGELOG.md | 52 ++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 38 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 852e94c7700..21208c00da5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,36 @@ release. ### Context +### Traces + +### Metrics + +### Logs + +### Events + +### Baggage + +### Resource + +### Profiles + +### OpenTelemetry Protocol + +### Compatibility + +### SDK Configuration + +### Common + +### Supplementary Guidelines + +### OTEPs + +## v1.40.0 (2024-12-12) + +### Context + - Adds optional `GetAll` method to `Getter` in Propagation API, allowing for the retrieval of multiple values for the same key. [#4295](https://github.com/open-telemetry/opentelemetry-specification/pull/4295) @@ -34,25 +64,13 @@ release. ([#4310](https://github.com/open-telemetry/opentelemetry-specification/pull/4310)) - Remove the in-development isolating log record processor. ([#4301](https://github.com/open-telemetry/opentelemetry-specification/pull/4301)) -- Change `event.name` attribute into top-level event name field. - ([#4320](https://github.com/open-telemetry/opentelemetry-specification/pull/4320)) ### Events - Deprecate Events API and SDK in favor of having Events support in the Logs API and SDK. ([#4319](https://github.com/open-telemetry/opentelemetry-specification/pull/4319)) - -### Baggage - -### Resource - -### Profiles - -### OpenTelemetry Protocol - -### Compatibility - -### SDK Configuration +- Change `event.name` attribute into top-level event name field. + ([#4320](https://github.com/open-telemetry/opentelemetry-specification/pull/4320)) ### Common @@ -64,6 +82,12 @@ release. - Add core principles for evaluating specification changes. ([#4286](https://github.com/open-telemetry/opentelemetry-specification/pull/4286)) +## OTEPs + +- The [open-telemetry/oteps](https://github.com/open-telemetry/oteps) repository was + merged into the specification repository. + ([#4288](https://github.com/open-telemetry/opentelemetry-specification/pull/4288)) + ## v1.39.0 (2024-11-06) ### Logs From b9b6d8f698f82cd321fbe4fcc15b76d49902c14e Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 13 Dec 2024 12:42:40 -0800 Subject: [PATCH 6/8] Fix links (#4340) --- specification/logs/api.md | 4 ++-- specification/logs/sdk.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/logs/api.md b/specification/logs/api.md index f04062c1348..24328b2e70b 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -137,7 +137,7 @@ The API MUST accept the following parameters: - [Severity Text](./data-model.md#field-severitytext) (optional) - [Body](./data-model.md#field-body) (optional) - [Attributes](./data-model.md#field-attributes) (optional) -- **Status**: [Development](../document-status.md) - [Event Name](./data-model.md#event-name) (optional) +- **Status**: [Development](../document-status.md) - [Event Name](./data-model.md#field-eventname) (optional) #### Enabled @@ -174,7 +174,7 @@ formatted as an [event](./data-model.md#events). **Parameters:** -* [Event Name](./data-model.md#event-name) (required) +* [Event Name](./data-model.md#field-eventname) (required) * [Timestamp](./data-model.md#field-timestamp) (optional) * [Observed Timestamp](./data-model.md#field-observedtimestamp) (optional). If unspecified the implementation SHOULD set it equal to the current time. diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 930d900c3f4..c61b81d560f 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -232,7 +232,7 @@ the following information added to the [LogRecord](data-model.md#log-and-event-r * [`TraceId`](./data-model.md#field-traceid) * [`SpanId`](./data-model.md#field-spanid) * [`TraceFlags`](./data-model.md#field-traceflags) -* **Status**: [Development](../document-status.md) - [`EventName`](./data-model.md#event-name) +* **Status**: [Development](../document-status.md) - [`EventName`](./data-model.md#field-eventname) The SDK MAY provide an operation that makes a deep clone of a `ReadWriteLogRecord`. The operation can be used by asynchronous processors (e.g. [Batching processor](#batching-processor)) From 21fdcbb8534634cdd3da1ab982891f57f74ad423 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Mon, 16 Dec 2024 18:36:00 -0500 Subject: [PATCH 7/8] Update links to openmetrics to reference the v1.0.0 release (#4341) --- .../prometheus_and_openmetrics.md | 24 +++++++++---------- .../metrics/sdk_exporters/prometheus.md | 4 ++-- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md index 4a549e3308f..986400cb380 100644 --- a/specification/compatibility/prometheus_and_openmetrics.md +++ b/specification/compatibility/prometheus_and_openmetrics.md @@ -82,7 +82,7 @@ at the time of writing: The [Prometheus Metric Name](https://prometheus.io/docs/instrumenting/exposition_formats/#comments-help-text-and-type-information) MUST be added as the Name of the OTLP metric. By default, the name SHOULD NOT be altered, but translation SHOULD provide configuration which, when enabled, removes type (e.g. `_total`) and unit (e.g. `_seconds`) suffixes. -[Prometheus UNIT metadata](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#metricfamily), +[Prometheus UNIT metadata](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#metricfamily), if present, MUST be converted to the unit of the OTLP metric. The unit SHOULD be translated from Prometheus conventions to OpenTelemetry conventions by: @@ -110,11 +110,11 @@ A [Prometheus Gauge](https://prometheus.io/docs/instrumenting/exposition_formats ### Info -A [Prometheus Info](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#info) metric MUST be converted to an OTLP Non-Monotonic Sum unless it is the `target` info metric, which is used to populate [resource attributes](#resource-attributes). A Prometheus Info metric can be thought of as a special-case of the Prometheus Gauge metric which has a value of 1, and whose labels generally stays constant over the life of the process. It is converted to a OTLP Non-Monotonic Sum, rather than an OTLP Gauge, because the value of 1 is intended to be viewed as a count, which should be summed together when aggregating away labels. +A [Prometheus Info](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#info) metric MUST be converted to an OTLP Non-Monotonic Sum unless it is the `target` info metric, which is used to populate [resource attributes](#resource-attributes). A Prometheus Info metric can be thought of as a special-case of the Prometheus Gauge metric which has a value of 1, and whose labels generally stays constant over the life of the process. It is converted to a OTLP Non-Monotonic Sum, rather than an OTLP Gauge, because the value of 1 is intended to be viewed as a count, which should be summed together when aggregating away labels. ### StateSet -A [Prometheus StateSet](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#stateset) metric MUST be converted to an OTLP Non-Monotonic Sum. A Prometheus StateSet metric can be thought of as a special-case of the Prometheus Gauge which has a 0 or 1 value, and has one metric point for every possible state. It is converted to an OTLP Non-Monotonic Sum, rather than an OTLP Gauge, because the value of 1 is intended to be viewed as a count, which should be summed together when aggregating away labels. +A [Prometheus StateSet](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#stateset) metric MUST be converted to an OTLP Non-Monotonic Sum. A Prometheus StateSet metric can be thought of as a special-case of the Prometheus Gauge which has a 0 or 1 value, and has one metric point for every possible state. It is converted to an OTLP Non-Monotonic Sum, rather than an OTLP Gauge, because the value of 1 is intended to be viewed as a count, which should be summed together when aggregating away labels. ### Unknown-typed @@ -146,15 +146,15 @@ Multiple Prometheus metrics are merged together into a single OTLP Summary: The following Prometheus types MUST be dropped: -* [Prometheus GaugeHistogram](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#gaugehistogram) +* [Prometheus GaugeHistogram](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#gaugehistogram) ### Start Time -Prometheus Cumulative metrics can include the start time using the [`_created` sample series](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#counter-1). When converting Prometheus Counters to OTLP, conversion SHOULD use `_created` where available. When no `_created` metric is available, conversion MUST follow [Cumulative streams: handling unknown start time](../metrics/data-model.md#cumulative-streams-handling-unknown-start-time) by default. Conversion MAY offer configuration, disabled by default, which allows using the `process_start_time_seconds` metric to provide the start time. Using `process_start_time_seconds` is only correct when all counters on the target start after the process and are not reset while the process is running. +Prometheus Cumulative metrics can include the start time using the [`_created` sample series](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#counter-1). When converting Prometheus Counters to OTLP, conversion SHOULD use `_created` where available. When no `_created` metric is available, conversion MUST follow [Cumulative streams: handling unknown start time](../metrics/data-model.md#cumulative-streams-handling-unknown-start-time) by default. Conversion MAY offer configuration, disabled by default, which allows using the `process_start_time_seconds` metric to provide the start time. Using `process_start_time_seconds` is only correct when all counters on the target start after the process and are not reset while the process is running. ### Exemplars -[Prometheus Exemplars](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#exemplars) +[Prometheus Exemplars](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#exemplars) can be attached to Prometheus Histogram bucket metric points and counter metric points. Exemplars on histogram buckets SHOULD be converted to exemplars on OpenTelemetry histograms. Exemplars on counter metric points SHOULD be @@ -231,7 +231,7 @@ attributes, and MUST NOT be added as metric attributes: | `url.scheme` | `http` or `https` | In addition to the attributes above, the -[target](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#supporting-target-metadata-in-both-push-based-and-pull-based-systems) +[target](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#supporting-target-metadata-in-both-push-based-and-pull-based-systems) info metric is used to supply additional resource attributes. If present, the `target` info metric MUST be dropped from the batch of metrics, and all labels from the `target` info metric MUST be converted to resource attributes @@ -266,7 +266,7 @@ The Unit of an OTLP metric point SHOULD be converted to the equivalent unit in P * Converting "foo/bar" to "foo_per_bar". The resulting unit SHOULD be added to the metric as -[UNIT metadata](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#metricfamily) +[UNIT metadata](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#metricfamily) and as a suffix to the metric name unless the metric name already ends with the unit (before type-specific suffixes), or the unit metadata MUST be omitted. The unit suffix comes before any type-specific suffixes. @@ -280,7 +280,7 @@ It also dictates type-specific conversion rules listed below. ### Instrumentation Scope -Prometheus exporters SHOULD generate an [Info](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#info)-typed +Prometheus exporters SHOULD generate an [Info](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#info)-typed metric named `otel_scope_info` for each Instrumentation Scope with non-empty scope attributes. If present, Instrumentation Scope `name` and `version` MUST be added as `otel_scope_name` and `otel_scope_version` labels. Scope attributes @@ -413,12 +413,12 @@ Prometheus Exemplars MUST use the `trace_id` and `span_id` keys for the trace and span IDs, respectively. Timestamps MUST be added as timestamps on the Prometheus exemplar, and `filtered_attributes` MUST be added as labels on the Prometheus exemplar unless they would exceed the -[limit on characters](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#exemplars). +[limit on characters](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#exemplars). ### Resource Attributes In Prometheus exporters, an OpenTelemetry Resource SHOULD be converted to -a [`target` info metric](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#supporting-target-metadata-in-both-push-based-and-pull-based-systems) +a [`target` info metric](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#supporting-target-metadata-in-both-push-based-and-pull-based-systems) if the resource is not [empty](../resource/sdk.md#the-empty-resource). The Resource attributes MAY be copied to labels of exported metric families if required by the exporter configuration, or MUST be dropped. The `target` @@ -445,7 +445,7 @@ attributes MUST be combined as `/`, or `service.instance.id` attribute, if present, MUST be converted to the `instance` label; otherwise, `instance` should be added with an empty value. Other resource attributes SHOULD be converted to a -[target](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#supporting-target-metadata-in-both-push-based-and-pull-based-systems) +[target](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#supporting-target-metadata-in-both-push-based-and-pull-based-systems) info metric, or MUST be dropped. The `target` metric is an info-typed metric whose labels MUST include the resource attributes, and MUST NOT include any other labels other than `job` and `instance`. There MUST be at most one diff --git a/specification/metrics/sdk_exporters/prometheus.md b/specification/metrics/sdk_exporters/prometheus.md index 9c119718838..771e3ea8ac4 100644 --- a/specification/metrics/sdk_exporters/prometheus.md +++ b/specification/metrics/sdk_exporters/prometheus.md @@ -30,10 +30,10 @@ by supporting other Protocols, but is not required to implement them. A Prometheus Exporter for an OpenTelemetry metrics SDK MUST NOT use [Prometheus Remote Write format](https://github.com/prometheus/prometheus/blob/main/prompb/remote.proto) -or [OpenMetrics protobuf format](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#protobuf-format). +or [OpenMetrics protobuf format](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#protobuf-format). A Prometheus Exporter for an OpenTelemetry metrics SDK MUST NOT add -[explicit timestamps on Metric points](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#metric). +[explicit timestamps on Metric points](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#metric). There MUST be at most one `target` info metric exposed by an SDK Prometheus exporter. From e81d06bd5def98b9004e3959ec9d4563c707a818 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 17 Dec 2024 09:07:12 -0800 Subject: [PATCH 8/8] Update release procedure in contributing.md (#4339) 1. Remove schemas updates - it's now in semantic-conventions 2. Remove manual step to update opentelemetry.io - it's automated 3. Add manual check for broken link anchors (see https://github.com/open-telemetry/semantic-conventions/issues/1009, #4338 for the context) --- CONTRIBUTING.md | 35 ++++++++--------------------------- 1 file changed, 8 insertions(+), 27 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 928638dbef9..4de73b91669 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -289,34 +289,15 @@ Release Procedure: 1. Prepare a [draft release here](https://github.com/open-telemetry/opentelemetry-specification/releases). Don't publish it yet. -2. Create a PR with updated [CHANGELOG.md](CHANGELOG.md). The CHANGELOG.md must have a +2. Run [opentelemetry.io workflow](https://github.com/open-telemetry/opentelemetry.io/actions/workflows/build-dev.yml) + against `opentelemetry-specification` submodule as a smoke-test for docs. Fix broken links, if any. +3. Create a PR with updated [CHANGELOG.md](CHANGELOG.md). The CHANGELOG.md must have a heading with the new version number. Ensure that no CHANGELOG entries are missing or ended up in the wrong section (e.g., in the last released version rather than Unreleased). - The PR will fail the `schemas-check` Github action (all other actions must pass). - This is expected and will be fixed in the next steps. Have this PR reviewed and approved - and ready to be merged. While it is being reviewed you can work on step 3-4 in parallel. -3. Prepare the schema file for the upcoming release. The schema file should be placed - in the `schemas` directory. If no changes to semantic conventions happened - since the last release which require a corresponding section in the schema file then - simply copy the previous schema file, rename it to the new version and add a section - with the new version number to the file. See for example the schema file for [1.9.0]( - https://github.com/open-telemetry/opentelemetry-specification/blob/main/schemas/1.9.0) - that has no changes from 1.8.0. - The schema file may already exist if there were changes done to semantic conventions - and the schema file was created with corresponding changes. -4. Create and merge the PR with the new schema file. Note the commit hash after merging. - If the schema file for the new release version previously existed then no new PR is - necessary, just note that latest commit hash of this repository. -5. Once CHANGELOG.md PR is approved and ready to be merged we are ready to make the release. - Update the [opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) - repository: the [opentelemetry-specification]( - https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules) - submodule points to this repository. Create a PR and update the submodule to point to - the commit hash from step 4. Merge this PR. This should update the - [https://opentelemetry.io/](https://opentelemetry.io/) website and the new schema file - should be downloadable at `https://opentelemetry.io/schemas/`. -6. Re-trigger the `schema-checks` Github action on the PR that updates the CHANGELOG.md. - The action should pass now. Merge the PR. -7. Add the changelog entries from `CHANGELOG.md` to the description of the previously +4. Once CHANGELOG.md PR is approved and ready to be merged we are ready to make the release. +5. Add the changelog entries from `CHANGELOG.md` to the description of the previously created [draft release here]( https://github.com/open-telemetry/opentelemetry-specification/releases) and publish it. + +New release is then auto-discovered by [opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) pipelines which +(via bot-generated PR) will eventually publish new version of the specification.