From c882652300146262bb7a7367cd90b7d6127fa28d Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Fri, 4 Aug 2023 17:07:34 +0200 Subject: [PATCH 01/11] Add OTLP partial success message handling to compliance matrix (#3637) Co-authored-by: Tyler Yahn --- spec-compliance-matrix.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 3e78413dc95..26282e42bc1 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -325,6 +325,8 @@ Note: Support for environment variables is optional. | SchemaURL in ResourceMetrics and ScopeMetrics | | | + | | + | | - | + | | | - | | | SchemaURL in ResourceLogs and ScopeLogs | | | + | | + | | - | + | | | - | | | Honors the [user agent spec](specification/protocol/exporter.md#user-agent) | | | | | | | | + | | | + | | +| [Partial Success](https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md#partial-success) messages are handled and logged for OTLP/gRPC | X | + | | | | | | | | | | | +| [Partial Success](https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md#partial-success-1) messages are handled and logged for OTLP/HTTP | X | + | | | | | | | | | | | | **[Zipkin](specification/trace/sdk_exporters/zipkin.md)** | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | | Zipkin V1 JSON | X | - | + | | + | - | - | - | - | - | - | - | | Zipkin V1 Thrift | X | - | + | | [-][py1174] | - | - | - | - | - | - | - | From 19044c06077185dd1e79da42b16c4e02eff514b3 Mon Sep 17 00:00:00 2001 From: Bruce Bujon Date: Mon, 7 Aug 2023 17:25:29 +0200 Subject: [PATCH 02/11] Fix inconsistent tracestate reference (#3633) --- specification/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/overview.md b/specification/overview.md index f60799bb88b..ca6ef858fdb 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -188,7 +188,7 @@ propagated from parent to child **Spans**. - **Tracestate** carries tracing-system specific context in a list of key value pairs. **Tracestate** allows different vendors propagate additional information and inter-operate with their legacy Id formats. For more details - see [this](https://w3c.github.io/trace-context/#tracestate-field). + see [this](https://www.w3.org/TR/trace-context/#tracestate-header). ### Links between spans From b2f923fb1650dde1f061507908b834035506a796 Mon Sep 17 00:00:00 2001 From: jack-berg <34418638+jack-berg@users.noreply.github.com> Date: Mon, 7 Aug 2023 15:55:15 -0500 Subject: [PATCH 03/11] Mark noop log bridge API and metric API documents as stable (#3642) --- CHANGELOG.md | 5 +++++ specification/logs/noop.md | 2 +- specification/metrics/noop.md | 2 +- 3 files changed, 7 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bfe96fd1f8a..789345bdc9c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,9 +17,14 @@ release. ([#3546](https://github.com/open-telemetry/opentelemetry-specification/pull/3546)) - Revise the exemplar default reservoirs. ([#3627](https://github.com/open-telemetry/opentelemetry-specification/pull/3627)) +- Mark Metric No-Op API as stable. + ([#3642](https://github.com/open-telemetry/opentelemetry-specification/pull/3642)) ### Logs +- Mark No-Op Logs Bridge API as stable. + ([#3642](https://github.com/open-telemetry/opentelemetry-specification/pull/3642)) + ### Resource ### Compatibility diff --git a/specification/logs/noop.md b/specification/logs/noop.md index 94f0de8f317..4338865c405 100644 --- a/specification/logs/noop.md +++ b/specification/logs/noop.md @@ -4,7 +4,7 @@ linkTitle: No-Op # Logs Bridge API No-Op Implementation -**Status**: [Experimental](../document-status.md) +**Status**: [Stable](../document-status.md)
Table of Contents diff --git a/specification/metrics/noop.md b/specification/metrics/noop.md index f32107d0c7c..ebd08e4fc36 100644 --- a/specification/metrics/noop.md +++ b/specification/metrics/noop.md @@ -4,7 +4,7 @@ linkTitle: No-Op # Metrics No-Op API Implementation -**Status**: [Experimental](../document-status.md) +**Status**: [Stable](../document-status.md)
Table of Contents From ef177f996af661eacb616cd5cc3104ea96d08cbb Mon Sep 17 00:00:00 2001 From: Tom Tan Date: Tue, 8 Aug 2023 01:20:26 -0700 Subject: [PATCH 04/11] Update spec-compliance-matrix for C++ Logs (#3646) --- spec-compliance-matrix.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 26282e42bc1..2e3186f2a30 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -218,19 +218,19 @@ Disclaimer: this list of features is still a work in progress, please refer to t | Feature | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | |----------------------------------------------|----------|-----|------|-----|--------|------|--------|-----|------|-----|------|-------| | **[Logging SDK](specification/logs/sdk.md)** | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | -| LoggerProvider.Get Logger | | | + | | | | | + | | | - | | -| LoggerProvider.Get Logger accepts attributes | | | | | | | | + | | | | | +| LoggerProvider.Get Logger | | | + | | | | | + | | + | - | | +| LoggerProvider.Get Logger accepts attributes | | | | | | | | + | | + | | | | LoggerProvider.Shutdown | | | + | | | | | + | | | - | | | LoggerProvider.ForceFlush | | | + | | | | | + | | | - | | -| Logger.Emit(LogRecord) | | | + | | | | | + | | | - | | -| SimpleLogRecordProcessor | | | + | | | | | + | | | | | -| BatchLogRecordProcessor | | | + | | | | | + | | | | | -| Can plug custom LogRecordProcessor | | | + | | | | | + | | | | | -| OTLP/gRPC exporter | | | + | | + | | | + | | | + | | -| OTLP/HTTP exporter | | | + | | + | | | + | | | + | | +| Logger.Emit(LogRecord) | | | + | | | | | + | | + | - | | +| SimpleLogRecordProcessor | | | + | | | | | + | | + | | | +| BatchLogRecordProcessor | | | + | | | | | + | | + | | | +| Can plug custom LogRecordProcessor | | | + | | | | | + | | + | | | +| OTLP/gRPC exporter | | | + | | + | | | + | | + | + | | +| OTLP/HTTP exporter | | | + | | + | | | + | | + | + | | | OTLP File exporter | | | - | | - | | | | | | - | | -| Can plug custom LogRecordExporter | | | + | | | | | + | | | | | -| Trace Context Injection | | | + | | + | | | + | | | + | | +| Can plug custom LogRecordExporter | | | + | | | | | + | | + | | | +| Trace Context Injection | | | + | | + | | | + | | + | + | | ## Resource From ad1537a46eb856eeb915786fd7cf81e07bdeb426 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Tue, 8 Aug 2023 13:07:57 -0400 Subject: [PATCH 05/11] MetricProducers are passed via config to MetricReaders instead of RegisterProducer (#3613) --- CHANGELOG.md | 2 ++ specification/metrics/sdk.md | 17 +---------------- 2 files changed, 3 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 789345bdc9c..ae5cd663d22 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,8 @@ release. ([#3627](https://github.com/open-telemetry/opentelemetry-specification/pull/3627)) - Mark Metric No-Op API as stable. ([#3642](https://github.com/open-telemetry/opentelemetry-specification/pull/3642)) +- MetricProducers are provided as config to MetricReaders instead of through a RegisterProducer operation. + ([#3613](https://github.com/open-telemetry/opentelemetry-specification/pull/3613)) ### Logs diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 98dfa5deff0..580b90cfd71 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -59,7 +59,6 @@ linkTitle: SDK + [AlignedHistogramBucketExemplarReservoir](#alignedhistogrambucketexemplarreservoir) - [MetricReader](#metricreader) * [MetricReader operations](#metricreader-operations) - + [RegisterProducer(metricProducer)](#registerproducermetricproducer) + [Collect](#collect) + [Shutdown](#shutdown-1) * [Periodic exporting MetricReader](#periodic-exporting-metricreader) @@ -1047,6 +1046,7 @@ SHOULD provide at least the following: * The default output `aggregation` (optional), a function of instrument kind. If not configured, the [default aggregation](#default-aggregation) SHOULD be used. * The default output `temporality` (optional), a function of instrument kind. If not configured, the Cumulative temporality SHOULD be used. * **Status**: [Experimental](../document-status.md) - The default aggregation cardinality limit to use, a function of instrument kind. If not configured, a default value of 2000 SHOULD be used. +* **Status**: [Experimental](../document-status.md) - Zero of more [MetricProducer](#metricproducer)s (optional) to collect metrics from in addition to metrics from the SDK. The [MetricReader.Collect](#collect) method allows general-purpose `MetricExporter` instances to explicitly initiate collection, commonly @@ -1103,21 +1103,6 @@ functions. ### MetricReader operations -#### RegisterProducer(metricProducer) - -**Status**: [Experimental](../document-status.md) - -RegisterProducer causes the MetricReader to use the provided -[MetricProducer](#metricproducer) as a source of aggregated metric data in -subsequent invocations of Collect. RegisterProducer is expected to be called -during initialization, but MAY be invoked later. Multiple registrations -of the same MetricProducer MAY result in duplicate metric data being collected. - -If the [MeterProvider](#meterprovider) is an instance of -[MetricProducer](#metricproducer), this MAY be used to register the -MeterProvider, but MUST NOT allow multiple [MeterProviders](#meterprovider) -to be registered with the same MetricReader. - #### Collect Collects the metrics from the SDK and any registered From ff5ea6145d2f51eb3dca4fffd33fbc460ea8c2a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 9 Aug 2023 00:57:06 +0200 Subject: [PATCH 06/11] Refine MetricProvider.ForceFlush and define ForceFlush for periodic exporting MetricReader (#3563) --- CHANGELOG.md | 2 ++ specification/metrics/sdk.md | 38 +++++++++++++++++++++++++++--------- 2 files changed, 31 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ae5cd663d22..9c52d225d68 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,8 @@ release. ([#3642](https://github.com/open-telemetry/opentelemetry-specification/pull/3642)) - MetricProducers are provided as config to MetricReaders instead of through a RegisterProducer operation. ([#3613](https://github.com/open-telemetry/opentelemetry-specification/pull/3613)) +- Refine `MetricProvider.ForceFlush` and define `ForceFlush` for periodic exporting MetricReader. + ([#3563](https://github.com/open-telemetry/opentelemetry-specification/pull/3563)) ### Logs diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 580b90cfd71..e09f18ff222 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -62,6 +62,7 @@ linkTitle: SDK + [Collect](#collect) + [Shutdown](#shutdown-1) * [Periodic exporting MetricReader](#periodic-exporting-metricreader) + + [ForceFlush](#forceflush-1) - [MetricExporter](#metricexporter) * [Push Metric Exporter](#push-metric-exporter) + [Interface Definition](#interface-definition) @@ -159,13 +160,16 @@ decide if they want to make the shutdown timeout configurable. ### ForceFlush This method provides a way for provider to notify the registered -[MetricReader](#metricreader) and [MetricExporter](#metricexporter) instances, -so they can do as much as they could to consume or send the metrics. Note: -unlike [Push Metric Exporter](#push-metric-exporter) which can send data on its -own schedule, [Pull Metric Exporter](#pull-metric-exporter) can only send the +[MetricReader](#metricreader) instances that have an associated +[Push Metric Exporter](#push-metric-exporter), so they can do as much +as they could to collect and send the metrics. +Note: [Pull Metric Exporter](#pull-metric-exporter) can only send the data when it is being asked by the scraper, so `ForceFlush` would not make much sense. +`ForceFlush` MUST invoke `ForceFlush` on all registered +[MetricReader](#metricreader) instances that implement `ForceFlush`. + `ForceFlush` SHOULD provide a way to let the caller know whether it succeeded, failed or timed out. `ForceFlush` SHOULD return some **ERROR** status if there is an error condition; and if there is no error condition, it should return some @@ -177,10 +181,6 @@ implemented as a blocking API or an asynchronous API which notifies the caller via a callback or an event. [OpenTelemetry SDK](../overview.md#sdk) authors MAY decide if they want to make the flush timeout configurable. -`ForceFlush` MUST invoke `ForceFlush` on all registered -[MetricReader](#metricreader) and [Push Metric Exporter](#push-metric-exporter) -instances. - ### View A `View` provides SDK users with the flexibility to customize the metrics that @@ -1168,6 +1168,25 @@ from `MetricReader` and start a background task which calls the inherited the background task calls `Collect()` which passes metrics to the push exporter. +#### ForceFlush + +This method provides a way for the periodic exporting MetricReader +so it can do as much as it could to collect and send the metrics. + +`ForceFlush` SHOULD collect metrics, call [`Export(batch)`](#exportbatch) +and [`ForceFlush()`](#forceflush-2) on the configured +[Push Metric Exporter](#push-metric-exporter). + +`ForceFlush` SHOULD provide a way to let the caller know whether it succeeded, +failed or timed out. `ForceFlush` SHOULD return some **ERROR** status if there +is an error condition; and if there is no error condition, it should return some +**NO ERROR** status, language implementations MAY decide how to model **ERROR** +and **NO ERROR**. + +`ForceFlush` SHOULD complete or abort within some timeout. `ForceFlush` MAY be +implemented as a blocking API or an asynchronous API which notifies the caller +via a callback or an event. + ## MetricExporter **Status**: [Stable](../document-status.md) @@ -1478,7 +1497,8 @@ called concurrently. **ExemplarReservoir** - all methods are safe to be called concurrently. -**MetricReader** - `Collect` and `Shutdown` are safe to be called concurrently. +**MetricReader** - `Collect`, `ForceFlush` (for periodic exporting MetricReader) +and `Shutdown` are safe to be called concurrently. **MetricExporter** - `ForceFlush` and `Shutdown` are safe to be called concurrently. From 2038b78553a86d29ee44dcfee63f528d703de83c Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Wed, 9 Aug 2023 07:22:56 -0700 Subject: [PATCH 07/11] Specify how to handle instrument name conflict (#3626) - Refactor the "Duplicate instrument registration" section - Clarify how to handle when instrument names differ by only their casing: 1. Return the first-seen instrument name for all conflicting instrument names 2. Log a warning Resolves #3539 --- CHANGELOG.md | 2 ++ spec-compliance-matrix.md | 1 + specification/metrics/sdk.md | 55 +++++++++++++++++++++++++----------- 3 files changed, 41 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c52d225d68..c38ae70674d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ release. ### Metrics +- Specify how to handle instrument name conflicts. + ([#3626](https://github.com/open-telemetry/opentelemetry-specification/pull/3626)) - Add experimental metric attributes advice API. ([#3546](https://github.com/open-telemetry/opentelemetry-specification/pull/3546)) - Revise the exemplar default reservoirs. diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 2e3186f2a30..0dfc50555e5 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -117,6 +117,7 @@ formats is required. Implementing more than one format is optional. | Instruments have an optional description. | | + | + | + | + | | | + | + | + | + | | | Instruments have an optional advice. | | | | | | | | | | | | | | A valid instrument MUST be created and warning SHOULD be emitted when multiple instruments are registered under the same `Meter` using the same `name`. | | | + | + | + | | | | | | | | +| Duplicate instrument registration name conflicts are resolved by using the first-seen for the stream name. | | | + | | | | | | | | | | | It is possible to register two instruments with same `name` under different `Meter`s. | | + | + | + | + | | | | + | + | + | | | Instrument names conform to the specified syntax. | | - | + | | + | | | | + | + | + | | | Instrument units conform to the specified syntax. | | - | + | | + | | | | + | + | + | | diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index e09f18ff222..68d6a60dfe6 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -42,6 +42,7 @@ linkTitle: SDK + [Asynchronous instrument cardinality limits](#asynchronous-instrument-cardinality-limits) - [Meter](#meter) * [Duplicate instrument registration](#duplicate-instrument-registration) + + [Name conflict](#name-conflict) * [Instrument name](#instrument-name) * [Instrument unit](#instrument-unit) * [Instrument description](#instrument-description) @@ -766,13 +767,32 @@ Distinct meters MUST be treated as separate namespaces for the purposes of detec ### Duplicate instrument registration -When more than one Instrument of the same `name` is created for identical -Meters from the same MeterProvider, denoted _duplicate instrument -registration_, the Meter MUST create a valid Instrument in every case. Here, -"valid" means an instrument that is functional and can be expected to export -data, despite potentially creating a [semantic error in the data +A _duplicate instrument registration_ occurs when more than one Instrument of +the same [`name`](./api.md#instrument-name-syntax) is created for identical +Meters from the same MeterProvider but they have different [identifying +fields](./api.md#instrument). + +Whenever this occurs, users still need to be able to make measurements with the +duplicate instrument. This means that the Meter MUST return a functional +instrument that can be expected to export data even if this will cause +[semantic error in the data model](data-model.md#opentelemetry-protocol-data-model-producer-recommendations). +Additionally, users need to be informed about this error. Therefore, when a +duplicate instrument registration occurs, and it is not corrected with a View, +a warning SHOULD be emitted. The emitted warning SHOULD include information for +the user on how to resolve the conflict, if possible. + +1. If the potential conflict involves multiple `description` + properties, setting the `description` through a configured View + SHOULD avoid the warning. +2. If the potential conflict involves instruments that can be distinguished by + a supported View selector (e.g. name, instrument kind) a renaming View + recipe SHOULD be included in the warning. +3. Otherwise (e.g., use of multiple units), the SDK SHOULD pass through the + data by reporting both `Metric` objects and emit a generic warning + describing the duplicate instrument registration. + It is unspecified whether or under which conditions the same or different Instrument instance will be returned as a result of duplicate instrument registration. The term _identical_ applied to @@ -786,19 +806,20 @@ model](data-model.md#opentelemetry-protocol-data-model-producer-recommendations) the SDK MUST aggregate data from [identical Instruments](api.md#instrument) together in its export pipeline. -When a duplicate instrument registration occurs, and it is not corrected with a -View, a warning SHOULD be emitted. The emitted warning SHOULD include -information for the user on how to resolve the conflict, if possible. +#### Name conflict -1. If the potential conflict involves multiple `description` - properties, setting the `description` through a configured View - SHOULD avoid the warning. -2. If the potential conflict involves instruments that can be - distinguished by a supported View selector (e.g., instrument type) - a renaming View recipe SHOULD be included in the warning. -3. Otherwise (e.g., use of multiple units), the SDK SHOULD pass through the - data by reporting both `Metric` objects and emit a generic warning - describing the duplicate instrument registration. +The [`name`](./api.md#instrument-name-syntax) of an Instrument is defined to be +case-insensitive. If an SDK uses a case-sensitive encoding to represent this +`name`, a duplicate instrument registration will occur when a user passes +multiple casings of the same `name`. When this happens, the Meter MUST return +an instrument using the first-seen instrument name and log an appropriate error +as described above. + +For example, if a user creates an instrument with the name `requestCount` and +then makes another request to the same `Meter` to create an instrument with the +name `RequestCount`, in both cases an instrument with the name `requestCount` +needs to be returned to the user and a log message needs to be emitted for the +second request. ### Instrument name From 634b6aea7d916bdafe40a524e19f172f7c8c9bb8 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 10 Aug 2023 17:11:51 +0200 Subject: [PATCH 08/11] Release 1.24.0 (#3644) August release. --- CHANGELOG.md | 38 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c38ae70674d..910547a58f6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,12 +13,38 @@ release. ### Metrics +### Logs + +### Resource + +### Compatibility + +### SDK Configuration + +### Common + +### Supplemenatary Guidelines + +## v1.24.0 (2023-08-10) + +### Context + +- No changes. + +### Traces + +- No changes. + +### Metrics + - Specify how to handle instrument name conflicts. ([#3626](https://github.com/open-telemetry/opentelemetry-specification/pull/3626)) - Add experimental metric attributes advice API. ([#3546](https://github.com/open-telemetry/opentelemetry-specification/pull/3546)) - Revise the exemplar default reservoirs. ([#3627](https://github.com/open-telemetry/opentelemetry-specification/pull/3627)) +- Mark the default aggregation cardinality Experimental in MetricReader. + ([#3619](https://github.com/open-telemetry/opentelemetry-specification/pull/3619)) - Mark Metric No-Op API as stable. ([#3642](https://github.com/open-telemetry/opentelemetry-specification/pull/3642)) - MetricProducers are provided as config to MetricReaders instead of through a RegisterProducer operation. @@ -28,11 +54,15 @@ release. ### Logs +- Clarify how log appender use Scope name and attributes. + ([#3583](https://github.com/open-telemetry/opentelemetry-specification/pull/3583)) - Mark No-Op Logs Bridge API as stable. ([#3642](https://github.com/open-telemetry/opentelemetry-specification/pull/3642)) ### Resource +- No changes. + ### Compatibility - Prometheus exporters SHOULD provide configuration to disable the addition of `_total` suffixes. @@ -40,10 +70,16 @@ release. ### SDK Configuration +- No changes. + ### Common +- No changes. + ### Supplemenatary Guidelines +- No changes. + ## v1.23.0 (2023-07-12) ### Context @@ -78,8 +114,6 @@ release. ([#3559](https://github.com/open-telemetry/opentelemetry-specification/pull/3559)) - Make SDK Logger Creation more normative. ([#3529](https://github.com/open-telemetry/opentelemetry-specification/pull/3529)) -- Clarify how log appender use Scope name and attributes. - ([#3583](https://github.com/open-telemetry/opentelemetry-specification/pull/3583)) ### Resource From b9c8a02f64ba86501b995649e957bba44e6712f5 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 10 Aug 2023 18:10:19 +0200 Subject: [PATCH 09/11] OpenTracing Shim: Allow invalid but sampled SpanContext to be returned. (#3471) This is done to support the `jaeger-debug-id` functionality, which allows invalid SpanContext with debug information to be propagated. This came up through an issue in Java: https://github.com/open-telemetry/opentelemetry-java/issues/5339 --- CHANGELOG.md | 3 +++ specification/compatibility/opentracing.md | 18 ++++++++++++++---- 2 files changed, 17 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 910547a58f6..c99be2f2db0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,9 @@ release. ### Compatibility +- OpenTracing Shim: Allow invalid but sampled SpanContext to be returned. + ([#3471](https://github.com/open-telemetry/opentelemetry-specification/pull/3471)) + ### SDK Configuration ### Common diff --git a/specification/compatibility/opentracing.md b/specification/compatibility/opentracing.md index 96f011a5943..1481b0af2b7 100644 --- a/specification/compatibility/opentracing.md +++ b/specification/compatibility/opentracing.md @@ -194,12 +194,18 @@ registered or the global OpenTelemetry `Propagator`s, as configured at construct - `TextMap` and `HttpHeaders` formats MUST use their explicitly specified `TextMapPropagator`, if any, or else use the global `TextMapPropagator`. -If the extracted `SpanContext` is invalid AND the extracted `Baggage` is empty, this operation -MUST return a null value, and otherwise it MUST return a `SpanContext` Shim instance with -the extracted values. +The operation MUST return a `SpanContext` Shim instance with the extracted values if any of these conditions are met: + +* `SpanContext` is valid. +* `SpanContext` is sampled. +* `SpanContext` contains non-empty extracted `Baggage`. + +Otherwise, the operation MUST return null or empty value. ```java -if (!extractedSpanContext.isValid() && extractedBaggage.isEmpty()) { +if (!extractedSpanContext.isValid() + && !extractedSpanContext.isSampled() + && extractedBaggage.isEmpty()) { return null; } @@ -210,6 +216,10 @@ Errors MAY be raised if either the `Format` is not recognized or no value could be extracted, depending on the specific OpenTracing Language API (e.g. Go and Python do, but Java may not). +Note: Invalid but sampled `SpanContext` instances are returned as a way to support +`jaeger-debug-id` [headers](https://github.com/jaegertracing/jaeger-client-java#via-http-headers), +which are used to force propagation of debug information. + ## Close OPTIONAL operation. If this operation is implemented for a specific OpenTracing language, From 0a128820da124301d95d7c2c789a544a22e1a861 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 10 Aug 2023 10:55:25 -0700 Subject: [PATCH 10/11] Increase metric name maximum length from 63 to 255 characters (#3648) --- CHANGELOG.md | 3 +++ specification/metrics/api.md | 4 ++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c99be2f2db0..b0dbb8ce85d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,9 @@ release. ### Metrics +- Increase metric name maximum length from 63 to 255 characters. + ([#3648](https://github.com/open-telemetry/opentelemetry-specification/pull/3648)) + ### Logs ### Resource diff --git a/specification/metrics/api.md b/specification/metrics/api.md index e4f9502ab15..f6824e83b47 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -202,7 +202,7 @@ The instrument name syntax is defined below using the [Augmented Backus-Naur Form](https://tools.ietf.org/html/rfc5234): ```abnf -instrument-name = ALPHA 0*62 ("_" / "." / "-" / ALPHA / DIGIT) +instrument-name = ALPHA 0*254 ("_" / "." / "-" / ALPHA / DIGIT) ALPHA = %x41-5A / %x61-7A; A-Z / a-z DIGIT = %x30-39 ; 0-9 @@ -213,7 +213,7 @@ DIGIT = %x30-39 ; 0-9 * The first character must be an alphabetic character. * Subsequent characters must belong to the alphanumeric characters, '_', '.', and '-'. -* They can have a maximum length of 63 characters. +* They can have a maximum length of 255 characters. #### Instrument unit From fce0a69537d5d70137b2c96f3e2557e88a48fbd1 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Thu, 10 Aug 2023 14:38:58 -0400 Subject: [PATCH 11/11] MetricProducer.Produce can include a Resource parameter (#3636) --- CHANGELOG.md | 2 ++ specification/metrics/sdk.md | 14 +++++++++----- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b0dbb8ce85d..96eb112f960 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,8 @@ release. - Increase metric name maximum length from 63 to 255 characters. ([#3648](https://github.com/open-telemetry/opentelemetry-specification/pull/3648)) +- MetricReader.Collect ignores Resource from MetricProducer.Produce. + ([#3636](https://github.com/open-telemetry/opentelemetry-specification/pull/3636)) ### Logs diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 68d6a60dfe6..8e348315d78 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -1141,6 +1141,12 @@ SDK](../overview.md#sdk) authors MAY choose to add parameters (e.g. callback, filter, timeout). [OpenTelemetry SDK](../overview.md#sdk) authors MAY choose the return value type, or do not return anything. +`Collect` SHOULD invoke [Produce](#produce-batch) on registered +[MetricProducers](#metricproducer). If the batch of metric points from +`Produce` includes [Resource](../resource/sdk.md) information, `Collect` MAY +replace the `Resource` from the MetricProducer with the `Resource` provided +when constructing the MeterProvider instead. + Note: it is expected that the `MetricReader.Collect` implementations will be provided by the SDK, so it is RECOMMENDED to prevent the user from accidentally overriding it, if possible (e.g. `final` in C++ and Java, `sealed` in C#). @@ -1431,10 +1437,6 @@ in-memory state MAY implement the `MetricProducer` interface for convenience. `AggregationTemporality` of produced metrics. SDK authors MAY provide utility libraries to facilitate conversion between delta and cumulative temporalities. -If the batch of [Metric points](./data-model.md#metric-points) returned by -`Produce()` includes a [Resource](../resource/sdk.md), the `MetricProducer` MUST -accept configuration for the [Resource](../resource/sdk.md). - ```text +-----------------+ +--------------+ | | Metrics... | | @@ -1457,7 +1459,9 @@ A `MetricProducer` MUST support the following functions: `Produce` provides metrics from the MetricProducer to the caller. `Produce` MUST return a batch of [Metric points](./data-model.md#metric-points). -`Produce` does not have any required parameters, however, [OpenTelemetry +If the batch of [Metric points](./data-model.md#metric-points) includes +resource information, `Produce` SHOULD require a resource as a parameter. +`Produce` does not have any other required parameters, however, [OpenTelemetry SDK](../overview.md#sdk) authors MAY choose to add required or optional parameters (e.g. timeout).