diff --git a/CHANGELOG.md b/CHANGELOG.md index bfe96fd1f8a..96eb112f960 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,15 +13,64 @@ release. ### Metrics +- 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 + +### Resource + +### Compatibility + +- OpenTracing Shim: Allow invalid but sampled SpanContext to be returned. + ([#3471](https://github.com/open-telemetry/opentelemetry-specification/pull/3471)) + +### 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. + ([#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 +- 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. @@ -29,10 +78,16 @@ release. ### SDK Configuration +- No changes. + ### Common +- No changes. + ### Supplemenatary Guidelines +- No changes. + ## v1.23.0 (2023-07-12) ### Context @@ -67,8 +122,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 diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 3e78413dc95..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. | | - | + | | + | | | | + | + | + | | @@ -218,19 +219,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 @@ -325,6 +326,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] | - | - | - | - | - | - | - | 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, 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/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 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 diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index ff1aa72ec53..201282ba979 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) @@ -59,10 +60,10 @@ linkTitle: SDK + [AlignedHistogramBucketExemplarReservoir](#alignedhistogrambucketexemplarreservoir) - [MetricReader](#metricreader) * [MetricReader operations](#metricreader-operations) - + [RegisterProducer(metricProducer)](#registerproducermetricproducer) + [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) @@ -160,13 +161,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 @@ -178,10 +182,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 @@ -771,13 +771,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 @@ -791,19 +810,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 @@ -1051,6 +1071,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 @@ -1107,21 +1128,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 @@ -1139,6 +1145,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#). @@ -1187,6 +1199,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) @@ -1410,10 +1441,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... | | @@ -1436,7 +1463,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). @@ -1497,7 +1526,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. 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