From 8f2b66656d09948cb7cbbe954dd36e06d9d5783e Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Fri, 29 Nov 2024 11:03:38 +0100 Subject: [PATCH 01/41] Added SDK span telemetry metrics --- docs/attributes-registry/telemetry.md | 22 +- docs/general/metrics.md | 1 + docs/telemetry/telemetry-sdk-metrics.md | 256 ++++++++++++++++++++++++ model/telemetry/metrics.yaml | 87 ++++++++ model/telemetry/registry.yaml | 38 ++++ 5 files changed, 402 insertions(+), 2 deletions(-) create mode 100644 docs/telemetry/telemetry-sdk-metrics.md create mode 100644 model/telemetry/metrics.yaml diff --git a/docs/attributes-registry/telemetry.md b/docs/attributes-registry/telemetry.md index 7c92cc2430..008c8d5b2d 100644 --- a/docs/attributes-registry/telemetry.md +++ b/docs/attributes-registry/telemetry.md @@ -14,20 +14,38 @@ This document defines attributes for telemetry SDK. |---|---|---|---|---| | `telemetry.distro.name` | string | The name of the auto instrumentation agent or distribution, if used. [1] | `parts-unlimited-java` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `telemetry.distro.version` | string | The version string of the auto instrumentation agent or distribution, if used. | `1.2.3` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.component.id` | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.exporter.type` | string | A name identifying the type of the OpenTelemetry SDK exporter. [3] | `otlp-grpc`; `jaeger` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.failure_reason` | string | A low-cardinality for why this component failed to process a record. [4] | `queue full`; `exporter failed` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `telemetry.sdk.language` | string | The language of the telemetry SDK. | `cpp`; `dotnet`; `erlang` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. [2] | `opentelemetry` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. [5] | `opentelemetry` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `telemetry.sdk.processor.type` | string | A name identifying the type of the OpenTelemetry SDK processor. [6] | `batch-span`; `MyCustomProcessor` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `telemetry.sdk.version` | string | The version string of the telemetry SDK. | `1.2.3` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1] `telemetry.distro.name`:** Official auto instrumentation agents and distributions SHOULD set the `telemetry.distro.name` attribute to a string starting with `opentelemetry-`, e.g. `opentelemetry-java-instrumentation`. -**[2] `telemetry.sdk.name`:** The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`. +**[2] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, +the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. +E.g. it MUST NOT use a UUID. +It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a +monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is created. +For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. +These values will therefore be reused in the case of an application restart. + +**[3] `telemetry.sdk.exporter.type`:** For OTLP, the values `otlp-grpc`, `otlp-http` or `otlp-http-json` MUST be used, based on the transport and serialization format. + +**[4] `telemetry.sdk.failure_reason`:** For the SDK Batch Span Processor `queue full` MUST be used for when items are dropped due to a full queue. + +**[5] `telemetry.sdk.name`:** The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`. If another SDK, like a fork or a vendor-provided implementation, is used, this SDK MUST set the `telemetry.sdk.name` attribute to the fully-qualified class or module name of this SDK's main entry point or another suitable identifier depending on the language. The identifier `opentelemetry` is reserved and MUST NOT be used in this case. All custom identifiers SHOULD be stable across different versions of an implementation. +**[6] `telemetry.sdk.processor.type`:** The value `batch-span` MUST be used for the SDK builtin Batch Span Processor. + --- `telemetry.sdk.language` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. diff --git a/docs/general/metrics.md b/docs/general/metrics.md index b69930e674..7c18bfca90 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -38,6 +38,7 @@ The following semantic conventions surrounding metrics are defined: * [Hardware](/docs/system/hardware-metrics.md): For hardware-related metrics. * [Process](/docs/system/process-metrics.md): For standard process metrics. * [Runtime Environment](/docs/runtime/README.md#metrics): For runtime environment metrics. +* [SDK Telemetry](/docs/telemetry/telemetry-sdk-metrics.md): Metrics emitted by the OpenTelemetry SDK components. Apart from semantic conventions for metrics, [traces](trace.md), [logs](logs.md), and [events](events.md), OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.37.0/specification/resource/sdk.md) with diff --git a/docs/telemetry/telemetry-sdk-metrics.md b/docs/telemetry/telemetry-sdk-metrics.md new file mode 100644 index 0000000000..5c55010917 --- /dev/null +++ b/docs/telemetry/telemetry-sdk-metrics.md @@ -0,0 +1,256 @@ + + +# Semantic Conventions for OpenTelemetry SDK metrics + +**Status**: [Experimental][DocumentStatus] + +This document describes metrics emitted by the OpenTelemetry SDK components themselves about their internal state. + + + + + +- [Span Metrics](#span-metrics) + - [Metric: `telemetry.sdk.trace.spans.ended`](#metric-telemetrysdktracespansended) + - [Metric: `telemetry.sdk.trace.spans.sampled`](#metric-telemetrysdktracespanssampled) + - [Metric: `telemetry.sdk.trace.processor.queue_size`](#metric-telemetrysdktraceprocessorqueue_size) + - [Metric: `telemetry.sdk.trace.processor.total`](#metric-telemetrysdktraceprocessortotal) + - [Metric: `telemetry.sdk.trace.processor.failed`](#metric-telemetrysdktraceprocessorfailed) + - [Metric: `telemetry.sdk.trace.exporter.total`](#metric-telemetrysdktraceexportertotal) + - [Metric: `telemetry.sdk.trace.exporter.failed`](#metric-telemetrysdktraceexporterfailed) + + + +## Span Metrics + +### Metric: `telemetry.sdk.trace.spans.ended` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `telemetry.sdk.trace.spans.ended` | Counter | `1` | The number of spans which have been ended | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + + +### Metric: `telemetry.sdk.trace.spans.sampled` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `telemetry.sdk.trace.spans.sampled` | Counter | `1` | The number of spans which have been ended AND are sampled | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `telemetry.sdk.trace.processor.queue_size` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `telemetry.sdk.trace.processor.queue_size` | UpDownCounter | `1` | The number of spans in the queue of an instance of an SDK span processor [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`telemetry.sdk.processor.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK processor. [2] | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, +the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. +E.g. it MUST NOT use a UUID. +It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a +monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is created. +For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. +These values will therefore be reused in the case of an application restart. + +**[2] `telemetry.sdk.processor.type`:** The value `batch-span` MUST be used for the SDK builtin Batch Span Processor. + + + + + + +### Metric: `telemetry.sdk.trace.processor.total` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `telemetry.sdk.trace.processor.total` | Counter | `1` | The total number of spans submitted for processing to this span processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`telemetry.sdk.processor.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK processor. [2] | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, +the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. +E.g. it MUST NOT use a UUID. +It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a +monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is created. +For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. +These values will therefore be reused in the case of an application restart. + +**[2] `telemetry.sdk.processor.type`:** The value `batch-span` MUST be used for the SDK builtin Batch Span Processor. + + + + + + + +### Metric: `telemetry.sdk.trace.processor.failed` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `telemetry.sdk.trace.processor.failed` | Counter | `1` | The total number of spans which could not be successfully processed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`telemetry.sdk.failure_reason`](/docs/attributes-registry/telemetry.md) | string | A low-cardinality for why this component failed to process a record. [2] | `queue full`; `exporter failed` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`telemetry.sdk.processor.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK processor. [3] | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, +the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. +E.g. it MUST NOT use a UUID. +It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a +monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is created. +For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. +These values will therefore be reused in the case of an application restart. + +**[2] `telemetry.sdk.failure_reason`:** For the SDK Batch Span Processor `queue full` MUST be used for when items are dropped due to a full queue. + +**[3] `telemetry.sdk.processor.type`:** The value `batch-span` MUST be used for the SDK builtin Batch Span Processor. + + + + + + + +### Metric: `telemetry.sdk.trace.exporter.total` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `telemetry.sdk.trace.exporter.total` | Counter | `1` | The total number of spans submitted for export | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`telemetry.sdk.exporter.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK exporter. [2] | `otlp-grpc`; `jaeger` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, +the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. +E.g. it MUST NOT use a UUID. +It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a +monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is created. +For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. +These values will therefore be reused in the case of an application restart. + +**[2] `telemetry.sdk.exporter.type`:** For OTLP, the values `otlp-grpc`, `otlp-http` or `otlp-http-json` MUST be used, based on the transport and serialization format. + + + + + + +### Metric: `telemetry.sdk.trace.exporter.failed` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `telemetry.sdk.trace.exporter.failed` | Counter | `1` | The total number of spans which could not be successfully exported | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`telemetry.sdk.exporter.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK exporter. [2] | `otlp-grpc`; `jaeger` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`telemetry.sdk.failure_reason`](/docs/attributes-registry/telemetry.md) | string | A low-cardinality for why this component failed to process a record. [3] | `queue full`; `exporter failed` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, +the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. +E.g. it MUST NOT use a UUID. +It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a +monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is created. +For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. +These values will therefore be reused in the case of an application restart. + +**[2] `telemetry.sdk.exporter.type`:** For OTLP, the values `otlp-grpc`, `otlp-http` or `otlp-http-json` MUST be used, based on the transport and serialization format. + +**[3] `telemetry.sdk.failure_reason`:** For the SDK Batch Span Processor `queue full` MUST be used for when items are dropped due to a full queue. + + + + + + + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/model/telemetry/metrics.yaml b/model/telemetry/metrics.yaml new file mode 100644 index 0000000000..f3c688db8e --- /dev/null +++ b/model/telemetry/metrics.yaml @@ -0,0 +1,87 @@ +groups: + - id: metric.telemetry.sdk.trace.spans.ended + type: metric + metric_name: telemetry.sdk.trace.spans.ended + stability: experimental + brief: "The number of spans which have been ended" + instrument: counter + unit: "1" + + - id: metric.telemetry.sdk.trace.spans.sampled + type: metric + metric_name: telemetry.sdk.trace.spans.sampled + stability: experimental + brief: "The number of spans which have been ended AND are sampled" + instrument: counter + unit: "1" + + - id: metric.telemetry.sdk.trace.processor.queue_size + type: metric + metric_name: telemetry.sdk.trace.processor.queue_size + stability: experimental + brief: "The number of spans in the queue of an instance of an SDK span processor" + note: | + Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. + instrument: updowncounter + unit: "1" + attributes: + - ref: telemetry.sdk.processor.type + - ref: telemetry.sdk.component.id + + - id: metric.telemetry.sdk.trace.processor.total + type: metric + metric_name: telemetry.sdk.trace.processor.total + stability: experimental + brief: "The total number of spans submitted for processing to this span processor" + instrument: counter + unit: "1" + attributes: + - ref: telemetry.sdk.processor.type + - ref: telemetry.sdk.component.id + + - id: metric.telemetry.sdk.trace.processor.failed + type: metric + metric_name: telemetry.sdk.trace.processor.failed + stability: experimental + brief: "The total number of spans which could not be successfully processed" + instrument: counter + unit: "1" + attributes: + - ref: telemetry.sdk.processor.type + - ref: telemetry.sdk.component.id + - ref: telemetry.sdk.failure_reason + + - id: metric.telemetry.sdk.trace.processor.failed + type: metric + metric_name: telemetry.sdk.trace.processor.failed + stability: experimental + brief: "The total number of spans which could not be successfully processed" + instrument: counter + unit: "1" + attributes: + - ref: telemetry.sdk.processor.type + - ref: telemetry.sdk.component.id + - ref: telemetry.sdk.failure_reason + + - id: metric.telemetry.sdk.trace.exporter.total + type: metric + metric_name: telemetry.sdk.trace.exporter.total + stability: experimental + brief: "The total number of spans submitted for export" + instrument: counter + unit: "1" + attributes: + - ref: telemetry.sdk.exporter.type + - ref: telemetry.sdk.component.id + + - id: metric.telemetry.sdk.trace.exporter.failed + type: metric + metric_name: telemetry.sdk.trace.exporter.failed + stability: experimental + brief: "The total number of spans which could not be successfully exported" + instrument: counter + unit: "1" + attributes: + - ref: telemetry.sdk.exporter.type + - ref: telemetry.sdk.component.id + - ref: telemetry.sdk.failure_reason \ No newline at end of file diff --git a/model/telemetry/registry.yaml b/model/telemetry/registry.yaml index 2cf3937501..e1a4e7e159 100644 --- a/model/telemetry/registry.yaml +++ b/model/telemetry/registry.yaml @@ -81,3 +81,41 @@ groups: brief: > The version string of the auto instrumentation agent or distribution, if used. examples: ["1.2.3"] + - id: telemetry.sdk.processor.type + type: string + stability: experimental + brief: > + A name identifying the type of the OpenTelemetry SDK processor. + note: | + The value `batch-span` MUST be used for the SDK builtin Batch Span Processor. + examples: ["batch-span", "MyCustomProcessor"] + - id: telemetry.sdk.exporter.type + type: string + stability: experimental + brief: > + A name identifying the type of the OpenTelemetry SDK exporter. + note: | + For OTLP, the values `otlp-grpc`, `otlp-http` or `otlp-http-json` MUST be used, based on the transport and serialization format. + examples: ["otlp-grpc", "jaeger"] + - id: telemetry.sdk.component.id + type: string + stability: experimental + brief: > + A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. + note: | + The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, + the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. + E.g. it MUST NOT use a UUID. + It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a + monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is created. + For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. + These values will therefore be reused in the case of an application restart. + examples: ["batch-span-0", "custom-name"] + - id: telemetry.sdk.failure_reason + type: string + stability: experimental + brief: > + A low-cardinality for why this component failed to process a record. + note: | + For the SDK Batch Span Processor `queue full` MUST be used for when items are dropped due to a full queue. + examples: ["queue full", "exporter failed"] From 8b2a1db584b5f77c6197e2d67bbc8ceec6dc039c Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Fri, 29 Nov 2024 11:16:33 +0100 Subject: [PATCH 02/41] Fix formatting --- docs/attributes-registry/telemetry.md | 5 +++-- docs/telemetry/telemetry-sdk-metrics.md | 29 +++++++++++++------------ model/telemetry/registry.yaml | 5 +++-- 3 files changed, 21 insertions(+), 18 deletions(-) diff --git a/docs/attributes-registry/telemetry.md b/docs/attributes-registry/telemetry.md index 008c8d5b2d..0c70f606f8 100644 --- a/docs/attributes-registry/telemetry.md +++ b/docs/attributes-registry/telemetry.md @@ -28,8 +28,9 @@ a string starting with `opentelemetry-`, e.g. `opentelemetry-java-instrumentatio **[2] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a -monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is created. +It instead MAY do that by using the following pattern as value: `-`: +Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an +instance of the given component type is created. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. diff --git a/docs/telemetry/telemetry-sdk-metrics.md b/docs/telemetry/telemetry-sdk-metrics.md index 5c55010917..f3b4d14936 100644 --- a/docs/telemetry/telemetry-sdk-metrics.md +++ b/docs/telemetry/telemetry-sdk-metrics.md @@ -45,7 +45,6 @@ This metric is [recommended][MetricRecommended]. - ### Metric: `telemetry.sdk.trace.spans.sampled` This metric is [recommended][MetricRecommended]. @@ -91,8 +90,9 @@ This metric is [recommended][MetricRecommended]. **[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a -monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is created. +It instead MAY do that by using the following pattern as value: `-`: +Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an +instance of the given component type is created. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. @@ -126,8 +126,9 @@ This metric is [recommended][MetricRecommended]. **[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a -monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is created. +It instead MAY do that by using the following pattern as value: `-`: +Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an +instance of the given component type is created. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. @@ -138,7 +139,6 @@ These values will therefore be reused in the case of an application restart. - ### Metric: `telemetry.sdk.trace.processor.failed` This metric is [recommended][MetricRecommended]. @@ -163,8 +163,9 @@ This metric is [recommended][MetricRecommended]. **[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a -monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is created. +It instead MAY do that by using the following pattern as value: `-`: +Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an +instance of the given component type is created. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. @@ -177,7 +178,6 @@ These values will therefore be reused in the case of an application restart. - ### Metric: `telemetry.sdk.trace.exporter.total` This metric is [recommended][MetricRecommended]. @@ -201,8 +201,9 @@ This metric is [recommended][MetricRecommended]. **[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a -monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is created. +It instead MAY do that by using the following pattern as value: `-`: +Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an +instance of the given component type is created. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. @@ -237,8 +238,9 @@ This metric is [recommended][MetricRecommended]. **[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a -monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is created. +It instead MAY do that by using the following pattern as value: `-`: +Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an +instance of the given component type is created. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. @@ -251,6 +253,5 @@ These values will therefore be reused in the case of an application restart. - [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/model/telemetry/registry.yaml b/model/telemetry/registry.yaml index e1a4e7e159..85dbc3a76c 100644 --- a/model/telemetry/registry.yaml +++ b/model/telemetry/registry.yaml @@ -106,8 +106,9 @@ groups: The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. - It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a - monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is created. + It instead MAY do that by using the following pattern as value: `-`: + Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an + instance of the given component type is created. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. examples: ["batch-span-0", "custom-name"] From 8bbea82126729ca57459a3f1e1e95f49e0c6c231 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Fri, 29 Nov 2024 11:20:34 +0100 Subject: [PATCH 03/41] Fix yamllint --- model/telemetry/metrics.yaml | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-) diff --git a/model/telemetry/metrics.yaml b/model/telemetry/metrics.yaml index f3c688db8e..144b489e86 100644 --- a/model/telemetry/metrics.yaml +++ b/model/telemetry/metrics.yaml @@ -38,19 +38,7 @@ groups: attributes: - ref: telemetry.sdk.processor.type - ref: telemetry.sdk.component.id - - - id: metric.telemetry.sdk.trace.processor.failed - type: metric - metric_name: telemetry.sdk.trace.processor.failed - stability: experimental - brief: "The total number of spans which could not be successfully processed" - instrument: counter - unit: "1" - attributes: - - ref: telemetry.sdk.processor.type - - ref: telemetry.sdk.component.id - - ref: telemetry.sdk.failure_reason - + - id: metric.telemetry.sdk.trace.processor.failed type: metric metric_name: telemetry.sdk.trace.processor.failed @@ -84,4 +72,4 @@ groups: attributes: - ref: telemetry.sdk.exporter.type - ref: telemetry.sdk.component.id - - ref: telemetry.sdk.failure_reason \ No newline at end of file + - ref: telemetry.sdk.failure_reason From cef63f2d88723fedb03110e23e74c80b73108aaa Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Fri, 29 Nov 2024 11:29:46 +0100 Subject: [PATCH 04/41] Changelog --- .chloggen/sdk-telemetry-span-metrics.yaml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 .chloggen/sdk-telemetry-span-metrics.yaml diff --git a/.chloggen/sdk-telemetry-span-metrics.yaml b/.chloggen/sdk-telemetry-span-metrics.yaml new file mode 100644 index 0000000000..729f87248c --- /dev/null +++ b/.chloggen/sdk-telemetry-span-metrics.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: 'enhancement' + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: 'telemetry' + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Adds SDK self-monitoring metrics for span processing + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [1631] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: From c24bcccc20b7f5ed1f5e8d07cec408bcdbb19dfb Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Fri, 29 Nov 2024 12:19:44 +0100 Subject: [PATCH 05/41] Reuse error.type --- docs/attributes-registry/telemetry.md | 11 ++-- docs/telemetry/telemetry-sdk-metrics.md | 74 +++++++++++++++++++++---- model/telemetry/metrics.yaml | 5 +- model/telemetry/registry.yaml | 9 +-- 4 files changed, 71 insertions(+), 28 deletions(-) diff --git a/docs/attributes-registry/telemetry.md b/docs/attributes-registry/telemetry.md index 0c70f606f8..041241e1ba 100644 --- a/docs/attributes-registry/telemetry.md +++ b/docs/attributes-registry/telemetry.md @@ -16,10 +16,9 @@ This document defines attributes for telemetry SDK. | `telemetry.distro.version` | string | The version string of the auto instrumentation agent or distribution, if used. | `1.2.3` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `telemetry.sdk.component.id` | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `telemetry.sdk.exporter.type` | string | A name identifying the type of the OpenTelemetry SDK exporter. [3] | `otlp-grpc`; `jaeger` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `telemetry.sdk.failure_reason` | string | A low-cardinality for why this component failed to process a record. [4] | `queue full`; `exporter failed` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `telemetry.sdk.language` | string | The language of the telemetry SDK. | `cpp`; `dotnet`; `erlang` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. [5] | `opentelemetry` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `telemetry.sdk.processor.type` | string | A name identifying the type of the OpenTelemetry SDK processor. [6] | `batch-span`; `MyCustomProcessor` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. [4] | `opentelemetry` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `telemetry.sdk.processor.type` | string | A name identifying the type of the OpenTelemetry SDK processor. [5] | `batch-span`; `MyCustomProcessor` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `telemetry.sdk.version` | string | The version string of the telemetry SDK. | `1.2.3` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1] `telemetry.distro.name`:** Official auto instrumentation agents and distributions SHOULD set the `telemetry.distro.name` attribute to @@ -36,16 +35,14 @@ These values will therefore be reused in the case of an application restart. **[3] `telemetry.sdk.exporter.type`:** For OTLP, the values `otlp-grpc`, `otlp-http` or `otlp-http-json` MUST be used, based on the transport and serialization format. -**[4] `telemetry.sdk.failure_reason`:** For the SDK Batch Span Processor `queue full` MUST be used for when items are dropped due to a full queue. - -**[5] `telemetry.sdk.name`:** The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`. +**[4] `telemetry.sdk.name`:** The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`. If another SDK, like a fork or a vendor-provided implementation, is used, this SDK MUST set the `telemetry.sdk.name` attribute to the fully-qualified class or module name of this SDK's main entry point or another suitable identifier depending on the language. The identifier `opentelemetry` is reserved and MUST NOT be used in this case. All custom identifiers SHOULD be stable across different versions of an implementation. -**[6] `telemetry.sdk.processor.type`:** The value `batch-span` MUST be used for the SDK builtin Batch Span Processor. +**[5] `telemetry.sdk.processor.type`:** The value `batch-span` MUST be used for the SDK builtin Batch Span Processor. --- diff --git a/docs/telemetry/telemetry-sdk-metrics.md b/docs/telemetry/telemetry-sdk-metrics.md index f3b4d14936..01de25078d 100644 --- a/docs/telemetry/telemetry-sdk-metrics.md +++ b/docs/telemetry/telemetry-sdk-metrics.md @@ -156,11 +156,31 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`telemetry.sdk.failure_reason`](/docs/attributes-registry/telemetry.md) | string | A low-cardinality for why this component failed to process a record. [2] | `queue full`; `exporter failed` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `queue full` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`telemetry.sdk.processor.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK processor. [3] | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, +**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. + +When `error.type` is set to a type (e.g., an exception type), its +canonical class name identifying the type within the artifact SHOULD be used. + +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low. +Telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time when no +additional filters are applied. + +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + +If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), +it's RECOMMENDED to: + +- Use a domain-specific attribute +- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. + +**[2] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. It instead MAY do that by using the following pattern as value: `-`: @@ -169,10 +189,16 @@ instance of the given component type is created. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. -**[2] `telemetry.sdk.failure_reason`:** For the SDK Batch Span Processor `queue full` MUST be used for when items are dropped due to a full queue. - **[3] `telemetry.sdk.processor.type`:** The value `batch-span` MUST be used for the SDK builtin Batch Span Processor. +--- + +`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + @@ -231,11 +257,31 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`telemetry.sdk.exporter.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK exporter. [2] | `otlp-grpc`; `jaeger` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`telemetry.sdk.failure_reason`](/docs/attributes-registry/telemetry.md) | string | A low-cardinality for why this component failed to process a record. [3] | `queue full`; `exporter failed` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`telemetry.sdk.exporter.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK exporter. [3] | `otlp-grpc`; `jaeger` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, +**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. + +When `error.type` is set to a type (e.g., an exception type), its +canonical class name identifying the type within the artifact SHOULD be used. + +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low. +Telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time when no +additional filters are applied. + +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + +If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), +it's RECOMMENDED to: + +- Use a domain-specific attribute +- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. + +**[2] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. It instead MAY do that by using the following pattern as value: `-`: @@ -244,9 +290,15 @@ instance of the given component type is created. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. -**[2] `telemetry.sdk.exporter.type`:** For OTLP, the values `otlp-grpc`, `otlp-http` or `otlp-http-json` MUST be used, based on the transport and serialization format. +**[3] `telemetry.sdk.exporter.type`:** For OTLP, the values `otlp-grpc`, `otlp-http` or `otlp-http-json` MUST be used, based on the transport and serialization format. + +--- + +`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -**[3] `telemetry.sdk.failure_reason`:** For the SDK Batch Span Processor `queue full` MUST be used for when items are dropped due to a full queue. +| Value | Description | Stability | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/model/telemetry/metrics.yaml b/model/telemetry/metrics.yaml index 144b489e86..b8a2debae1 100644 --- a/model/telemetry/metrics.yaml +++ b/model/telemetry/metrics.yaml @@ -49,7 +49,8 @@ groups: attributes: - ref: telemetry.sdk.processor.type - ref: telemetry.sdk.component.id - - ref: telemetry.sdk.failure_reason + - ref: error.type + examples: ["queue full"] - id: metric.telemetry.sdk.trace.exporter.total type: metric @@ -72,4 +73,4 @@ groups: attributes: - ref: telemetry.sdk.exporter.type - ref: telemetry.sdk.component.id - - ref: telemetry.sdk.failure_reason + - ref: error.type diff --git a/model/telemetry/registry.yaml b/model/telemetry/registry.yaml index 85dbc3a76c..96f18ceb19 100644 --- a/model/telemetry/registry.yaml +++ b/model/telemetry/registry.yaml @@ -112,11 +112,4 @@ groups: For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. examples: ["batch-span-0", "custom-name"] - - id: telemetry.sdk.failure_reason - type: string - stability: experimental - brief: > - A low-cardinality for why this component failed to process a record. - note: | - For the SDK Batch Span Processor `queue full` MUST be used for when items are dropped due to a full queue. - examples: ["queue full", "exporter failed"] + From 34e56e78f03501216025278349b8fe6a528e00d5 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Fri, 29 Nov 2024 12:43:21 +0100 Subject: [PATCH 06/41] Use enum for processor and exporter type attributes --- docs/attributes-registry/telemetry.md | 29 +++++++++--- docs/telemetry/telemetry-sdk-metrics.md | 61 ++++++++++++++++++++----- model/telemetry/registry.yaml | 36 ++++++++++++--- 3 files changed, 100 insertions(+), 26 deletions(-) diff --git a/docs/attributes-registry/telemetry.md b/docs/attributes-registry/telemetry.md index 041241e1ba..babd0aebbc 100644 --- a/docs/attributes-registry/telemetry.md +++ b/docs/attributes-registry/telemetry.md @@ -15,10 +15,10 @@ This document defines attributes for telemetry SDK. | `telemetry.distro.name` | string | The name of the auto instrumentation agent or distribution, if used. [1] | `parts-unlimited-java` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `telemetry.distro.version` | string | The version string of the auto instrumentation agent or distribution, if used. | `1.2.3` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `telemetry.sdk.component.id` | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `telemetry.sdk.exporter.type` | string | A name identifying the type of the OpenTelemetry SDK exporter. [3] | `otlp-grpc`; `jaeger` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.exporter.type` | string | A name identifying the type of the OpenTelemetry SDK exporter. | `otlp-grpc`; `jaeger` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `telemetry.sdk.language` | string | The language of the telemetry SDK. | `cpp`; `dotnet`; `erlang` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. [4] | `opentelemetry` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `telemetry.sdk.processor.type` | string | A name identifying the type of the OpenTelemetry SDK processor. [5] | `batch-span`; `MyCustomProcessor` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. [3] | `opentelemetry` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `telemetry.sdk.processor.type` | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `telemetry.sdk.version` | string | The version string of the telemetry SDK. | `1.2.3` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1] `telemetry.distro.name`:** Official auto instrumentation agents and distributions SHOULD set the `telemetry.distro.name` attribute to @@ -33,16 +33,22 @@ instance of the given component type is created. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. -**[3] `telemetry.sdk.exporter.type`:** For OTLP, the values `otlp-grpc`, `otlp-http` or `otlp-http-json` MUST be used, based on the transport and serialization format. - -**[4] `telemetry.sdk.name`:** The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`. +**[3] `telemetry.sdk.name`:** The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`. If another SDK, like a fork or a vendor-provided implementation, is used, this SDK MUST set the `telemetry.sdk.name` attribute to the fully-qualified class or module name of this SDK's main entry point or another suitable identifier depending on the language. The identifier `opentelemetry` is reserved and MUST NOT be used in this case. All custom identifiers SHOULD be stable across different versions of an implementation. -**[5] `telemetry.sdk.processor.type`:** The value `batch-span` MUST be used for the SDK builtin Batch Span Processor. +--- + +`telemetry.sdk.exporter.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `otlp-grpc` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp-http` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp-http-json` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | --- @@ -62,3 +68,12 @@ All custom identifiers SHOULD be stable across different versions of an implemen | `rust` | rust | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `swift` | swift | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `webjs` | webjs | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +--- + +`telemetry.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `batch-span` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `simple-span` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/telemetry/telemetry-sdk-metrics.md b/docs/telemetry/telemetry-sdk-metrics.md index 01de25078d..24a069296e 100644 --- a/docs/telemetry/telemetry-sdk-metrics.md +++ b/docs/telemetry/telemetry-sdk-metrics.md @@ -85,7 +85,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`telemetry.sdk.processor.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK processor. [2] | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`telemetry.sdk.processor.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. @@ -96,7 +96,14 @@ instance of the given component type is created. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. -**[2] `telemetry.sdk.processor.type`:** The value `batch-span` MUST be used for the SDK builtin Batch Span Processor. +--- + +`telemetry.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `batch-span` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `simple-span` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -121,7 +128,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`telemetry.sdk.processor.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK processor. [2] | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`telemetry.sdk.processor.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. @@ -132,7 +139,14 @@ instance of the given component type is created. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. -**[2] `telemetry.sdk.processor.type`:** The value `batch-span` MUST be used for the SDK builtin Batch Span Processor. +--- + +`telemetry.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `batch-span` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `simple-span` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -158,7 +172,7 @@ This metric is [recommended][MetricRecommended]. |---|---|---|---|---|---| | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `queue full` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`telemetry.sdk.processor.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK processor. [3] | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`telemetry.sdk.processor.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. @@ -189,8 +203,6 @@ instance of the given component type is created. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. -**[3] `telemetry.sdk.processor.type`:** The value `batch-span` MUST be used for the SDK builtin Batch Span Processor. - --- `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. @@ -199,6 +211,15 @@ These values will therefore be reused in the case of an application restart. |---|---|---| | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +--- + +`telemetry.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `batch-span` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `simple-span` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + @@ -222,7 +243,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`telemetry.sdk.exporter.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK exporter. [2] | `otlp-grpc`; `jaeger` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`telemetry.sdk.exporter.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK exporter. | `otlp-grpc`; `jaeger` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. @@ -233,7 +254,15 @@ instance of the given component type is created. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. -**[2] `telemetry.sdk.exporter.type`:** For OTLP, the values `otlp-grpc`, `otlp-http` or `otlp-http-json` MUST be used, based on the transport and serialization format. +--- + +`telemetry.sdk.exporter.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `otlp-grpc` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp-http` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp-http-json` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -259,7 +288,7 @@ This metric is [recommended][MetricRecommended]. |---|---|---|---|---|---| | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`telemetry.sdk.exporter.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK exporter. [3] | `otlp-grpc`; `jaeger` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`telemetry.sdk.exporter.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK exporter. | `otlp-grpc`; `jaeger` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. @@ -290,8 +319,6 @@ instance of the given component type is created. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. -**[3] `telemetry.sdk.exporter.type`:** For OTLP, the values `otlp-grpc`, `otlp-http` or `otlp-http-json` MUST be used, based on the transport and serialization format. - --- `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. @@ -300,6 +327,16 @@ These values will therefore be reused in the case of an application restart. |---|---|---| | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +--- + +`telemetry.sdk.exporter.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `otlp-grpc` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp-http` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp-http-json` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + diff --git a/model/telemetry/registry.yaml b/model/telemetry/registry.yaml index 96f18ceb19..f5ffaf0eef 100644 --- a/model/telemetry/registry.yaml +++ b/model/telemetry/registry.yaml @@ -82,20 +82,43 @@ groups: The version string of the auto instrumentation agent or distribution, if used. examples: ["1.2.3"] - id: telemetry.sdk.processor.type - type: string + type: + members: + - id: batch_span + value: "batch-span" + brief: > + The builtin SDK Batching Span Processor + stability: experimental + - id: simple_span + value: "simple-span" + brief: > + The builtin SDK Simple Span Processor + stability: experimental stability: experimental brief: > A name identifying the type of the OpenTelemetry SDK processor. - note: | - The value `batch-span` MUST be used for the SDK builtin Batch Span Processor. examples: ["batch-span", "MyCustomProcessor"] - id: telemetry.sdk.exporter.type - type: string + type: + members: + - id: otlp_grpc + value: "otlp-grpc" + brief: > + OTLP exporter over gRPC with protobuf serialization + stability: experimental + - id: otlp_http + value: "otlp-http" + brief: > + OTLP exporter over HTTP with protobuf serialization + stability: experimental + - id: otlp_http_json + value: "otlp-http-json" + brief: > + OTLP exporter over HTTP with JSON serialization + stability: experimental stability: experimental brief: > A name identifying the type of the OpenTelemetry SDK exporter. - note: | - For OTLP, the values `otlp-grpc`, `otlp-http` or `otlp-http-json` MUST be used, based on the transport and serialization format. examples: ["otlp-grpc", "jaeger"] - id: telemetry.sdk.component.id type: string @@ -112,4 +135,3 @@ groups: For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. examples: ["batch-span-0", "custom-name"] - From 42489175c14991a51f29b395a269b0ac3ecf9454 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Fri, 29 Nov 2024 14:05:10 +0100 Subject: [PATCH 07/41] Renamed trace to span namespace --- docs/telemetry/telemetry-sdk-metrics.md | 26 +++++++++--------- model/telemetry/metrics.yaml | 36 ++++++++++++------------- 2 files changed, 31 insertions(+), 31 deletions(-) diff --git a/docs/telemetry/telemetry-sdk-metrics.md b/docs/telemetry/telemetry-sdk-metrics.md index 24a069296e..35b625e687 100644 --- a/docs/telemetry/telemetry-sdk-metrics.md +++ b/docs/telemetry/telemetry-sdk-metrics.md @@ -25,11 +25,11 @@ This document describes metrics emitted by the OpenTelemetry SDK components them ## Span Metrics -### Metric: `telemetry.sdk.trace.spans.ended` +### Metric: `telemetry.sdk.span.ended_count` This metric is [recommended][MetricRecommended]. - + @@ -45,7 +45,7 @@ This metric is [recommended][MetricRecommended]. -### Metric: `telemetry.sdk.trace.spans.sampled` +### Metric: `telemetry.sdk.span.sampled_count` This metric is [recommended][MetricRecommended]. @@ -65,11 +65,11 @@ This metric is [recommended][MetricRecommended]. -### Metric: `telemetry.sdk.trace.processor.queue_size` +### Metric: `telemetry.sdk.span.processor.queue_size` This metric is [recommended][MetricRecommended]. - + @@ -110,11 +110,11 @@ These values will therefore be reused in the case of an application restart. -### Metric: `telemetry.sdk.trace.processor.total` +### Metric: `telemetry.sdk.span.processor.spans_submitted` This metric is [recommended][MetricRecommended]. - + @@ -153,11 +153,11 @@ These values will therefore be reused in the case of an application restart. -### Metric: `telemetry.sdk.trace.processor.failed` +### Metric: `telemetry.sdk.span.processor.spans_failed` This metric is [recommended][MetricRecommended]. - + @@ -225,11 +225,11 @@ These values will therefore be reused in the case of an application restart. -### Metric: `telemetry.sdk.trace.exporter.total` +### Metric: `telemetry.sdk.span.exporter.spans_submitted` This metric is [recommended][MetricRecommended]. - + @@ -269,11 +269,11 @@ These values will therefore be reused in the case of an application restart. -### Metric: `telemetry.sdk.trace.exporter.failed` +### Metric: `telemetry.sdk.span.exporter.spans_failed` This metric is [recommended][MetricRecommended]. - + diff --git a/model/telemetry/metrics.yaml b/model/telemetry/metrics.yaml index b8a2debae1..12e9bd1b64 100644 --- a/model/telemetry/metrics.yaml +++ b/model/telemetry/metrics.yaml @@ -1,23 +1,23 @@ groups: - - id: metric.telemetry.sdk.trace.spans.ended + - id: metric.telemetry.sdk.span.ended_count type: metric - metric_name: telemetry.sdk.trace.spans.ended + metric_name: telemetry.sdk.span.ended_count stability: experimental brief: "The number of spans which have been ended" instrument: counter unit: "1" - - id: metric.telemetry.sdk.trace.spans.sampled + - id: metric.telemetry.sdk.span.sampled_count type: metric - metric_name: telemetry.sdk.trace.spans.sampled + metric_name: telemetry.sdk.span.sampled_count stability: experimental brief: "The number of spans which have been ended AND are sampled" instrument: counter unit: "1" - - id: metric.telemetry.sdk.trace.processor.queue_size + - id: metric.telemetry.sdk.span.processor.queue_size type: metric - metric_name: telemetry.sdk.trace.processor.queue_size + metric_name: telemetry.sdk.span.processor.queue_size stability: experimental brief: "The number of spans in the queue of an instance of an SDK span processor" note: | @@ -28,22 +28,22 @@ groups: - ref: telemetry.sdk.processor.type - ref: telemetry.sdk.component.id - - id: metric.telemetry.sdk.trace.processor.total + - id: metric.telemetry.sdk.span.processor.spans_submitted type: metric - metric_name: telemetry.sdk.trace.processor.total + metric_name: telemetry.sdk.trace.processor.spans_submitted stability: experimental - brief: "The total number of spans submitted for processing to this span processor" + brief: "The number of spans submitted for processing to this span processor" instrument: counter unit: "1" attributes: - ref: telemetry.sdk.processor.type - ref: telemetry.sdk.component.id - - id: metric.telemetry.sdk.trace.processor.failed + - id: metric.telemetry.sdk.span.processor.spans_submitted type: metric - metric_name: telemetry.sdk.trace.processor.failed + metric_name: telemetry.sdk.span.processor.spans_submitted stability: experimental - brief: "The total number of spans which could not be successfully processed" + brief: "The number of spans which could not be successfully processed" instrument: counter unit: "1" attributes: @@ -52,22 +52,22 @@ groups: - ref: error.type examples: ["queue full"] - - id: metric.telemetry.sdk.trace.exporter.total + - id: metric.telemetry.sdk.span.exporter.spans_submitted type: metric - metric_name: telemetry.sdk.trace.exporter.total + metric_name: telemetry.sdk.span.exporter.spans_submitted stability: experimental - brief: "The total number of spans submitted for export" + brief: "The number of spans submitted for export" instrument: counter unit: "1" attributes: - ref: telemetry.sdk.exporter.type - ref: telemetry.sdk.component.id - - id: metric.telemetry.sdk.trace.exporter.failed + - id: metric.telemetry.sdk.span.exporter.spans_failed type: metric - metric_name: telemetry.sdk.trace.exporter.failed + metric_name: telemetry.sdk.span.exporter.spans_failed stability: experimental - brief: "The total number of spans which could not be successfully exported" + brief: "The number of spans which could not be successfully exported" instrument: counter unit: "1" attributes: From 2174d24d2edaf4a4dcbec7b1528d5ca4f1312b96 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Fri, 29 Nov 2024 14:10:15 +0100 Subject: [PATCH 08/41] Fixed invalid metric name --- model/telemetry/metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/telemetry/metrics.yaml b/model/telemetry/metrics.yaml index 12e9bd1b64..81ea29f7d1 100644 --- a/model/telemetry/metrics.yaml +++ b/model/telemetry/metrics.yaml @@ -30,7 +30,7 @@ groups: - id: metric.telemetry.sdk.span.processor.spans_submitted type: metric - metric_name: telemetry.sdk.trace.processor.spans_submitted + metric_name: telemetry.sdk.span.processor.spans_submitted stability: experimental brief: "The number of spans submitted for processing to this span processor" instrument: counter From 0e54b96ac97f2c6ab2f366c84236a3ec25a9e329 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Fri, 29 Nov 2024 14:19:13 +0100 Subject: [PATCH 09/41] fix lots of dumb mistakes --- docs/telemetry/telemetry-sdk-metrics.md | 34 ++++++++++++------------- model/telemetry/metrics.yaml | 6 +++-- 2 files changed, 21 insertions(+), 19 deletions(-) diff --git a/docs/telemetry/telemetry-sdk-metrics.md b/docs/telemetry/telemetry-sdk-metrics.md index 35b625e687..0c3a9c6fc8 100644 --- a/docs/telemetry/telemetry-sdk-metrics.md +++ b/docs/telemetry/telemetry-sdk-metrics.md @@ -13,13 +13,13 @@ This document describes metrics emitted by the OpenTelemetry SDK components them - [Span Metrics](#span-metrics) - - [Metric: `telemetry.sdk.trace.spans.ended`](#metric-telemetrysdktracespansended) - - [Metric: `telemetry.sdk.trace.spans.sampled`](#metric-telemetrysdktracespanssampled) - - [Metric: `telemetry.sdk.trace.processor.queue_size`](#metric-telemetrysdktraceprocessorqueue_size) - - [Metric: `telemetry.sdk.trace.processor.total`](#metric-telemetrysdktraceprocessortotal) - - [Metric: `telemetry.sdk.trace.processor.failed`](#metric-telemetrysdktraceprocessorfailed) - - [Metric: `telemetry.sdk.trace.exporter.total`](#metric-telemetrysdktraceexportertotal) - - [Metric: `telemetry.sdk.trace.exporter.failed`](#metric-telemetrysdktraceexporterfailed) + - [Metric: `telemetry.sdk.span.ended_count`](#metric-telemetrysdkspanended_count) + - [Metric: `telemetry.sdk.span.sampled_count`](#metric-telemetrysdkspansampled_count) + - [Metric: `telemetry.sdk.span.processor.queue_size`](#metric-telemetrysdkspanprocessorqueue_size) + - [Metric: `telemetry.sdk.span.processor.spans_submitted`](#metric-telemetrysdkspanprocessorspans_submitted) + - [Metric: `telemetry.sdk.span.processor.spans_failed`](#metric-telemetrysdkspanprocessorspans_failed) + - [Metric: `telemetry.sdk.span.exporter.spans_submitted`](#metric-telemetrysdkspanexporterspans_submitted) + - [Metric: `telemetry.sdk.span.exporter.spans_failed`](#metric-telemetrysdkspanexporterspans_failed) @@ -38,7 +38,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.trace.spans.ended` | Counter | `1` | The number of spans which have been ended | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.span.ended_count` | Counter | `1` | The number of spans which have been ended | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -49,7 +49,7 @@ This metric is [recommended][MetricRecommended]. This metric is [recommended][MetricRecommended]. - + @@ -58,7 +58,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.trace.spans.sampled` | Counter | `1` | The number of spans which have been ended AND are sampled | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.span.sampled_count` | Counter | `1` | The number of spans which have been ended AND are sampled | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -78,7 +78,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.trace.processor.queue_size` | UpDownCounter | `1` | The number of spans in the queue of an instance of an SDK span processor [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.span.processor.queue_size` | UpDownCounter | `1` | The number of spans in the queue of an instance of an SDK span processor [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. @@ -123,7 +123,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.trace.processor.total` | Counter | `1` | The total number of spans submitted for processing to this span processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.span.processor.spans_submitted` | Counter | `1` | The number of spans submitted for processing to this span processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -157,7 +157,7 @@ These values will therefore be reused in the case of an application restart. This metric is [recommended][MetricRecommended]. - + @@ -166,11 +166,11 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.trace.processor.failed` | Counter | `1` | The total number of spans which could not be successfully processed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.span.processor.spans_failed` | Counter | `1` | The number of spans which could not be successfully processed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `queue full` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`error.type`](/docs/attributes-registry/error.md) | string | A low-cardinality description of the failure reason. SDK Batching Span Processors MUST use `queue full` for spans dropped due to a full queue. [1] | `queue full` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`telemetry.sdk.processor.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -238,7 +238,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.trace.exporter.total` | Counter | `1` | The total number of spans submitted for export | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.span.exporter.spans_submitted` | Counter | `1` | The number of spans submitted for export | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -282,7 +282,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.trace.exporter.failed` | Counter | `1` | The total number of spans which could not be successfully exported | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.span.exporter.spans_failed` | Counter | `1` | The number of spans which could not be successfully exported | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/model/telemetry/metrics.yaml b/model/telemetry/metrics.yaml index 81ea29f7d1..5caa5ddc2d 100644 --- a/model/telemetry/metrics.yaml +++ b/model/telemetry/metrics.yaml @@ -39,9 +39,9 @@ groups: - ref: telemetry.sdk.processor.type - ref: telemetry.sdk.component.id - - id: metric.telemetry.sdk.span.processor.spans_submitted + - id: metric.telemetry.sdk.span.processor.spans_failed type: metric - metric_name: telemetry.sdk.span.processor.spans_submitted + metric_name: telemetry.sdk.span.processor.spans_failed stability: experimental brief: "The number of spans which could not be successfully processed" instrument: counter @@ -50,6 +50,8 @@ groups: - ref: telemetry.sdk.processor.type - ref: telemetry.sdk.component.id - ref: error.type + brief: > + A low-cardinality description of the failure reason. SDK Batching Span Processors MUST use `queue full` for spans dropped due to a full queue. examples: ["queue full"] - id: metric.telemetry.sdk.span.exporter.spans_submitted From c62be6444b0c2eb41dde7ab9fd8fcd8c4b4ae7aa Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Fri, 29 Nov 2024 14:25:11 +0100 Subject: [PATCH 10/41] Added queue_capacity metric --- docs/telemetry/telemetry-sdk-metrics.md | 48 ++++++++++++++++++++++++- model/telemetry/metrics.yaml | 15 +++++++- 2 files changed, 61 insertions(+), 2 deletions(-) diff --git a/docs/telemetry/telemetry-sdk-metrics.md b/docs/telemetry/telemetry-sdk-metrics.md index 0c3a9c6fc8..6c77b9797f 100644 --- a/docs/telemetry/telemetry-sdk-metrics.md +++ b/docs/telemetry/telemetry-sdk-metrics.md @@ -16,6 +16,7 @@ This document describes metrics emitted by the OpenTelemetry SDK components them - [Metric: `telemetry.sdk.span.ended_count`](#metric-telemetrysdkspanended_count) - [Metric: `telemetry.sdk.span.sampled_count`](#metric-telemetrysdkspansampled_count) - [Metric: `telemetry.sdk.span.processor.queue_size`](#metric-telemetrysdkspanprocessorqueue_size) + - [Metric: `telemetry.sdk.span.processor.queue_capacity`](#metric-telemetrysdkspanprocessorqueue_capacity) - [Metric: `telemetry.sdk.span.processor.spans_submitted`](#metric-telemetrysdkspanprocessorspans_submitted) - [Metric: `telemetry.sdk.span.processor.spans_failed`](#metric-telemetrysdkspanprocessorspans_failed) - [Metric: `telemetry.sdk.span.exporter.spans_submitted`](#metric-telemetrysdkspanexporterspans_submitted) @@ -78,7 +79,52 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.span.processor.queue_size` | UpDownCounter | `1` | The number of spans in the queue of an instance of an SDK span processor [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.span.processor.queue_size` | UpDownCounter | `1` | The number of spans in the queue of a given instance of an SDK span processor [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`telemetry.sdk.processor.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, +the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. +E.g. it MUST NOT use a UUID. +It instead MAY do that by using the following pattern as value: `-`: +Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an +instance of the given component type is created. +For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. +These values will therefore be reused in the case of an application restart. + +--- + +`telemetry.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `batch-span` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `simple-span` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `telemetry.sdk.span.processor.queue_capacity` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `telemetry.sdk.span.processor.queue_capacity` | Gauge | `1` | The maximum number of spans the queue of a given instance of an SDK span processor can hold [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. diff --git a/model/telemetry/metrics.yaml b/model/telemetry/metrics.yaml index 5caa5ddc2d..dec70af657 100644 --- a/model/telemetry/metrics.yaml +++ b/model/telemetry/metrics.yaml @@ -19,7 +19,7 @@ groups: type: metric metric_name: telemetry.sdk.span.processor.queue_size stability: experimental - brief: "The number of spans in the queue of an instance of an SDK span processor" + brief: "The number of spans in the queue of a given instance of an SDK span processor" note: | Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. instrument: updowncounter @@ -28,6 +28,19 @@ groups: - ref: telemetry.sdk.processor.type - ref: telemetry.sdk.component.id + - id: metric.telemetry.sdk.span.processor.queue_capacity + type: metric + metric_name: telemetry.sdk.span.processor.queue_capacity + stability: experimental + brief: "The maximum number of spans the queue of a given instance of an SDK span processor can hold" + note: | + Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. + instrument: gauge + unit: "1" + attributes: + - ref: telemetry.sdk.processor.type + - ref: telemetry.sdk.component.id + - id: metric.telemetry.sdk.span.processor.spans_submitted type: metric metric_name: telemetry.sdk.span.processor.spans_submitted From 2f491df8d0a6baf5bb9f0f017f33d9c802e41d59 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Tue, 3 Dec 2024 12:10:12 +0100 Subject: [PATCH 11/41] Clarified meaning of submitted --- docs/telemetry/telemetry-sdk-metrics.md | 5 ++++- model/telemetry/metrics.yaml | 5 ++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/telemetry/telemetry-sdk-metrics.md b/docs/telemetry/telemetry-sdk-metrics.md index 6c77b9797f..1c5d94bd8a 100644 --- a/docs/telemetry/telemetry-sdk-metrics.md +++ b/docs/telemetry/telemetry-sdk-metrics.md @@ -169,7 +169,10 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.span.processor.spans_submitted` | Counter | `1` | The number of spans submitted for processing to this span processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.span.processor.spans_submitted` | Counter | `1` | The number of spans submitted for processing to this span processor. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** A span is considered submitted when the first callback has been called which triggers processing of the span for the given processor. +For the Batching and Simple Span Processors this metric therefore MUST be incremented on invocations of the `on_end` span processor callback. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/model/telemetry/metrics.yaml b/model/telemetry/metrics.yaml index dec70af657..4960b803ea 100644 --- a/model/telemetry/metrics.yaml +++ b/model/telemetry/metrics.yaml @@ -45,7 +45,10 @@ groups: type: metric metric_name: telemetry.sdk.span.processor.spans_submitted stability: experimental - brief: "The number of spans submitted for processing to this span processor" + brief: "The number of spans submitted for processing to this span processor." + note: | + A span is considered submitted when the first callback has been called which triggers processing of the span for the given processor. + For the Batching and Simple Span Processors this metric therefore MUST be incremented on invocations of the `on_end` span processor callback. instrument: counter unit: "1" attributes: From 1388eac103981ef5be772a0c400946022f8319d6 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Tue, 3 Dec 2024 12:15:46 +0100 Subject: [PATCH 12/41] replaced spans_failed with spans_processed metric --- docs/telemetry/telemetry-sdk-metrics.md | 22 +++++++++++++--------- model/telemetry/metrics.yaml | 18 +++++++++++------- 2 files changed, 24 insertions(+), 16 deletions(-) diff --git a/docs/telemetry/telemetry-sdk-metrics.md b/docs/telemetry/telemetry-sdk-metrics.md index 1c5d94bd8a..d07a08936d 100644 --- a/docs/telemetry/telemetry-sdk-metrics.md +++ b/docs/telemetry/telemetry-sdk-metrics.md @@ -18,9 +18,9 @@ This document describes metrics emitted by the OpenTelemetry SDK components them - [Metric: `telemetry.sdk.span.processor.queue_size`](#metric-telemetrysdkspanprocessorqueue_size) - [Metric: `telemetry.sdk.span.processor.queue_capacity`](#metric-telemetrysdkspanprocessorqueue_capacity) - [Metric: `telemetry.sdk.span.processor.spans_submitted`](#metric-telemetrysdkspanprocessorspans_submitted) - - [Metric: `telemetry.sdk.span.processor.spans_failed`](#metric-telemetrysdkspanprocessorspans_failed) + - [Metric: `telemetry.sdk.span.processor.spans_processed`](#metric-telemetrysdkspanprocessorspans_processed) - [Metric: `telemetry.sdk.span.exporter.spans_submitted`](#metric-telemetrysdkspanexporterspans_submitted) - - [Metric: `telemetry.sdk.span.exporter.spans_failed`](#metric-telemetrysdkspanexporterspans_failed) + - [Metric: `telemetry.sdk.span.exporter.spans_processed`](#metric-telemetrysdkspanexporterspans_processed) @@ -202,11 +202,11 @@ These values will therefore be reused in the case of an application restart. -### Metric: `telemetry.sdk.span.processor.spans_failed` +### Metric: `telemetry.sdk.span.processor.spans_processed` This metric is [recommended][MetricRecommended]. - + @@ -215,7 +215,9 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.span.processor.spans_failed` | Counter | `1` | The number of spans which could not be successfully processed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.span.processor.spans_processed` | Counter | `1` | The number of spans for which the processing has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** For successful processing, `error.type` must be empty. For failed processing, `error.type` must contain the failure cause. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -287,7 +289,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.span.exporter.spans_submitted` | Counter | `1` | The number of spans submitted for export | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.span.exporter.spans_submitted` | Counter | `1` | The number of spans for which the `export` callback of the exporter has been invoked. This does not require the export of the span to have finished yet. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -318,11 +320,11 @@ These values will therefore be reused in the case of an application restart. -### Metric: `telemetry.sdk.span.exporter.spans_failed` +### Metric: `telemetry.sdk.span.exporter.spans_processed` This metric is [recommended][MetricRecommended]. - + @@ -331,7 +333,9 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.span.exporter.spans_failed` | Counter | `1` | The number of spans which could not be successfully exported | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.span.exporter.spans_processed` | Counter | `1` | The number of spans for which the export has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/model/telemetry/metrics.yaml b/model/telemetry/metrics.yaml index 4960b803ea..7b1cf466ec 100644 --- a/model/telemetry/metrics.yaml +++ b/model/telemetry/metrics.yaml @@ -55,11 +55,13 @@ groups: - ref: telemetry.sdk.processor.type - ref: telemetry.sdk.component.id - - id: metric.telemetry.sdk.span.processor.spans_failed + - id: metric.telemetry.sdk.span.processor.spans_processed type: metric - metric_name: telemetry.sdk.span.processor.spans_failed + metric_name: telemetry.sdk.span.processor.spans_processed stability: experimental - brief: "The number of spans which could not be successfully processed" + brief: "The number of spans for which the processing has finished, either successful or failed" + note: | + For successful processing, `error.type` must be empty. For failed processing, `error.type` must contain the failure cause. instrument: counter unit: "1" attributes: @@ -74,18 +76,20 @@ groups: type: metric metric_name: telemetry.sdk.span.exporter.spans_submitted stability: experimental - brief: "The number of spans submitted for export" + brief: "The number of spans for which the `export` callback of the exporter has been invoked. This does not require the export of the span to have finished yet." instrument: counter unit: "1" attributes: - ref: telemetry.sdk.exporter.type - ref: telemetry.sdk.component.id - - id: metric.telemetry.sdk.span.exporter.spans_failed + - id: metric.telemetry.sdk.span.exporter.spans_processed type: metric - metric_name: telemetry.sdk.span.exporter.spans_failed + metric_name: telemetry.sdk.span.exporter.spans_processed stability: experimental - brief: "The number of spans which could not be successfully exported" + brief: "The number of spans for which the export has finished, either successful or failed" + note: | + For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. instrument: counter unit: "1" attributes: From 2c60a71bd243dbcf4c808012790e62262a4f3bd8 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Tue, 3 Dec 2024 12:20:03 +0100 Subject: [PATCH 13/41] Tried clarifying elemetry.sdk.component.id --- docs/attributes-registry/telemetry.md | 6 ++--- docs/telemetry/telemetry-sdk-metrics.md | 36 ++++++++++++------------- model/telemetry/registry.yaml | 6 ++--- 3 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/attributes-registry/telemetry.md b/docs/attributes-registry/telemetry.md index babd0aebbc..6600387fbf 100644 --- a/docs/attributes-registry/telemetry.md +++ b/docs/attributes-registry/telemetry.md @@ -24,12 +24,12 @@ This document defines attributes for telemetry SDK. **[1] `telemetry.distro.name`:** Official auto instrumentation agents and distributions SHOULD set the `telemetry.distro.name` attribute to a string starting with `opentelemetry-`, e.g. `opentelemetry-java-instrumentation`. -**[2] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, -the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. +**[2] `telemetry.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, +the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an -instance of the given component type is created. +instance of the given component type is started. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. diff --git a/docs/telemetry/telemetry-sdk-metrics.md b/docs/telemetry/telemetry-sdk-metrics.md index d07a08936d..03bf50d52d 100644 --- a/docs/telemetry/telemetry-sdk-metrics.md +++ b/docs/telemetry/telemetry-sdk-metrics.md @@ -88,12 +88,12 @@ This metric is [recommended][MetricRecommended]. | [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`telemetry.sdk.processor.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, -the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. +**[1] `telemetry.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, +the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an -instance of the given component type is created. +instance of the given component type is started. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. @@ -133,12 +133,12 @@ This metric is [recommended][MetricRecommended]. | [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`telemetry.sdk.processor.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, -the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. +**[1] `telemetry.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, +the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an -instance of the given component type is created. +instance of the given component type is started. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. @@ -179,12 +179,12 @@ For the Batching and Simple Span Processors this metric therefore MUST be increm | [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`telemetry.sdk.processor.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, -the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. +**[1] `telemetry.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, +the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an -instance of the given component type is created. +instance of the given component type is started. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. @@ -245,12 +245,12 @@ it's RECOMMENDED to: - Use a domain-specific attribute - Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. -**[2] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, -the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. +**[2] `telemetry.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, +the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an -instance of the given component type is created. +instance of the given component type is started. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. @@ -296,12 +296,12 @@ This metric is [recommended][MetricRecommended]. | [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`telemetry.sdk.exporter.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK exporter. | `otlp-grpc`; `jaeger` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, -the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. +**[1] `telemetry.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, +the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an -instance of the given component type is created. +instance of the given component type is started. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. @@ -363,12 +363,12 @@ it's RECOMMENDED to: - Use a domain-specific attribute - Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. -**[2] `telemetry.sdk.component.id`:** The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, -the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. +**[2] `telemetry.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, +the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an -instance of the given component type is created. +instance of the given component type is started. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. diff --git a/model/telemetry/registry.yaml b/model/telemetry/registry.yaml index f5ffaf0eef..ef0d8f99e9 100644 --- a/model/telemetry/registry.yaml +++ b/model/telemetry/registry.yaml @@ -126,12 +126,12 @@ groups: brief: > A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. note: | - The SDK MAY allow users to provide an id for the component instances. If no id is provided by the user, - the SDK SHOULD automatically assign an id. Because this attribute is used in metrics, the SDK MUST ensure a low cardinality in that case. + The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, + the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an - instance of the given component type is created. + instance of the given component type is started. For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. examples: ["batch-span-0", "custom-name"] From 67ab2d072c228fcb5dbb7873bbe0e02c6f769619 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Tue, 14 Jan 2025 10:22:35 +0100 Subject: [PATCH 14/41] Moved from telemetry. to otel. namespace --- docs/attributes-registry/otel.md | 39 +++++ docs/attributes-registry/telemetry.md | 35 +---- .../sdk-metrics.md} | 138 +++++++++--------- model/{telemetry => otel}/metrics.yaml | 72 ++++----- model/otel/registry.yaml | 59 ++++++++ model/telemetry/registry.yaml | 54 ------- 6 files changed, 205 insertions(+), 192 deletions(-) rename docs/{telemetry/telemetry-sdk-metrics.md => otel/sdk-metrics.md} (61%) rename model/{telemetry => otel}/metrics.yaml (59%) diff --git a/docs/attributes-registry/otel.md b/docs/attributes-registry/otel.md index 2c236b530e..4509f73b97 100644 --- a/docs/attributes-registry/otel.md +++ b/docs/attributes-registry/otel.md @@ -8,6 +8,7 @@ - [OTel Attributes](#otel-attributes) - [OTel Scope Attributes](#otel-scope-attributes) +- [OTel Scope Attributes](#otel-scope-attributes) - [Deprecated OTel Library Attributes](#deprecated-otel-library-attributes) ## OTel Attributes @@ -37,6 +38,44 @@ Attributes used by non-OTLP exporters to represent OpenTelemetry Scope's concept | `otel.scope.name` | string | The name of the instrumentation scope - (`InstrumentationScope.Name` in OTLP). | `io.opentelemetry.contrib.mongodb` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `otel.scope.version` | string | The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). | `1.0.0` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +## OTel Scope Attributes + +Attributes used for OpenTelemetry SDK self-monitoring + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `otel.sdk.component.id` | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.exporter.type` | string | A name identifying the type of the OpenTelemetry SDK exporter. | `otlp-grpc`; `jaeger` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.processor.type` | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `otel.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, +the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. +E.g. it MUST NOT use a UUID. +It instead MAY do that by using the following pattern as value: `-`: +Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an +instance of the given component type is started. +For example, the first Batch Span Processor will have `batch-span-0` as `otel.sdk.component.id`, the second one `batch-span-1` and so one. +These values will therefore be reused in the case of an application restart. + +--- + +`otel.sdk.exporter.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `otlp-grpc` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp-http` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp-http-json` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +--- + +`otel.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `batch-span` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `simple-span` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + ## Deprecated OTel Library Attributes Describes deprecated otel.library attributes. diff --git a/docs/attributes-registry/telemetry.md b/docs/attributes-registry/telemetry.md index 6600387fbf..7c92cc2430 100644 --- a/docs/attributes-registry/telemetry.md +++ b/docs/attributes-registry/telemetry.md @@ -14,26 +14,14 @@ This document defines attributes for telemetry SDK. |---|---|---|---|---| | `telemetry.distro.name` | string | The name of the auto instrumentation agent or distribution, if used. [1] | `parts-unlimited-java` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `telemetry.distro.version` | string | The version string of the auto instrumentation agent or distribution, if used. | `1.2.3` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `telemetry.sdk.component.id` | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `telemetry.sdk.exporter.type` | string | A name identifying the type of the OpenTelemetry SDK exporter. | `otlp-grpc`; `jaeger` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `telemetry.sdk.language` | string | The language of the telemetry SDK. | `cpp`; `dotnet`; `erlang` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. [3] | `opentelemetry` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `telemetry.sdk.processor.type` | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. [2] | `opentelemetry` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `telemetry.sdk.version` | string | The version string of the telemetry SDK. | `1.2.3` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1] `telemetry.distro.name`:** Official auto instrumentation agents and distributions SHOULD set the `telemetry.distro.name` attribute to a string starting with `opentelemetry-`, e.g. `opentelemetry-java-instrumentation`. -**[2] `telemetry.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, -the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. -E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: -Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an -instance of the given component type is started. -For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. -These values will therefore be reused in the case of an application restart. - -**[3] `telemetry.sdk.name`:** The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`. +**[2] `telemetry.sdk.name`:** The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`. If another SDK, like a fork or a vendor-provided implementation, is used, this SDK MUST set the `telemetry.sdk.name` attribute to the fully-qualified class or module name of this SDK's main entry point or another suitable identifier depending on the language. @@ -42,16 +30,6 @@ All custom identifiers SHOULD be stable across different versions of an implemen --- -`telemetry.sdk.exporter.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -|---|---|---| -| `otlp-grpc` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp-http` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp-http-json` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - ---- - `telemetry.sdk.language` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | @@ -68,12 +46,3 @@ All custom identifiers SHOULD be stable across different versions of an implemen | `rust` | rust | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `swift` | swift | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `webjs` | webjs | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - ---- - -`telemetry.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -|---|---|---| -| `batch-span` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `simple-span` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/telemetry/telemetry-sdk-metrics.md b/docs/otel/sdk-metrics.md similarity index 61% rename from docs/telemetry/telemetry-sdk-metrics.md rename to docs/otel/sdk-metrics.md index 03bf50d52d..d63fadd85e 100644 --- a/docs/telemetry/telemetry-sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -4,7 +4,7 @@ linkTitle: SDK Metrics # Semantic Conventions for OpenTelemetry SDK metrics -**Status**: [Experimental][DocumentStatus] +**Status**: [Development][DocumentStatus] This document describes metrics emitted by the OpenTelemetry SDK components themselves about their internal state. @@ -13,24 +13,24 @@ This document describes metrics emitted by the OpenTelemetry SDK components them - [Span Metrics](#span-metrics) - - [Metric: `telemetry.sdk.span.ended_count`](#metric-telemetrysdkspanended_count) - - [Metric: `telemetry.sdk.span.sampled_count`](#metric-telemetrysdkspansampled_count) - - [Metric: `telemetry.sdk.span.processor.queue_size`](#metric-telemetrysdkspanprocessorqueue_size) - - [Metric: `telemetry.sdk.span.processor.queue_capacity`](#metric-telemetrysdkspanprocessorqueue_capacity) - - [Metric: `telemetry.sdk.span.processor.spans_submitted`](#metric-telemetrysdkspanprocessorspans_submitted) - - [Metric: `telemetry.sdk.span.processor.spans_processed`](#metric-telemetrysdkspanprocessorspans_processed) - - [Metric: `telemetry.sdk.span.exporter.spans_submitted`](#metric-telemetrysdkspanexporterspans_submitted) - - [Metric: `telemetry.sdk.span.exporter.spans_processed`](#metric-telemetrysdkspanexporterspans_processed) + - [Metric: `otel.sdk.span.ended_count`](#metric-otelsdkspanended_count) + - [Metric: `otel.sdk.span.sampled_count`](#metric-otelsdkspansampled_count) + - [Metric: `otel.sdk.span.processor.queue_size`](#metric-otelsdkspanprocessorqueue_size) + - [Metric: `otel.sdk.span.processor.queue_capacity`](#metric-otelsdkspanprocessorqueue_capacity) + - [Metric: `otel.sdk.span.processor.spans_submitted`](#metric-otelsdkspanprocessorspans_submitted) + - [Metric: `otel.sdk.span.processor.spans_processed`](#metric-otelsdkspanprocessorspans_processed) + - [Metric: `otel.sdk.span.exporter.spans_submitted`](#metric-otelsdkspanexporterspans_submitted) + - [Metric: `otel.sdk.span.exporter.spans_processed`](#metric-otelsdkspanexporterspans_processed) ## Span Metrics -### Metric: `telemetry.sdk.span.ended_count` +### Metric: `otel.sdk.span.ended_count` This metric is [recommended][MetricRecommended]. - + @@ -39,18 +39,18 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.span.ended_count` | Counter | `1` | The number of spans which have been ended | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.ended_count` | Counter | `1` | The number of spans which have been ended | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -### Metric: `telemetry.sdk.span.sampled_count` +### Metric: `otel.sdk.span.sampled_count` This metric is [recommended][MetricRecommended]. - + @@ -59,18 +59,18 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.span.sampled_count` | Counter | `1` | The number of spans which have been ended AND are sampled | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.sampled_count` | Counter | `1` | The number of spans which have been ended AND are sampled | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -### Metric: `telemetry.sdk.span.processor.queue_size` +### Metric: `otel.sdk.span.processor.queue_size` This metric is [recommended][MetricRecommended]. - + @@ -79,27 +79,27 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.span.processor.queue_size` | UpDownCounter | `1` | The number of spans in the queue of a given instance of an SDK span processor [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.processor.queue_size` | UpDownCounter | `1` | The number of spans in the queue of a given instance of an SDK span processor [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`telemetry.sdk.processor.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.id`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.processor.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `telemetry.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, +**[1] `otel.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: +It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. +For example, the first Batch Span Processor will have `batch-span-0` as `otel.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. --- -`telemetry.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +`otel.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| @@ -111,11 +111,11 @@ These values will therefore be reused in the case of an application restart. -### Metric: `telemetry.sdk.span.processor.queue_capacity` +### Metric: `otel.sdk.span.processor.queue_capacity` This metric is [recommended][MetricRecommended]. - + @@ -124,27 +124,27 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.span.processor.queue_capacity` | Gauge | `1` | The maximum number of spans the queue of a given instance of an SDK span processor can hold [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.processor.queue_capacity` | Gauge | `1` | The maximum number of spans the queue of a given instance of an SDK span processor can hold [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`telemetry.sdk.processor.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.id`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.processor.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `telemetry.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, +**[1] `otel.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: +It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. +For example, the first Batch Span Processor will have `batch-span-0` as `otel.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. --- -`telemetry.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +`otel.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| @@ -156,11 +156,11 @@ These values will therefore be reused in the case of an application restart. -### Metric: `telemetry.sdk.span.processor.spans_submitted` +### Metric: `otel.sdk.span.processor.spans_submitted` This metric is [recommended][MetricRecommended]. - + @@ -169,28 +169,28 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.span.processor.spans_submitted` | Counter | `1` | The number of spans submitted for processing to this span processor. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.processor.spans_submitted` | Counter | `1` | The number of spans submitted for processing to this span processor. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** A span is considered submitted when the first callback has been called which triggers processing of the span for the given processor. For the Batching and Simple Span Processors this metric therefore MUST be incremented on invocations of the `on_end` span processor callback. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`telemetry.sdk.processor.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.id`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.processor.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `telemetry.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, +**[1] `otel.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: +It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. +For example, the first Batch Span Processor will have `batch-span-0` as `otel.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. --- -`telemetry.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +`otel.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| @@ -202,11 +202,11 @@ These values will therefore be reused in the case of an application restart. -### Metric: `telemetry.sdk.span.processor.spans_processed` +### Metric: `otel.sdk.span.processor.spans_processed` This metric is [recommended][MetricRecommended]. - + @@ -215,15 +215,15 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.span.processor.spans_processed` | Counter | `1` | The number of spans for which the processing has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.processor.spans_processed` | Counter | `1` | The number of spans for which the processing has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** For successful processing, `error.type` must be empty. For failed processing, `error.type` must contain the failure cause. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`error.type`](/docs/attributes-registry/error.md) | string | A low-cardinality description of the failure reason. SDK Batching Span Processors MUST use `queue full` for spans dropped due to a full queue. [1] | `queue full` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`telemetry.sdk.processor.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.id`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.processor.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. @@ -245,13 +245,13 @@ it's RECOMMENDED to: - Use a domain-specific attribute - Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. -**[2] `telemetry.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, +**[2] `otel.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: +It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. +For example, the first Batch Span Processor will have `batch-span-0` as `otel.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. --- @@ -264,7 +264,7 @@ These values will therefore be reused in the case of an application restart. --- -`telemetry.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +`otel.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| @@ -276,11 +276,11 @@ These values will therefore be reused in the case of an application restart. -### Metric: `telemetry.sdk.span.exporter.spans_submitted` +### Metric: `otel.sdk.span.exporter.spans_submitted` This metric is [recommended][MetricRecommended]. - + @@ -289,25 +289,25 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.span.exporter.spans_submitted` | Counter | `1` | The number of spans for which the `export` callback of the exporter has been invoked. This does not require the export of the span to have finished yet. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.exporter.spans_submitted` | Counter | `1` | The number of spans for which the `export` callback of the exporter has been invoked. This does not require the export of the span to have finished yet. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`telemetry.sdk.exporter.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK exporter. | `otlp-grpc`; `jaeger` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.id`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.exporter.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK exporter. | `otlp-grpc`; `jaeger` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `telemetry.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, +**[1] `otel.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: +It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. +For example, the first Batch Span Processor will have `batch-span-0` as `otel.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. --- -`telemetry.sdk.exporter.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +`otel.sdk.exporter.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| @@ -320,11 +320,11 @@ These values will therefore be reused in the case of an application restart. -### Metric: `telemetry.sdk.span.exporter.spans_processed` +### Metric: `otel.sdk.span.exporter.spans_processed` This metric is [recommended][MetricRecommended]. - + @@ -333,15 +333,15 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `telemetry.sdk.span.exporter.spans_processed` | Counter | `1` | The number of spans for which the export has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.exporter.spans_processed` | Counter | `1` | The number of spans for which the export has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`telemetry.sdk.component.id`](/docs/attributes-registry/telemetry.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`telemetry.sdk.exporter.type`](/docs/attributes-registry/telemetry.md) | string | A name identifying the type of the OpenTelemetry SDK exporter. | `otlp-grpc`; `jaeger` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.id`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.exporter.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK exporter. | `otlp-grpc`; `jaeger` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. @@ -363,13 +363,13 @@ it's RECOMMENDED to: - Use a domain-specific attribute - Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. -**[2] `telemetry.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, +**[2] `otel.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: +It instead MAY do that by using the following pattern as value: `-`: Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. +For example, the first Batch Span Processor will have `batch-span-0` as `otel.sdk.component.id`, the second one `batch-span-1` and so one. These values will therefore be reused in the case of an application restart. --- @@ -382,7 +382,7 @@ These values will therefore be reused in the case of an application restart. --- -`telemetry.sdk.exporter.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +`otel.sdk.exporter.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| diff --git a/model/telemetry/metrics.yaml b/model/otel/metrics.yaml similarity index 59% rename from model/telemetry/metrics.yaml rename to model/otel/metrics.yaml index 7b1cf466ec..0bfbb66aab 100644 --- a/model/telemetry/metrics.yaml +++ b/model/otel/metrics.yaml @@ -1,50 +1,50 @@ groups: - - id: metric.telemetry.sdk.span.ended_count + - id: metric.otel.sdk.span.ended_count type: metric - metric_name: telemetry.sdk.span.ended_count - stability: experimental + metric_name: otel.sdk.span.ended_count + stability: development brief: "The number of spans which have been ended" instrument: counter unit: "1" - - id: metric.telemetry.sdk.span.sampled_count + - id: metric.otel.sdk.span.sampled_count type: metric - metric_name: telemetry.sdk.span.sampled_count - stability: experimental + metric_name: otel.sdk.span.sampled_count + stability: development brief: "The number of spans which have been ended AND are sampled" instrument: counter unit: "1" - - id: metric.telemetry.sdk.span.processor.queue_size + - id: metric.otel.sdk.span.processor.queue_size type: metric - metric_name: telemetry.sdk.span.processor.queue_size - stability: experimental + metric_name: otel.sdk.span.processor.queue_size + stability: development brief: "The number of spans in the queue of a given instance of an SDK span processor" note: | Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. instrument: updowncounter unit: "1" attributes: - - ref: telemetry.sdk.processor.type - - ref: telemetry.sdk.component.id + - ref: otel.sdk.processor.type + - ref: otel.sdk.component.id - - id: metric.telemetry.sdk.span.processor.queue_capacity + - id: metric.otel.sdk.span.processor.queue_capacity type: metric - metric_name: telemetry.sdk.span.processor.queue_capacity - stability: experimental + metric_name: otel.sdk.span.processor.queue_capacity + stability: development brief: "The maximum number of spans the queue of a given instance of an SDK span processor can hold" note: | Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. instrument: gauge unit: "1" attributes: - - ref: telemetry.sdk.processor.type - - ref: telemetry.sdk.component.id + - ref: otel.sdk.processor.type + - ref: otel.sdk.component.id - - id: metric.telemetry.sdk.span.processor.spans_submitted + - id: metric.otel.sdk.span.processor.spans_submitted type: metric - metric_name: telemetry.sdk.span.processor.spans_submitted - stability: experimental + metric_name: otel.sdk.span.processor.spans_submitted + stability: development brief: "The number of spans submitted for processing to this span processor." note: | A span is considered submitted when the first callback has been called which triggers processing of the span for the given processor. @@ -52,47 +52,47 @@ groups: instrument: counter unit: "1" attributes: - - ref: telemetry.sdk.processor.type - - ref: telemetry.sdk.component.id + - ref: otel.sdk.processor.type + - ref: otel.sdk.component.id - - id: metric.telemetry.sdk.span.processor.spans_processed + - id: metric.otel.sdk.span.processor.spans_processed type: metric - metric_name: telemetry.sdk.span.processor.spans_processed - stability: experimental + metric_name: otel.sdk.span.processor.spans_processed + stability: development brief: "The number of spans for which the processing has finished, either successful or failed" note: | For successful processing, `error.type` must be empty. For failed processing, `error.type` must contain the failure cause. instrument: counter unit: "1" attributes: - - ref: telemetry.sdk.processor.type - - ref: telemetry.sdk.component.id + - ref: otel.sdk.processor.type + - ref: otel.sdk.component.id - ref: error.type brief: > A low-cardinality description of the failure reason. SDK Batching Span Processors MUST use `queue full` for spans dropped due to a full queue. examples: ["queue full"] - - id: metric.telemetry.sdk.span.exporter.spans_submitted + - id: metric.otel.sdk.span.exporter.spans_submitted type: metric - metric_name: telemetry.sdk.span.exporter.spans_submitted - stability: experimental + metric_name: otel.sdk.span.exporter.spans_submitted + stability: development brief: "The number of spans for which the `export` callback of the exporter has been invoked. This does not require the export of the span to have finished yet." instrument: counter unit: "1" attributes: - - ref: telemetry.sdk.exporter.type - - ref: telemetry.sdk.component.id + - ref: otel.sdk.exporter.type + - ref: otel.sdk.component.id - - id: metric.telemetry.sdk.span.exporter.spans_processed + - id: metric.otel.sdk.span.exporter.spans_processed type: metric - metric_name: telemetry.sdk.span.exporter.spans_processed - stability: experimental + metric_name: otel.sdk.span.exporter.spans_processed + stability: development brief: "The number of spans for which the export has finished, either successful or failed" note: | For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. instrument: counter unit: "1" attributes: - - ref: telemetry.sdk.exporter.type - - ref: telemetry.sdk.component.id + - ref: otel.sdk.exporter.type + - ref: otel.sdk.component.id - ref: error.type diff --git a/model/otel/registry.yaml b/model/otel/registry.yaml index 01b1a19a8c..61736e4106 100644 --- a/model/otel/registry.yaml +++ b/model/otel/registry.yaml @@ -37,3 +37,62 @@ groups: brief: The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). examples: ['1.0.0'] stability: stable + - id: registry.otel.sdk.telemetry + type: attribute_group + display_name: OTel Scope Attributes + brief: Attributes used for OpenTelemetry SDK self-monitoring + attributes: + - id: otel.sdk.processor.type + type: + members: + - id: batch_span + value: "batch-span" + brief: > + The builtin SDK Batching Span Processor + stability: development + - id: simple_span + value: "simple-span" + brief: > + The builtin SDK Simple Span Processor + stability: development + stability: development + brief: > + A name identifying the type of the OpenTelemetry SDK processor. + examples: ["batch-span", "MyCustomProcessor"] + - id: otel.sdk.exporter.type + type: + members: + - id: otlp_grpc + value: "otlp-grpc" + brief: > + OTLP exporter over gRPC with protobuf serialization + stability: development + - id: otlp_http + value: "otlp-http" + brief: > + OTLP exporter over HTTP with protobuf serialization + stability: development + - id: otlp_http_json + value: "otlp-http-json" + brief: > + OTLP exporter over HTTP with JSON serialization + stability: development + stability: development + brief: > + A name identifying the type of the OpenTelemetry SDK exporter. + examples: ["otlp-grpc", "jaeger"] + - id: otel.sdk.component.id + type: string + stability: development + brief: > + A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. + note: | + The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, + the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. + E.g. it MUST NOT use a UUID. + It instead MAY do that by using the following pattern as value: `-`: + Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an + instance of the given component type is started. + For example, the first Batch Span Processor will have `batch-span-0` as `otel.sdk.component.id`, the second one `batch-span-1` and so one. + These values will therefore be reused in the case of an application restart. + examples: ["batch-span-0", "custom-name"] diff --git a/model/telemetry/registry.yaml b/model/telemetry/registry.yaml index ef0d8f99e9..2cf3937501 100644 --- a/model/telemetry/registry.yaml +++ b/model/telemetry/registry.yaml @@ -81,57 +81,3 @@ groups: brief: > The version string of the auto instrumentation agent or distribution, if used. examples: ["1.2.3"] - - id: telemetry.sdk.processor.type - type: - members: - - id: batch_span - value: "batch-span" - brief: > - The builtin SDK Batching Span Processor - stability: experimental - - id: simple_span - value: "simple-span" - brief: > - The builtin SDK Simple Span Processor - stability: experimental - stability: experimental - brief: > - A name identifying the type of the OpenTelemetry SDK processor. - examples: ["batch-span", "MyCustomProcessor"] - - id: telemetry.sdk.exporter.type - type: - members: - - id: otlp_grpc - value: "otlp-grpc" - brief: > - OTLP exporter over gRPC with protobuf serialization - stability: experimental - - id: otlp_http - value: "otlp-http" - brief: > - OTLP exporter over HTTP with protobuf serialization - stability: experimental - - id: otlp_http_json - value: "otlp-http-json" - brief: > - OTLP exporter over HTTP with JSON serialization - stability: experimental - stability: experimental - brief: > - A name identifying the type of the OpenTelemetry SDK exporter. - examples: ["otlp-grpc", "jaeger"] - - id: telemetry.sdk.component.id - type: string - stability: experimental - brief: > - A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. - note: | - The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, - the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. - E.g. it MUST NOT use a UUID. - It instead MAY do that by using the following pattern as value: `-`: - Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an - instance of the given component type is started. - For example, the first Batch Span Processor will have `batch-span-0` as `telemetry.sdk.component.id`, the second one `batch-span-1` and so one. - These values will therefore be reused in the case of an application restart. - examples: ["batch-span-0", "custom-name"] From 598636f6b3271585f0d2b603d3b6856abd2b07f1 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Tue, 14 Jan 2025 10:23:44 +0100 Subject: [PATCH 15/41] mend --- .../{sdk-telemetry-span-metrics.yaml => sdk-span-metrics.yaml} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename .chloggen/{sdk-telemetry-span-metrics.yaml => sdk-span-metrics.yaml} (97%) diff --git a/.chloggen/sdk-telemetry-span-metrics.yaml b/.chloggen/sdk-span-metrics.yaml similarity index 97% rename from .chloggen/sdk-telemetry-span-metrics.yaml rename to .chloggen/sdk-span-metrics.yaml index 729f87248c..360ea4f2c4 100644 --- a/.chloggen/sdk-telemetry-span-metrics.yaml +++ b/.chloggen/sdk-span-metrics.yaml @@ -7,7 +7,7 @@ change_type: 'enhancement' # The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) -component: 'telemetry' +component: 'otel' # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). note: Adds SDK self-monitoring metrics for span processing From b0fd83db65a826a9d6394a7fe0dd44963d046900 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Tue, 14 Jan 2025 11:14:37 +0100 Subject: [PATCH 16/41] Rename spans_submitted to spans_exported --- docs/otel/sdk-metrics.md | 22 +++++++++++----------- model/otel/metrics.yaml | 4 ++-- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index d63fadd85e..26a32affe3 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -13,14 +13,14 @@ This document describes metrics emitted by the OpenTelemetry SDK components them - [Span Metrics](#span-metrics) - - [Metric: `otel.sdk.span.ended_count`](#metric-otelsdkspanended_count) - - [Metric: `otel.sdk.span.sampled_count`](#metric-otelsdkspansampled_count) - - [Metric: `otel.sdk.span.processor.queue_size`](#metric-otelsdkspanprocessorqueue_size) - - [Metric: `otel.sdk.span.processor.queue_capacity`](#metric-otelsdkspanprocessorqueue_capacity) - - [Metric: `otel.sdk.span.processor.spans_submitted`](#metric-otelsdkspanprocessorspans_submitted) - - [Metric: `otel.sdk.span.processor.spans_processed`](#metric-otelsdkspanprocessorspans_processed) - - [Metric: `otel.sdk.span.exporter.spans_submitted`](#metric-otelsdkspanexporterspans_submitted) - - [Metric: `otel.sdk.span.exporter.spans_processed`](#metric-otelsdkspanexporterspans_processed) + - [Metric: `otel.sdk.span.ended_count`](#metric-telemetrysdkspanended_count) + - [Metric: `otel.sdk.span.sampled_count`](#metric-telemetrysdkspansampled_count) + - [Metric: `otel.sdk.span.processor.queue_size`](#metric-telemetrysdkspanprocessorqueue_size) + - [Metric: `otel.sdk.span.processor.queue_capacity`](#metric-telemetrysdkspanprocessorqueue_capacity) + - [Metric: `otel.sdk.span.processor.spans_submitted`](#metric-telemetrysdkspanprocessorspans_submitted) + - [Metric: `otel.sdk.span.processor.spans_processed`](#metric-telemetrysdkspanprocessorspans_processed) + - [Metric: `otel.sdk.span.exporter.spans_exported`](#metric-telemetrysdkspanexporterspans_exported) + - [Metric: `otel.sdk.span.exporter.spans_processed`](#metric-telemetrysdkspanexporterspans_processed) @@ -276,11 +276,11 @@ These values will therefore be reused in the case of an application restart. -### Metric: `otel.sdk.span.exporter.spans_submitted` +### Metric: `otel.sdk.span.exporter.spans_exported` This metric is [recommended][MetricRecommended]. - + @@ -289,7 +289,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.exporter.spans_submitted` | Counter | `1` | The number of spans for which the `export` callback of the exporter has been invoked. This does not require the export of the span to have finished yet. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.exporter.spans_exported` | Counter | `1` | The number of spans for which the `export` callback of the exporter has been invoked. This does not require the export of the span to have finished yet. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml index 0bfbb66aab..5b466f601a 100644 --- a/model/otel/metrics.yaml +++ b/model/otel/metrics.yaml @@ -83,9 +83,9 @@ groups: - ref: otel.sdk.exporter.type - ref: otel.sdk.component.id - - id: metric.otel.sdk.span.exporter.spans_processed + - id: metric.otel.sdk.span.exporter.spans_exported type: metric - metric_name: otel.sdk.span.exporter.spans_processed + metric_name: otel.sdk.span.exporter.spans_exported stability: development brief: "The number of spans for which the export has finished, either successful or failed" note: | From 27f76901f1203617726c592d037251ed26cf7fcb Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Tue, 14 Jan 2025 12:03:25 +0100 Subject: [PATCH 17/41] Cleanup metrics with review suggestions --- docs/attributes-registry/otel.md | 1 + docs/otel/sdk-metrics.md | 131 ++++++++++++++++++------------- model/otel/common.yaml | 2 +- model/otel/metrics.yaml | 57 ++++++++------ model/otel/registry.yaml | 4 + 5 files changed, 112 insertions(+), 83 deletions(-) diff --git a/docs/attributes-registry/otel.md b/docs/attributes-registry/otel.md index 4509f73b97..d243f8a2ec 100644 --- a/docs/attributes-registry/otel.md +++ b/docs/attributes-registry/otel.md @@ -17,6 +17,7 @@ Attributes reserved for OpenTelemetry | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| +| `otel.is_sampled` | boolean | The sampled trace flag of the span | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `otel.status_code` | string | Name of the code, either "OK" or "ERROR". MUST NOT be set if the status code is UNSET. | `OK`; `ERROR` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `otel.status_description` | string | Description of the Status if it has a value, otherwise not set. | `resource not found` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index 26a32affe3..95ff34ed03 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -13,24 +13,24 @@ This document describes metrics emitted by the OpenTelemetry SDK components them - [Span Metrics](#span-metrics) - - [Metric: `otel.sdk.span.ended_count`](#metric-telemetrysdkspanended_count) - - [Metric: `otel.sdk.span.sampled_count`](#metric-telemetrysdkspansampled_count) - - [Metric: `otel.sdk.span.processor.queue_size`](#metric-telemetrysdkspanprocessorqueue_size) - - [Metric: `otel.sdk.span.processor.queue_capacity`](#metric-telemetrysdkspanprocessorqueue_capacity) - - [Metric: `otel.sdk.span.processor.spans_submitted`](#metric-telemetrysdkspanprocessorspans_submitted) - - [Metric: `otel.sdk.span.processor.spans_processed`](#metric-telemetrysdkspanprocessorspans_processed) - - [Metric: `otel.sdk.span.exporter.spans_exported`](#metric-telemetrysdkspanexporterspans_exported) - - [Metric: `otel.sdk.span.exporter.spans_processed`](#metric-telemetrysdkspanexporterspans_processed) + - [Metric: `otel.sdk.span.created_count`](#metric-otelsdkspancreated_count) + - [Metric: `otel.sdk.span.live_count`](#metric-otelsdkspanlive_count) + - [Metric: `otel.sdk.span.ended_count`](#metric-otelsdkspanended_count) + - [Metric: `otel.sdk.span.processor.queue_size`](#metric-otelsdkspanprocessorqueue_size) + - [Metric: `otel.sdk.span.processor.queue_capacity`](#metric-otelsdkspanprocessorqueue_capacity) + - [Metric: `otel.sdk.span.processor.spans_processed`](#metric-otelsdkspanprocessorspans_processed) + - [Metric: `otel.sdk.span.exporter.spans_inflight`](#metric-otelsdkspanexporterspans_inflight) + - [Metric: `otel.sdk.span.exporter.spans_exported`](#metric-otelsdkspanexporterspans_exported) ## Span Metrics -### Metric: `otel.sdk.span.ended_count` +### Metric: `otel.sdk.span.created_count` This metric is [recommended][MetricRecommended]. - + @@ -39,18 +39,23 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.ended_count` | Counter | `1` | The number of spans which have been ended | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.created_count` | Counter | `1` | The number of spans which have been created | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`otel.is_sampled`](/docs/attributes-registry/otel.md) | boolean | The sampled trace flag of the span | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -### Metric: `otel.sdk.span.sampled_count` + +### Metric: `otel.sdk.span.live_count` This metric is [recommended][MetricRecommended]. - + @@ -59,18 +64,22 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.sampled_count` | Counter | `1` | The number of spans which have been ended AND are sampled | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.live_count` | UpDownCounter | `1` | The number of created spans for which the end operation has not been called yet | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`otel.is_sampled`](/docs/attributes-registry/otel.md) | boolean | The sampled trace flag of the span | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -### Metric: `otel.sdk.span.processor.queue_size` +### Metric: `otel.sdk.span.ended_count` This metric is [recommended][MetricRecommended]. - + @@ -79,43 +88,22 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.processor.queue_size` | UpDownCounter | `1` | The number of spans in the queue of a given instance of an SDK span processor [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. +| `otel.sdk.span.ended_count` | Counter | `1` | The number of created spans for which the end operation was called | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`otel.sdk.component.id`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`otel.sdk.processor.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1] `otel.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, -the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. -E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: -Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an -instance of the given component type is started. -For example, the first Batch Span Processor will have `batch-span-0` as `otel.sdk.component.id`, the second one `batch-span-1` and so one. -These values will therefore be reused in the case of an application restart. - ---- - -`otel.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -|---|---|---| -| `batch-span` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `simple-span` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.is_sampled`](/docs/attributes-registry/otel.md) | boolean | The sampled trace flag of the span | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -### Metric: `otel.sdk.span.processor.queue_capacity` +### Metric: `otel.sdk.span.processor.queue_size` This metric is [recommended][MetricRecommended]. - + @@ -124,7 +112,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.processor.queue_capacity` | Gauge | `1` | The maximum number of spans the queue of a given instance of an SDK span processor can hold [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.processor.queue_size` | UpDownCounter | `1` | The number of spans in the queue of a given instance of an SDK span processor [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. @@ -156,11 +144,11 @@ These values will therefore be reused in the case of an application restart. -### Metric: `otel.sdk.span.processor.spans_submitted` +### Metric: `otel.sdk.span.processor.queue_capacity` This metric is [recommended][MetricRecommended]. - + @@ -169,10 +157,9 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.processor.spans_submitted` | Counter | `1` | The number of spans submitted for processing to this span processor. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.processor.queue_capacity` | Gauge | `1` | The maximum number of spans the queue of a given instance of an SDK span processor can hold [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** A span is considered submitted when the first callback has been called which triggers processing of the span for the given processor. -For the Batching and Simple Span Processors this metric therefore MUST be incremented on invocations of the `on_end` span processor callback. +**[1]:** Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -218,10 +205,11 @@ This metric is [recommended][MetricRecommended]. | `otel.sdk.span.processor.spans_processed` | Counter | `1` | The number of spans for which the processing has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** For successful processing, `error.type` must be empty. For failed processing, `error.type` must contain the failure cause. +For the SDK Simple and Batching Span Processor a span is considered to be processed already when it has been submitted to the exporter, not when the corresponding export call has finished. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`error.type`](/docs/attributes-registry/error.md) | string | A low-cardinality description of the failure reason. SDK Batching Span Processors MUST use `queue full` for spans dropped due to a full queue. [1] | `queue full` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`error.type`](/docs/attributes-registry/error.md) | string | A low-cardinality description of the failure reason. SDK Batching Span Processors MUST use `queue_full` for spans dropped due to a full queue. [1] | `queue_full` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`otel.sdk.component.id`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`otel.sdk.processor.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -276,11 +264,11 @@ These values will therefore be reused in the case of an application restart. -### Metric: `otel.sdk.span.exporter.spans_exported` +### Metric: `otel.sdk.span.exporter.spans_inflight` This metric is [recommended][MetricRecommended]. - + @@ -289,14 +277,37 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.exporter.spans_exported` | Counter | `1` | The number of spans for which the `export` callback of the exporter has been invoked. This does not require the export of the span to have finished yet. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.exporter.spans_inflight` | UpDownCounter | `1` | The number of spans which were passed to the exporter, but that have not been exported yet (neither successful, nor failed) [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`otel.sdk.component.id`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`otel.sdk.component.id`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`otel.sdk.exporter.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK exporter. | `otlp-grpc`; `jaeger` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `otel.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, +**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. + +When `error.type` is set to a type (e.g., an exception type), its +canonical class name identifying the type within the artifact SHOULD be used. + +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low. +Telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time when no +additional filters are applied. + +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + +If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), +it's RECOMMENDED to: + +- Use a domain-specific attribute +- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. + +**[2] `otel.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. E.g. it MUST NOT use a UUID. It instead MAY do that by using the following pattern as value: `-`: @@ -307,6 +318,14 @@ These values will therefore be reused in the case of an application restart. --- +`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +--- + `otel.sdk.exporter.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | @@ -320,11 +339,11 @@ These values will therefore be reused in the case of an application restart. -### Metric: `otel.sdk.span.exporter.spans_processed` +### Metric: `otel.sdk.span.exporter.spans_exported` This metric is [recommended][MetricRecommended]. - + @@ -333,7 +352,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.exporter.spans_processed` | Counter | `1` | The number of spans for which the export has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.exporter.spans_exported` | Counter | `1` | The number of spans for which the export has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. diff --git a/model/otel/common.yaml b/model/otel/common.yaml index ddb8dd1e22..1051371079 100644 --- a/model/otel/common.yaml +++ b/model/otel/common.yaml @@ -1,7 +1,7 @@ groups: - id: otel_span type: attribute_group - brief: Span attributes used by non-OTLP exporters to represent OpenTelemetry Span's concepts. + brief: Span attributes used by non-OTLP exporters or on metrics to represent OpenTelemetry Span's concepts. attributes: - ref: otel.status_code requirement_level: recommended diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml index 5b466f601a..b62b429536 100644 --- a/model/otel/metrics.yaml +++ b/model/otel/metrics.yaml @@ -1,19 +1,34 @@ groups: - - id: metric.otel.sdk.span.ended_count + - id: metric.otel.sdk.span.created_count type: metric - metric_name: otel.sdk.span.ended_count + metric_name: otel.sdk.span.created_count stability: development - brief: "The number of spans which have been ended" + brief: "The number of spans which have been created" instrument: counter unit: "1" + attributes: + - ref: otel.is_sampled - - id: metric.otel.sdk.span.sampled_count + - id: metric.otel.sdk.span.live_count type: metric - metric_name: otel.sdk.span.sampled_count + metric_name: otel.sdk.span.live_count stability: development - brief: "The number of spans which have been ended AND are sampled" + brief: "The number of created spans for which the end operation has not been called yet" + instrument: updowncounter + unit: "1" + attributes: + - ref: otel.is_sampled + + - id: metric.otel.sdk.span.ended_count + type: metric + metric_name: otel.sdk.span.ended_count + stability: development + brief: "The number of created spans for which the end operation was called" instrument: counter unit: "1" + attributes: + - ref: otel.is_sampled + - id: metric.otel.sdk.span.processor.queue_size type: metric @@ -41,20 +56,6 @@ groups: - ref: otel.sdk.processor.type - ref: otel.sdk.component.id - - id: metric.otel.sdk.span.processor.spans_submitted - type: metric - metric_name: otel.sdk.span.processor.spans_submitted - stability: development - brief: "The number of spans submitted for processing to this span processor." - note: | - A span is considered submitted when the first callback has been called which triggers processing of the span for the given processor. - For the Batching and Simple Span Processors this metric therefore MUST be incremented on invocations of the `on_end` span processor callback. - instrument: counter - unit: "1" - attributes: - - ref: otel.sdk.processor.type - - ref: otel.sdk.component.id - - id: metric.otel.sdk.span.processor.spans_processed type: metric metric_name: otel.sdk.span.processor.spans_processed @@ -62,6 +63,7 @@ groups: brief: "The number of spans for which the processing has finished, either successful or failed" note: | For successful processing, `error.type` must be empty. For failed processing, `error.type` must contain the failure cause. + For the SDK Simple and Batching Span Processor a span is considered to be processed already when it has been submitted to the exporter, not when the corresponding export call has finished. instrument: counter unit: "1" attributes: @@ -69,19 +71,22 @@ groups: - ref: otel.sdk.component.id - ref: error.type brief: > - A low-cardinality description of the failure reason. SDK Batching Span Processors MUST use `queue full` for spans dropped due to a full queue. - examples: ["queue full"] + A low-cardinality description of the failure reason. SDK Batching Span Processors MUST use `queue_full` for spans dropped due to a full queue. + examples: ["queue_full"] - - id: metric.otel.sdk.span.exporter.spans_submitted + - id: metric.otel.sdk.span.exporter.spans_inflight type: metric - metric_name: otel.sdk.span.exporter.spans_submitted + metric_name: otel.sdk.span.exporter.spans_inflight stability: development - brief: "The number of spans for which the `export` callback of the exporter has been invoked. This does not require the export of the span to have finished yet." - instrument: counter + brief: "The number of spans which were passed to the exporter, but that have not been exported yet (neither successful, nor failed)" + note: | + For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. + instrument: updowncounter unit: "1" attributes: - ref: otel.sdk.exporter.type - ref: otel.sdk.component.id + - ref: error.type - id: metric.otel.sdk.span.exporter.spans_exported type: metric diff --git a/model/otel/registry.yaml b/model/otel/registry.yaml index 61736e4106..2e6958ad7e 100644 --- a/model/otel/registry.yaml +++ b/model/otel/registry.yaml @@ -22,6 +22,10 @@ groups: brief: "Description of the Status if it has a value, otherwise not set." examples: ['resource not found'] stability: stable + - id: otel.is_sampled + type: boolean + brief: "The sampled trace flag of the span" + stability: development - id: registry.otel.scope type: attribute_group display_name: OTel Scope Attributes From f1e1404bf128921803f71bdee01724fe6e164cde Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Tue, 14 Jan 2025 12:10:57 +0100 Subject: [PATCH 18/41] Clarify rejected data handling --- docs/otel/sdk-metrics.md | 2 ++ model/otel/metrics.yaml | 2 ++ 2 files changed, 4 insertions(+) diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index 95ff34ed03..b70acf38e4 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -355,6 +355,8 @@ This metric is [recommended][MetricRecommended]. | `otel.sdk.span.exporter.spans_exported` | Counter | `1` | The number of spans for which the export has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. +For exporters with partial success semantics (e.g. OTLP with `rejected_spans`), rejected spans must count as failed and only non-rejected spans count as success. +If no rejection reason is available, `rejected` SHOULD be used as value for `error.type`. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml index b62b429536..f179bee11a 100644 --- a/model/otel/metrics.yaml +++ b/model/otel/metrics.yaml @@ -95,6 +95,8 @@ groups: brief: "The number of spans for which the export has finished, either successful or failed" note: | For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. + For exporters with partial success semantics (e.g. OTLP with `rejected_spans`), rejected spans must count as failed and only non-rejected spans count as success. + If no rejection reason is available, `rejected` SHOULD be used as value for `error.type`. instrument: counter unit: "1" attributes: From 4db76053ceec42f3d652c425fe1c97db067d895d Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Tue, 14 Jan 2025 12:37:53 +0100 Subject: [PATCH 19/41] removed type in favor of component.name --- docs/attributes-registry/otel.md | 24 ++-- docs/otel/sdk-metrics.md | 197 +++++++++++++------------------ model/otel/metrics.yaml | 18 ++- model/otel/registry.yaml | 26 ++-- 4 files changed, 125 insertions(+), 140 deletions(-) diff --git a/docs/attributes-registry/otel.md b/docs/attributes-registry/otel.md index d243f8a2ec..1448d587e3 100644 --- a/docs/attributes-registry/otel.md +++ b/docs/attributes-registry/otel.md @@ -45,17 +45,27 @@ Attributes used for OpenTelemetry SDK self-monitoring | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `otel.sdk.component.id` | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.component.name` | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `otel.sdk.exporter.type` | string | A name identifying the type of the OpenTelemetry SDK exporter. | `otlp-grpc`; `jaeger` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `otel.sdk.processor.type` | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `otel.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, -the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. -E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: -Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an +**[1] `otel.sdk.component.name`:** The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. + +For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: + * `batching_span_processor` for the SDK Batching Span Processor + * `simple_span_processor` for the SDK Simple Span Processor + * `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization + * `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization + * `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization + +Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. + +The value of `instance-counter` MUST be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. +Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality. E.g. a UUID MUST NOT be use for . +Instead, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -For example, the first Batch Span Processor will have `batch-span-0` as `otel.sdk.component.id`, the second one `batch-span-1` and so one. + +For example, the first Batching Span Processor will have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. --- diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index b70acf38e4..4c149a2cc4 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -118,26 +118,26 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`otel.sdk.component.id`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`otel.sdk.processor.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1] `otel.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, -the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. -E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: -Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an -instance of the given component type is started. -For example, the first Batch Span Processor will have `batch-span-0` as `otel.sdk.component.id`, the second one `batch-span-1` and so one. -These values will therefore be reused in the case of an application restart. +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ---- +**[1] `otel.sdk.component.name`:** The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. -`otel.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: + * `batching_span_processor` for the SDK Batching Span Processor + * `simple_span_processor` for the SDK Simple Span Processor + * `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization + * `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization + * `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization -| Value | Description | Stability | -|---|---|---| -| `batch-span` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `simple-span` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. + +The value of `instance-counter` MUST be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. +Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality. E.g. a UUID MUST NOT be use for . +Instead, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an +instance of the given component type is started. + +For example, the first Batching Span Processor will have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +These values will therefore be reused in the case of an application restart. @@ -163,26 +163,26 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`otel.sdk.component.id`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`otel.sdk.processor.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1] `otel.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, -the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. -E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: -Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an -instance of the given component type is started. -For example, the first Batch Span Processor will have `batch-span-0` as `otel.sdk.component.id`, the second one `batch-span-1` and so one. -These values will therefore be reused in the case of an application restart. +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ---- +**[1] `otel.sdk.component.name`:** The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. -`otel.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: + * `batching_span_processor` for the SDK Batching Span Processor + * `simple_span_processor` for the SDK Simple Span Processor + * `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization + * `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization + * `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization -| Value | Description | Stability | -|---|---|---| -| `batch-span` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `simple-span` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. + +The value of `instance-counter` MUST be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. +Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality. E.g. a UUID MUST NOT be use for . +Instead, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an +instance of the given component type is started. + +For example, the first Batching Span Processor will have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +These values will therefore be reused in the case of an application restart. @@ -210,8 +210,7 @@ For the SDK Simple and Batching Span Processor a span is considered to be proces | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`error.type`](/docs/attributes-registry/error.md) | string | A low-cardinality description of the failure reason. SDK Batching Span Processors MUST use `queue_full` for spans dropped due to a full queue. [1] | `queue_full` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`otel.sdk.component.id`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`otel.sdk.processor.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. @@ -233,13 +232,23 @@ it's RECOMMENDED to: - Use a domain-specific attribute - Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. -**[2] `otel.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, -the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. -E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: -Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an +**[2] `otel.sdk.component.name`:** The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. + +For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: + * `batching_span_processor` for the SDK Batching Span Processor + * `simple_span_processor` for the SDK Simple Span Processor + * `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization + * `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization + * `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization + +Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. + +The value of `instance-counter` MUST be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. +Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality. E.g. a UUID MUST NOT be use for . +Instead, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -For example, the first Batch Span Processor will have `batch-span-0` as `otel.sdk.component.id`, the second one `batch-span-1` and so one. + +For example, the first Batching Span Processor will have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. --- @@ -250,15 +259,6 @@ These values will therefore be reused in the case of an application restart. |---|---|---| | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | ---- - -`otel.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -|---|---|---| -| `batch-span` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `simple-span` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - @@ -283,56 +283,26 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`otel.sdk.component.id`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`otel.sdk.exporter.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK exporter. | `otlp-grpc`; `jaeger` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. - -When `error.type` is set to a type (e.g., an exception type), its -canonical class name identifying the type within the artifact SHOULD be used. - -Instrumentations SHOULD document the list of errors they report. +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -The cardinality of `error.type` within one instrumentation library SHOULD be low. -Telemetry consumers that aggregate data from multiple instrumentation libraries and applications -should be prepared for `error.type` to have high cardinality at query time when no -additional filters are applied. +**[1] `otel.sdk.component.name`:** The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. -If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. +For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: + * `batching_span_processor` for the SDK Batching Span Processor + * `simple_span_processor` for the SDK Simple Span Processor + * `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization + * `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization + * `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization -If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), -it's RECOMMENDED to: - -- Use a domain-specific attribute -- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. +Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. -**[2] `otel.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, -the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. -E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: -Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an +The value of `instance-counter` MUST be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. +Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality. E.g. a UUID MUST NOT be use for . +Instead, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -For example, the first Batch Span Processor will have `batch-span-0` as `otel.sdk.component.id`, the second one `batch-span-1` and so one. -These values will therefore be reused in the case of an application restart. ---- - -`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -|---|---|---| -| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - ---- - -`otel.sdk.exporter.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -|---|---|---| -| `otlp-grpc` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp-http` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp-http-json` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +For example, the first Batching Span Processor will have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +These values will therefore be reused in the case of an application restart. @@ -360,9 +330,8 @@ If no rejection reason is available, `rejected` SHOULD be used as value for `err | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`otel.sdk.component.id`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`otel.sdk.exporter.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK exporter. | `otlp-grpc`; `jaeger` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `rejected` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. @@ -384,13 +353,23 @@ it's RECOMMENDED to: - Use a domain-specific attribute - Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. -**[2] `otel.sdk.component.id`:** The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, -the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. -E.g. it MUST NOT use a UUID. -It instead MAY do that by using the following pattern as value: `-`: -Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an +**[2] `otel.sdk.component.name`:** The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. + +For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: + * `batching_span_processor` for the SDK Batching Span Processor + * `simple_span_processor` for the SDK Simple Span Processor + * `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization + * `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization + * `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization + +Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. + +The value of `instance-counter` MUST be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. +Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality. E.g. a UUID MUST NOT be use for . +Instead, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -For example, the first Batch Span Processor will have `batch-span-0` as `otel.sdk.component.id`, the second one `batch-span-1` and so one. + +For example, the first Batching Span Processor will have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. --- @@ -401,16 +380,6 @@ These values will therefore be reused in the case of an application restart. |---|---|---| | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | ---- - -`otel.sdk.exporter.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -|---|---|---| -| `otlp-grpc` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp-http` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp-http-json` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml index f179bee11a..3efa72dce8 100644 --- a/model/otel/metrics.yaml +++ b/model/otel/metrics.yaml @@ -40,8 +40,7 @@ groups: instrument: updowncounter unit: "1" attributes: - - ref: otel.sdk.processor.type - - ref: otel.sdk.component.id + - ref: otel.sdk.component.name - id: metric.otel.sdk.span.processor.queue_capacity type: metric @@ -53,8 +52,7 @@ groups: instrument: gauge unit: "1" attributes: - - ref: otel.sdk.processor.type - - ref: otel.sdk.component.id + - ref: otel.sdk.component.name - id: metric.otel.sdk.span.processor.spans_processed type: metric @@ -67,8 +65,7 @@ groups: instrument: counter unit: "1" attributes: - - ref: otel.sdk.processor.type - - ref: otel.sdk.component.id + - ref: otel.sdk.component.name - ref: error.type brief: > A low-cardinality description of the failure reason. SDK Batching Span Processors MUST use `queue_full` for spans dropped due to a full queue. @@ -84,9 +81,7 @@ groups: instrument: updowncounter unit: "1" attributes: - - ref: otel.sdk.exporter.type - - ref: otel.sdk.component.id - - ref: error.type + - ref: otel.sdk.component.name - id: metric.otel.sdk.span.exporter.spans_exported type: metric @@ -100,6 +95,7 @@ groups: instrument: counter unit: "1" attributes: - - ref: otel.sdk.exporter.type - - ref: otel.sdk.component.id + - ref: otel.sdk.component.name - ref: error.type + examples: ["rejected"] + diff --git a/model/otel/registry.yaml b/model/otel/registry.yaml index 2e6958ad7e..6c55ed6f43 100644 --- a/model/otel/registry.yaml +++ b/model/otel/registry.yaml @@ -49,7 +49,7 @@ groups: - id: otel.sdk.processor.type type: members: - - id: batch_span + - id: batching_span value: "batch-span" brief: > The builtin SDK Batching Span Processor @@ -85,18 +85,28 @@ groups: brief: > A name identifying the type of the OpenTelemetry SDK exporter. examples: ["otlp-grpc", "jaeger"] - - id: otel.sdk.component.id + - id: otel.sdk.component.name type: string stability: development brief: > A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. note: | - The SDK components MAY allow users to provide an id for the component instances. If no id is provided by the user, - the components SHOULD automatically assign an id. Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality in that case. - E.g. it MUST NOT use a UUID. - It instead MAY do that by using the following pattern as value: `-`: - Hereby, `` is a monotonically increasing counter (starting with `0`), which is incremented every time an + The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. + + For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: + * `batching_span_processor` for the SDK Batching Span Processor + * `simple_span_processor` for the SDK Simple Span Processor + * `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization + * `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization + * `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization + + Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. + + The value of `instance-counter` MUST be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. + Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality. E.g. a UUID MUST NOT be use for . + Instead, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. - For example, the first Batch Span Processor will have `batch-span-0` as `otel.sdk.component.id`, the second one `batch-span-1` and so one. + + For example, the first Batching Span Processor will have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. examples: ["batch-span-0", "custom-name"] From 26e21b2b956ddbb21f9ae069c25e2f48d8f0ecee Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Tue, 14 Jan 2025 12:46:01 +0100 Subject: [PATCH 20/41] Use {span} as unit --- docs/otel/sdk-metrics.md | 16 ++++++++-------- model/otel/metrics.yaml | 16 ++++++++-------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index 4c149a2cc4..0ad2a554ce 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -39,7 +39,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.created_count` | Counter | `1` | The number of spans which have been created | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.created_count` | Counter | `{span}` | The number of spans which have been created | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -64,7 +64,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.live_count` | UpDownCounter | `1` | The number of created spans for which the end operation has not been called yet | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.live_count` | UpDownCounter | `{span}` | The number of created spans for which the end operation has not been called yet | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -88,7 +88,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.ended_count` | Counter | `1` | The number of created spans for which the end operation was called | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.ended_count` | Counter | `{span}` | The number of created spans for which the end operation was called | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -112,7 +112,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.processor.queue_size` | UpDownCounter | `1` | The number of spans in the queue of a given instance of an SDK span processor [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.processor.queue_size` | UpDownCounter | `{span}` | The number of spans in the queue of a given instance of an SDK span processor [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. @@ -157,7 +157,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.processor.queue_capacity` | Gauge | `1` | The maximum number of spans the queue of a given instance of an SDK span processor can hold [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.processor.queue_capacity` | Gauge | `{span}` | The maximum number of spans the queue of a given instance of an SDK span processor can hold [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. @@ -202,7 +202,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.processor.spans_processed` | Counter | `1` | The number of spans for which the processing has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.processor.spans_processed` | Counter | `{span}` | The number of spans for which the processing has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** For successful processing, `error.type` must be empty. For failed processing, `error.type` must contain the failure cause. For the SDK Simple and Batching Span Processor a span is considered to be processed already when it has been submitted to the exporter, not when the corresponding export call has finished. @@ -277,7 +277,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.exporter.spans_inflight` | UpDownCounter | `1` | The number of spans which were passed to the exporter, but that have not been exported yet (neither successful, nor failed) [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.exporter.spans_inflight` | UpDownCounter | `{span}` | The number of spans which were passed to the exporter, but that have not been exported yet (neither successful, nor failed) [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. @@ -322,7 +322,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.exporter.spans_exported` | Counter | `1` | The number of spans for which the export has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.exporter.spans_exported` | Counter | `{span}` | The number of spans for which the export has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. For exporters with partial success semantics (e.g. OTLP with `rejected_spans`), rejected spans must count as failed and only non-rejected spans count as success. diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml index 3efa72dce8..df499d0b47 100644 --- a/model/otel/metrics.yaml +++ b/model/otel/metrics.yaml @@ -5,7 +5,7 @@ groups: stability: development brief: "The number of spans which have been created" instrument: counter - unit: "1" + unit: "{span}" attributes: - ref: otel.is_sampled @@ -15,7 +15,7 @@ groups: stability: development brief: "The number of created spans for which the end operation has not been called yet" instrument: updowncounter - unit: "1" + unit: "{span}" attributes: - ref: otel.is_sampled @@ -25,7 +25,7 @@ groups: stability: development brief: "The number of created spans for which the end operation was called" instrument: counter - unit: "1" + unit: "{span}" attributes: - ref: otel.is_sampled @@ -38,7 +38,7 @@ groups: note: | Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. instrument: updowncounter - unit: "1" + unit: "{span}" attributes: - ref: otel.sdk.component.name @@ -50,7 +50,7 @@ groups: note: | Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. instrument: gauge - unit: "1" + unit: "{span}" attributes: - ref: otel.sdk.component.name @@ -63,7 +63,7 @@ groups: For successful processing, `error.type` must be empty. For failed processing, `error.type` must contain the failure cause. For the SDK Simple and Batching Span Processor a span is considered to be processed already when it has been submitted to the exporter, not when the corresponding export call has finished. instrument: counter - unit: "1" + unit: "{span}" attributes: - ref: otel.sdk.component.name - ref: error.type @@ -79,7 +79,7 @@ groups: note: | For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. instrument: updowncounter - unit: "1" + unit: "{span}" attributes: - ref: otel.sdk.component.name @@ -93,7 +93,7 @@ groups: For exporters with partial success semantics (e.g. OTLP with `rejected_spans`), rejected spans must count as failed and only non-rejected spans count as success. If no rejection reason is available, `rejected` SHOULD be used as value for `error.type`. instrument: counter - unit: "1" + unit: "{span}" attributes: - ref: otel.sdk.component.name - ref: error.type From 820c5c6fc3bfce6225c8d6608c27fb2080774634 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Tue, 14 Jan 2025 13:19:34 +0100 Subject: [PATCH 21/41] Lint fixes --- docs/attributes-registry/otel.md | 15 +++++---- docs/general/metrics.md | 2 +- docs/otel/sdk-metrics.md | 56 +++++++++++++++++--------------- model/otel/registry.yaml | 13 ++++---- 4 files changed, 46 insertions(+), 40 deletions(-) diff --git a/docs/attributes-registry/otel.md b/docs/attributes-registry/otel.md index 1448d587e3..8d41744196 100644 --- a/docs/attributes-registry/otel.md +++ b/docs/attributes-registry/otel.md @@ -8,7 +8,7 @@ - [OTel Attributes](#otel-attributes) - [OTel Scope Attributes](#otel-scope-attributes) -- [OTel Scope Attributes](#otel-scope-attributes) +- [OTel SDK Telemetry Attributes](#otel-sdk-telemetry-attributes) - [Deprecated OTel Library Attributes](#deprecated-otel-library-attributes) ## OTel Attributes @@ -39,7 +39,7 @@ Attributes used by non-OTLP exporters to represent OpenTelemetry Scope's concept | `otel.scope.name` | string | The name of the instrumentation scope - (`InstrumentationScope.Name` in OTLP). | `io.opentelemetry.contrib.mongodb` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `otel.scope.version` | string | The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). | `1.0.0` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -## OTel Scope Attributes +## OTel SDK Telemetry Attributes Attributes used for OpenTelemetry SDK self-monitoring @@ -52,11 +52,12 @@ Attributes used for OpenTelemetry SDK self-monitoring **[1] `otel.sdk.component.name`:** The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: - * `batching_span_processor` for the SDK Batching Span Processor - * `simple_span_processor` for the SDK Simple Span Processor - * `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization - * `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization - * `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization + +* `batching_span_processor` for the SDK Batching Span Processor +* `simple_span_processor` for the SDK Simple Span Processor +* `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization +* `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization +* `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. diff --git a/docs/general/metrics.md b/docs/general/metrics.md index f43ed176bb..653cd0c995 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -34,7 +34,7 @@ The following semantic conventions surrounding metrics are defined: * [K8s](/docs/system/k8s-metrics.md): For K8s metrics. * [Process](/docs/system/process-metrics.md): For standard process metrics. * [Runtime Environment](/docs/runtime/README.md#metrics): For runtime environment metrics. -* [SDK Telemetry](/docs/telemetry/telemetry-sdk-metrics.md): Metrics emitted by the OpenTelemetry SDK components. +* [OTel SDK Telemetry](/docs/otel/sdk-metrics.md): Metrics emitted by the OpenTelemetry SDK components. Apart from semantic conventions for metrics, [traces](trace.md), [logs](logs.md), and [events](events.md), OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/resource/sdk.md) with diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index 0ad2a554ce..567accb9ae 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -50,7 +50,6 @@ This metric is [recommended][MetricRecommended]. - ### Metric: `otel.sdk.span.live_count` This metric is [recommended][MetricRecommended]. @@ -123,11 +122,12 @@ This metric is [recommended][MetricRecommended]. **[1] `otel.sdk.component.name`:** The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: - * `batching_span_processor` for the SDK Batching Span Processor - * `simple_span_processor` for the SDK Simple Span Processor - * `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization - * `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization - * `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization + +* `batching_span_processor` for the SDK Batching Span Processor +* `simple_span_processor` for the SDK Simple Span Processor +* `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization +* `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization +* `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. @@ -168,11 +168,12 @@ This metric is [recommended][MetricRecommended]. **[1] `otel.sdk.component.name`:** The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: - * `batching_span_processor` for the SDK Batching Span Processor - * `simple_span_processor` for the SDK Simple Span Processor - * `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization - * `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization - * `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization + +* `batching_span_processor` for the SDK Batching Span Processor +* `simple_span_processor` for the SDK Simple Span Processor +* `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization +* `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization +* `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. @@ -235,11 +236,12 @@ it's RECOMMENDED to: **[2] `otel.sdk.component.name`:** The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: - * `batching_span_processor` for the SDK Batching Span Processor - * `simple_span_processor` for the SDK Simple Span Processor - * `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization - * `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization - * `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization + +* `batching_span_processor` for the SDK Batching Span Processor +* `simple_span_processor` for the SDK Simple Span Processor +* `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization +* `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization +* `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. @@ -288,11 +290,12 @@ This metric is [recommended][MetricRecommended]. **[1] `otel.sdk.component.name`:** The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: - * `batching_span_processor` for the SDK Batching Span Processor - * `simple_span_processor` for the SDK Simple Span Processor - * `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization - * `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization - * `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization + +* `batching_span_processor` for the SDK Batching Span Processor +* `simple_span_processor` for the SDK Simple Span Processor +* `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization +* `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization +* `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. @@ -356,11 +359,12 @@ it's RECOMMENDED to: **[2] `otel.sdk.component.name`:** The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: - * `batching_span_processor` for the SDK Batching Span Processor - * `simple_span_processor` for the SDK Simple Span Processor - * `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization - * `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization - * `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization + +* `batching_span_processor` for the SDK Batching Span Processor +* `simple_span_processor` for the SDK Simple Span Processor +* `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization +* `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization +* `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. diff --git a/model/otel/registry.yaml b/model/otel/registry.yaml index 6c55ed6f43..6c36eaaeac 100644 --- a/model/otel/registry.yaml +++ b/model/otel/registry.yaml @@ -43,7 +43,7 @@ groups: stability: stable - id: registry.otel.sdk.telemetry type: attribute_group - display_name: OTel Scope Attributes + display_name: OTel SDK Telemetry Attributes brief: Attributes used for OpenTelemetry SDK self-monitoring attributes: - id: otel.sdk.processor.type @@ -94,11 +94,12 @@ groups: The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: - * `batching_span_processor` for the SDK Batching Span Processor - * `simple_span_processor` for the SDK Simple Span Processor - * `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization - * `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization - * `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization + + * `batching_span_processor` for the SDK Batching Span Processor + * `simple_span_processor` for the SDK Simple Span Processor + * `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization + * `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization + * `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. From ef5bd539703a5eb8b2b5def03ffbc702b40be354 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Tue, 14 Jan 2025 13:21:52 +0100 Subject: [PATCH 22/41] Remove trailing empty line --- model/otel/metrics.yaml | 3 +-- model/otel/registry.yaml | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml index df499d0b47..adf6dfcb47 100644 --- a/model/otel/metrics.yaml +++ b/model/otel/metrics.yaml @@ -18,7 +18,7 @@ groups: unit: "{span}" attributes: - ref: otel.is_sampled - + - id: metric.otel.sdk.span.ended_count type: metric metric_name: otel.sdk.span.ended_count @@ -98,4 +98,3 @@ groups: - ref: otel.sdk.component.name - ref: error.type examples: ["rejected"] - diff --git a/model/otel/registry.yaml b/model/otel/registry.yaml index 6c36eaaeac..8ec77eab76 100644 --- a/model/otel/registry.yaml +++ b/model/otel/registry.yaml @@ -94,7 +94,7 @@ groups: The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: - + * `batching_span_processor` for the SDK Batching Span Processor * `simple_span_processor` for the SDK Simple Span Processor * `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization From 833352b363f891d390a3f33abc2909063b217a0c Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Mon, 20 Jan 2025 12:30:48 +0100 Subject: [PATCH 23/41] Fix attribute registry name --- model/otel/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/otel/registry.yaml b/model/otel/registry.yaml index 8ec77eab76..c209e1d99a 100644 --- a/model/otel/registry.yaml +++ b/model/otel/registry.yaml @@ -41,7 +41,7 @@ groups: brief: The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). examples: ['1.0.0'] stability: stable - - id: registry.otel.sdk.telemetry + - id: registry.otel.sdk type: attribute_group display_name: OTel SDK Telemetry Attributes brief: Attributes used for OpenTelemetry SDK self-monitoring From 226b42f4dd8f000748ee260bc6e5a6721752ac45 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Mon, 20 Jan 2025 12:33:35 +0100 Subject: [PATCH 24/41] Renamed otel.is_sampled to otel.span.is_sampled --- docs/attributes-registry/otel.md | 2 +- docs/otel/sdk-metrics.md | 6 +++--- model/otel/metrics.yaml | 6 +++--- model/otel/registry.yaml | 2 +- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/attributes-registry/otel.md b/docs/attributes-registry/otel.md index 8d41744196..6946c75dd7 100644 --- a/docs/attributes-registry/otel.md +++ b/docs/attributes-registry/otel.md @@ -17,7 +17,7 @@ Attributes reserved for OpenTelemetry | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `otel.is_sampled` | boolean | The sampled trace flag of the span | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.span.is_sampled` | boolean | The sampled trace flag of the span | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `otel.status_code` | string | Name of the code, either "OK" or "ERROR". MUST NOT be set if the status code is UNSET. | `OK`; `ERROR` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `otel.status_description` | string | Description of the Status if it has a value, otherwise not set. | `resource not found` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index 567accb9ae..bd86078890 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -43,7 +43,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`otel.is_sampled`](/docs/attributes-registry/otel.md) | boolean | The sampled trace flag of the span | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.span.is_sampled`](/docs/attributes-registry/otel.md) | boolean | The sampled trace flag of the span | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -67,7 +67,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`otel.is_sampled`](/docs/attributes-registry/otel.md) | boolean | The sampled trace flag of the span | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.span.is_sampled`](/docs/attributes-registry/otel.md) | boolean | The sampled trace flag of the span | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -91,7 +91,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`otel.is_sampled`](/docs/attributes-registry/otel.md) | boolean | The sampled trace flag of the span | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.span.is_sampled`](/docs/attributes-registry/otel.md) | boolean | The sampled trace flag of the span | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml index adf6dfcb47..07ffe7b8e2 100644 --- a/model/otel/metrics.yaml +++ b/model/otel/metrics.yaml @@ -7,7 +7,7 @@ groups: instrument: counter unit: "{span}" attributes: - - ref: otel.is_sampled + - ref: otel.span.is_sampled - id: metric.otel.sdk.span.live_count type: metric @@ -17,7 +17,7 @@ groups: instrument: updowncounter unit: "{span}" attributes: - - ref: otel.is_sampled + - ref: otel.span.is_sampled - id: metric.otel.sdk.span.ended_count type: metric @@ -27,7 +27,7 @@ groups: instrument: counter unit: "{span}" attributes: - - ref: otel.is_sampled + - ref: otel.span.is_sampled - id: metric.otel.sdk.span.processor.queue_size diff --git a/model/otel/registry.yaml b/model/otel/registry.yaml index c209e1d99a..c65fa9d12d 100644 --- a/model/otel/registry.yaml +++ b/model/otel/registry.yaml @@ -22,7 +22,7 @@ groups: brief: "Description of the Status if it has a value, otherwise not set." examples: ['resource not found'] stability: stable - - id: otel.is_sampled + - id: otel.span.is_sampled type: boolean brief: "The sampled trace flag of the span" stability: development From 1a82268f2c0722ae1398515211bc06ff302f0b9c Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Thu, 23 Jan 2025 14:15:39 +0100 Subject: [PATCH 25/41] Remove leftover unused attributes --- docs/attributes-registry/otel.md | 21 ----------------- model/otel/registry.yaml | 39 -------------------------------- 2 files changed, 60 deletions(-) diff --git a/docs/attributes-registry/otel.md b/docs/attributes-registry/otel.md index 6946c75dd7..60f7576fd5 100644 --- a/docs/attributes-registry/otel.md +++ b/docs/attributes-registry/otel.md @@ -46,8 +46,6 @@ Attributes used for OpenTelemetry SDK self-monitoring | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| | `otel.sdk.component.name` | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otel.sdk.exporter.type` | string | A name identifying the type of the OpenTelemetry SDK exporter. | `otlp-grpc`; `jaeger` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otel.sdk.processor.type` | string | A name identifying the type of the OpenTelemetry SDK processor. | `batch-span`; `MyCustomProcessor` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `otel.sdk.component.name`:** The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. @@ -69,25 +67,6 @@ instance of the given component type is started. For example, the first Batching Span Processor will have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. ---- - -`otel.sdk.exporter.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -|---|---|---| -| `otlp-grpc` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp-http` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp-http-json` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - ---- - -`otel.sdk.processor.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -|---|---|---| -| `batch-span` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `simple-span` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - ## Deprecated OTel Library Attributes Describes deprecated otel.library attributes. diff --git a/model/otel/registry.yaml b/model/otel/registry.yaml index c65fa9d12d..9bc04321a4 100644 --- a/model/otel/registry.yaml +++ b/model/otel/registry.yaml @@ -46,45 +46,6 @@ groups: display_name: OTel SDK Telemetry Attributes brief: Attributes used for OpenTelemetry SDK self-monitoring attributes: - - id: otel.sdk.processor.type - type: - members: - - id: batching_span - value: "batch-span" - brief: > - The builtin SDK Batching Span Processor - stability: development - - id: simple_span - value: "simple-span" - brief: > - The builtin SDK Simple Span Processor - stability: development - stability: development - brief: > - A name identifying the type of the OpenTelemetry SDK processor. - examples: ["batch-span", "MyCustomProcessor"] - - id: otel.sdk.exporter.type - type: - members: - - id: otlp_grpc - value: "otlp-grpc" - brief: > - OTLP exporter over gRPC with protobuf serialization - stability: development - - id: otlp_http - value: "otlp-http" - brief: > - OTLP exporter over HTTP with protobuf serialization - stability: development - - id: otlp_http_json - value: "otlp-http-json" - brief: > - OTLP exporter over HTTP with JSON serialization - stability: development - stability: development - brief: > - A name identifying the type of the OpenTelemetry SDK exporter. - examples: ["otlp-grpc", "jaeger"] - id: otel.sdk.component.name type: string stability: development From e737b7d2bace666f877ed69ce37888d96b40f03a Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Fri, 24 Jan 2025 13:16:21 +0100 Subject: [PATCH 26/41] Added back reworked otel.sdk.component.type attribute --- docs/attributes-registry/otel.md | 39 ++++--- docs/otel/sdk-metrics.md | 195 +++++++++++++++++++------------ model/otel/metrics.yaml | 5 + model/otel/registry.yaml | 58 ++++++--- 4 files changed, 192 insertions(+), 105 deletions(-) diff --git a/docs/attributes-registry/otel.md b/docs/attributes-registry/otel.md index 60f7576fd5..6a5b7ea3f3 100644 --- a/docs/attributes-registry/otel.md +++ b/docs/attributes-registry/otel.md @@ -45,28 +45,37 @@ Attributes used for OpenTelemetry SDK self-monitoring | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `otel.sdk.component.name` | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.component.name` | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_exporter/0`; `custom-name` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.component.type` | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `co.example.MySpanExporter` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `otel.sdk.component.name`:** The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. +**[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. +E.g. implementations MUST NOT use UUIDs as values for this attribute. -For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: +Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. +Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. -* `batching_span_processor` for the SDK Batching Span Processor -* `simple_span_processor` for the SDK Simple Span Processor -* `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization -* `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization -* `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization - -Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. - -The value of `instance-counter` MUST be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. -Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality. E.g. a UUID MUST NOT be use for . -Instead, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an +The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. +For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -For example, the first Batching Span Processor will have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. +**[2] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. +E.g. for Java the fully qualified classname SHOULD be used in this case. + +--- + +`otel.sdk.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_exporter` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_exporter` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_exporter` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + ## Deprecated OTel Library Attributes Describes deprecated otel.library attributes. diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index bd86078890..9ba919bb9a 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -117,28 +117,37 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `otel.sdk.component.name`:** The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. +**[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. +E.g. implementations MUST NOT use UUIDs as values for this attribute. -For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: +Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. +Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. -* `batching_span_processor` for the SDK Batching Span Processor -* `simple_span_processor` for the SDK Simple Span Processor -* `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization -* `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization -* `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization - -Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. - -The value of `instance-counter` MUST be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. -Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality. E.g. a UUID MUST NOT be use for . -Instead, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an +The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. +For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -For example, the first Batching Span Processor will have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. +**[2] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. +E.g. for Java the fully qualified classname SHOULD be used in this case. + +--- + +`otel.sdk.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_exporter` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_exporter` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_exporter` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + @@ -163,28 +172,37 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `otel.sdk.component.name`:** The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. +**[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. +E.g. implementations MUST NOT use UUIDs as values for this attribute. -For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: +Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. +Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. -* `batching_span_processor` for the SDK Batching Span Processor -* `simple_span_processor` for the SDK Simple Span Processor -* `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization -* `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization -* `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization - -Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. - -The value of `instance-counter` MUST be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. -Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality. E.g. a UUID MUST NOT be use for . -Instead, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an +The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. +For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -For example, the first Batching Span Processor will have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. +**[2] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. +E.g. for Java the fully qualified classname SHOULD be used in this case. + +--- + +`otel.sdk.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_exporter` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_exporter` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_exporter` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + @@ -211,7 +229,8 @@ For the SDK Simple and Batching Span Processor a span is considered to be proces | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`error.type`](/docs/attributes-registry/error.md) | string | A low-cardinality description of the failure reason. SDK Batching Span Processors MUST use `queue_full` for spans dropped due to a full queue. [1] | `queue_full` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `otlp_grpc_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [3] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. @@ -233,26 +252,22 @@ it's RECOMMENDED to: - Use a domain-specific attribute - Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. -**[2] `otel.sdk.component.name`:** The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. +**[2] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. +E.g. implementations MUST NOT use UUIDs as values for this attribute. -For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: +Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. +Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. -* `batching_span_processor` for the SDK Batching Span Processor -* `simple_span_processor` for the SDK Simple Span Processor -* `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization -* `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization -* `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization - -Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. - -The value of `instance-counter` MUST be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. -Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality. E.g. a UUID MUST NOT be use for . -Instead, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an +The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. +For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -For example, the first Batching Span Processor will have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. +**[3] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. +E.g. for Java the fully qualified classname SHOULD be used in this case. + --- `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. @@ -261,6 +276,18 @@ These values will therefore be reused in the case of an application restart. |---|---|---| | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +--- + +`otel.sdk.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_exporter` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_exporter` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_exporter` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + @@ -285,28 +312,37 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1] `otel.sdk.component.name`:** The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. - -For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -* `batching_span_processor` for the SDK Batching Span Processor -* `simple_span_processor` for the SDK Simple Span Processor -* `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization -* `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization -* `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization +**[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. +E.g. implementations MUST NOT use UUIDs as values for this attribute. -Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. +Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. +Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. -The value of `instance-counter` MUST be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. -Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality. E.g. a UUID MUST NOT be use for . -Instead, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an +The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. +For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -For example, the first Batching Span Processor will have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. +**[2] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. +E.g. for Java the fully qualified classname SHOULD be used in this case. + +--- + +`otel.sdk.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_exporter` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_exporter` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_exporter` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + @@ -334,7 +370,8 @@ If no rejection reason is available, `rejected` SHOULD be used as value for `err | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `rejected` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `batch-span-0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `otlp_grpc_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [3] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. @@ -356,26 +393,22 @@ it's RECOMMENDED to: - Use a domain-specific attribute - Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. -**[2] `otel.sdk.component.name`:** The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. - -For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: +**[2] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. +E.g. implementations MUST NOT use UUIDs as values for this attribute. -* `batching_span_processor` for the SDK Batching Span Processor -* `simple_span_processor` for the SDK Simple Span Processor -* `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization -* `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization -* `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization +Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. +Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. -Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. - -The value of `instance-counter` MUST be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. -Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality. E.g. a UUID MUST NOT be use for . -Instead, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an +The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. +For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -For example, the first Batching Span Processor will have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. +**[3] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. +E.g. for Java the fully qualified classname SHOULD be used in this case. + --- `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. @@ -384,6 +417,18 @@ These values will therefore be reused in the case of an application restart. |---|---|---| | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +--- + +`otel.sdk.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_exporter` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_exporter` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_exporter` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml index 07ffe7b8e2..362b102aa5 100644 --- a/model/otel/metrics.yaml +++ b/model/otel/metrics.yaml @@ -40,6 +40,7 @@ groups: instrument: updowncounter unit: "{span}" attributes: + - ref: otel.sdk.component.type - ref: otel.sdk.component.name - id: metric.otel.sdk.span.processor.queue_capacity @@ -52,6 +53,7 @@ groups: instrument: gauge unit: "{span}" attributes: + - ref: otel.sdk.component.type - ref: otel.sdk.component.name - id: metric.otel.sdk.span.processor.spans_processed @@ -65,6 +67,7 @@ groups: instrument: counter unit: "{span}" attributes: + - ref: otel.sdk.component.type - ref: otel.sdk.component.name - ref: error.type brief: > @@ -81,6 +84,7 @@ groups: instrument: updowncounter unit: "{span}" attributes: + - ref: otel.sdk.component.type - ref: otel.sdk.component.name - id: metric.otel.sdk.span.exporter.spans_exported @@ -95,6 +99,7 @@ groups: instrument: counter unit: "{span}" attributes: + - ref: otel.sdk.component.type - ref: otel.sdk.component.name - ref: error.type examples: ["rejected"] diff --git a/model/otel/registry.yaml b/model/otel/registry.yaml index 9bc04321a4..27427f89fc 100644 --- a/model/otel/registry.yaml +++ b/model/otel/registry.yaml @@ -46,29 +46,57 @@ groups: display_name: OTel SDK Telemetry Attributes brief: Attributes used for OpenTelemetry SDK self-monitoring attributes: + - id: otel.sdk.component.type + type: + members: + - id: batching_span_processor + value: "batching_span_processor" + brief: > + The builtin SDK Batching Span Processor + stability: development + - id: simple_span_processor + value: "simple_span_processor" + brief: > + The builtin SDK Simple Span Processor + stability: development + - id: otlp_grpc_span_exporter + value: "otlp_grpc_exporter" + brief: > + OTLP exporter over gRPC with protobuf serialization + stability: development + - id: otlp_http_span_exporter + value: "otlp_http_exporter" + brief: > + OTLP exporter over HTTP with protobuf serialization + stability: development + - id: otlp_http_json_span_exporter + value: "otlp_http_json_exporter" + brief: > + OTLP exporter over HTTP with JSON serialization + stability: development + stability: development + brief: > + A name identifying the type of the OpenTelemetry SDK component. + note: | + If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. + E.g. for Java the fully qualified classname SHOULD be used in this case. + examples: ["batching_span_processor", "co.example.MySpanExporter"] - id: otel.sdk.component.name type: string stability: development brief: > A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. note: | - The attribute value MUST follow a `/` pattern, e.g. `batching_span_processor/0`. - - For components corresponding to SDK specification concepts, the `type-name` MUST have the following values: - - * `batching_span_processor` for the SDK Batching Span Processor - * `simple_span_processor` for the SDK Simple Span Processor - * `otlp_grpc_exporter` for the OTLP exporter over gRPC with protobuf serialization - * `otlp_http_exporter` for the OTLP exporter over HTTP with protobuf serialization - * `otlp_http_json_exporter` for the OTLP exporter over HTTP with JSON serialization + Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. + E.g. implementations MUST NOT use UUIDs as values for this attribute. - Other components SHOULD use the language and implementation dependant type name of the component for `type-name`, e.g. the class name in Java. + Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. + Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. - The value of `instance-counter` MUST be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. - Because this attribute is used in metrics, the component implementation MUST ensure a low cardinality. E.g. a UUID MUST NOT be use for . - Instead, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an + The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. + For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. - For example, the first Batching Span Processor will have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. + With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. - examples: ["batch-span-0", "custom-name"] + examples: ["otlp_grpc_exporter/0", "custom-name"] From 772d29a6f0cf30ea32bbdefe99a9942a51bca1b2 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Fri, 24 Jan 2025 13:18:19 +0100 Subject: [PATCH 27/41] Fix lint --- docs/attributes-registry/otel.md | 3 ++- docs/otel/sdk-metrics.md | 15 ++++++++++----- model/otel/registry.yaml | 3 ++- 3 files changed, 14 insertions(+), 7 deletions(-) diff --git a/docs/attributes-registry/otel.md b/docs/attributes-registry/otel.md index 6a5b7ea3f3..582131de63 100644 --- a/docs/attributes-registry/otel.md +++ b/docs/attributes-registry/otel.md @@ -58,7 +58,8 @@ The value of `instance-counter` MAY be automatically assigned by the component a For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` +as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. **[2] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index 9ba919bb9a..377d999814 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -130,7 +130,8 @@ The value of `instance-counter` MAY be automatically assigned by the component a For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` +as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. **[2] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. @@ -185,7 +186,8 @@ The value of `instance-counter` MAY be automatically assigned by the component a For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` +as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. **[2] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. @@ -262,7 +264,8 @@ The value of `instance-counter` MAY be automatically assigned by the component a For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` +as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. **[3] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. @@ -325,7 +328,8 @@ The value of `instance-counter` MAY be automatically assigned by the component a For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` +as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. **[2] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. @@ -403,7 +407,8 @@ The value of `instance-counter` MAY be automatically assigned by the component a For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. -With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` +as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. **[3] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. diff --git a/model/otel/registry.yaml b/model/otel/registry.yaml index 27427f89fc..c096d8ba6e 100644 --- a/model/otel/registry.yaml +++ b/model/otel/registry.yaml @@ -97,6 +97,7 @@ groups: For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. - With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. + With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` + as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. examples: ["otlp_grpc_exporter/0", "custom-name"] From 935c01c6280a94ab0d8bcfc488c33aa373931061 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Fri, 24 Jan 2025 13:24:42 +0100 Subject: [PATCH 28/41] Fix otel.sdk.component.type enum value descriptions --- docs/attributes-registry/otel.md | 6 +++--- docs/otel/sdk-metrics.md | 30 +++++++++++++++--------------- model/otel/registry.yaml | 6 +++--- 3 files changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/attributes-registry/otel.md b/docs/attributes-registry/otel.md index 582131de63..2808e94e83 100644 --- a/docs/attributes-registry/otel.md +++ b/docs/attributes-registry/otel.md @@ -72,9 +72,9 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | Value | Description | Stability | |---|---|---| | `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_grpc_exporter` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_exporter` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_json_exporter` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## Deprecated OTel Library Attributes diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index 377d999814..1f442337ce 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -144,9 +144,9 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | Value | Description | Stability | |---|---|---| | `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_grpc_exporter` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_exporter` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_json_exporter` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -200,9 +200,9 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | Value | Description | Stability | |---|---|---| | `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_grpc_exporter` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_exporter` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_json_exporter` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -286,9 +286,9 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | Value | Description | Stability | |---|---|---| | `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_grpc_exporter` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_exporter` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_json_exporter` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -342,9 +342,9 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | Value | Description | Stability | |---|---|---| | `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_grpc_exporter` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_exporter` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_json_exporter` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -429,9 +429,9 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | Value | Description | Stability | |---|---|---| | `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_grpc_exporter` | OTLP exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_exporter` | OTLP exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_json_exporter` | OTLP exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/otel/registry.yaml b/model/otel/registry.yaml index c096d8ba6e..8770a5baa3 100644 --- a/model/otel/registry.yaml +++ b/model/otel/registry.yaml @@ -62,17 +62,17 @@ groups: - id: otlp_grpc_span_exporter value: "otlp_grpc_exporter" brief: > - OTLP exporter over gRPC with protobuf serialization + OTLP span exporter over gRPC with protobuf serialization stability: development - id: otlp_http_span_exporter value: "otlp_http_exporter" brief: > - OTLP exporter over HTTP with protobuf serialization + OTLP span exporter over HTTP with protobuf serialization stability: development - id: otlp_http_json_span_exporter value: "otlp_http_json_exporter" brief: > - OTLP exporter over HTTP with JSON serialization + OTLP span exporter over HTTP with JSON serialization stability: development stability: development brief: > From 04c0085c9881e61b5eaed25ff99c55ff51aa916f Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Fri, 24 Jan 2025 13:26:27 +0100 Subject: [PATCH 29/41] Fix missing _span prefixes --- docs/attributes-registry/otel.md | 6 +++--- docs/otel/sdk-metrics.md | 30 +++++++++++++++--------------- model/otel/registry.yaml | 6 +++--- 3 files changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/attributes-registry/otel.md b/docs/attributes-registry/otel.md index 2808e94e83..4219d22904 100644 --- a/docs/attributes-registry/otel.md +++ b/docs/attributes-registry/otel.md @@ -72,9 +72,9 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | Value | Description | Stability | |---|---|---| | `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_grpc_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_json_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_span_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_span_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_span_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ## Deprecated OTel Library Attributes diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index 1f442337ce..a8f84b2d45 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -144,9 +144,9 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | Value | Description | Stability | |---|---|---| | `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_grpc_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_json_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_span_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_span_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_span_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -200,9 +200,9 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | Value | Description | Stability | |---|---|---| | `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_grpc_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_json_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_span_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_span_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_span_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -286,9 +286,9 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | Value | Description | Stability | |---|---|---| | `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_grpc_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_json_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_span_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_span_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_span_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -342,9 +342,9 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | Value | Description | Stability | |---|---|---| | `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_grpc_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_json_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_span_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_span_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_span_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -429,9 +429,9 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | Value | Description | Stability | |---|---|---| | `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_grpc_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otlp_http_json_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_span_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_span_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_span_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/otel/registry.yaml b/model/otel/registry.yaml index 8770a5baa3..77e95e43d1 100644 --- a/model/otel/registry.yaml +++ b/model/otel/registry.yaml @@ -60,17 +60,17 @@ groups: The builtin SDK Simple Span Processor stability: development - id: otlp_grpc_span_exporter - value: "otlp_grpc_exporter" + value: "otlp_grpc_span_exporter" brief: > OTLP span exporter over gRPC with protobuf serialization stability: development - id: otlp_http_span_exporter - value: "otlp_http_exporter" + value: "otlp_http_span_exporter" brief: > OTLP span exporter over HTTP with protobuf serialization stability: development - id: otlp_http_json_span_exporter - value: "otlp_http_json_exporter" + value: "otlp_http_json_span_exporter" brief: > OTLP span exporter over HTTP with JSON serialization stability: development From 667028d1f55125b2ccdb0c9354e8bd8b13dabf79 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Fri, 24 Jan 2025 13:32:04 +0100 Subject: [PATCH 30/41] Fix another missing _span prefix --- docs/attributes-registry/otel.md | 2 +- docs/otel/sdk-metrics.md | 10 +++++----- model/otel/registry.yaml | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/attributes-registry/otel.md b/docs/attributes-registry/otel.md index 4219d22904..e21eeacac4 100644 --- a/docs/attributes-registry/otel.md +++ b/docs/attributes-registry/otel.md @@ -45,7 +45,7 @@ Attributes used for OpenTelemetry SDK self-monitoring | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `otel.sdk.component.name` | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_exporter/0`; `custom-name` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.component.name` | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `otel.sdk.component.type` | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `co.example.MySpanExporter` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index a8f84b2d45..cec62f15a3 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -117,7 +117,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. @@ -173,7 +173,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. @@ -231,7 +231,7 @@ For the SDK Simple and Batching Span Processor a span is considered to be proces | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`error.type`](/docs/attributes-registry/error.md) | string | A low-cardinality description of the failure reason. SDK Batching Span Processors MUST use `queue_full` for spans dropped due to a full queue. [1] | `queue_full` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `otlp_grpc_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [3] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. @@ -315,7 +315,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. @@ -374,7 +374,7 @@ If no rejection reason is available, `rejected` SHOULD be used as value for `err | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `rejected` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `otlp_grpc_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [3] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. diff --git a/model/otel/registry.yaml b/model/otel/registry.yaml index 77e95e43d1..5e9c6887b0 100644 --- a/model/otel/registry.yaml +++ b/model/otel/registry.yaml @@ -100,4 +100,4 @@ groups: With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. - examples: ["otlp_grpc_exporter/0", "custom-name"] + examples: ["otlp_grpc_span_exporter/0", "custom-name"] From 02a4ca66cb050b9de9d6cb97811941722545cc96 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Thu, 30 Jan 2025 11:05:35 +0100 Subject: [PATCH 31/41] remove spans-created metric --- docs/otel/sdk-metrics.md | 25 ------------------------- model/otel/metrics.yaml | 11 ----------- 2 files changed, 36 deletions(-) diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index cec62f15a3..ae6b8af07d 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -13,7 +13,6 @@ This document describes metrics emitted by the OpenTelemetry SDK components them - [Span Metrics](#span-metrics) - - [Metric: `otel.sdk.span.created_count`](#metric-otelsdkspancreated_count) - [Metric: `otel.sdk.span.live_count`](#metric-otelsdkspanlive_count) - [Metric: `otel.sdk.span.ended_count`](#metric-otelsdkspanended_count) - [Metric: `otel.sdk.span.processor.queue_size`](#metric-otelsdkspanprocessorqueue_size) @@ -26,30 +25,6 @@ This document describes metrics emitted by the OpenTelemetry SDK components them ## Span Metrics -### Metric: `otel.sdk.span.created_count` - -This metric is [recommended][MetricRecommended]. - - - - - - - - -| Name | Instrument Type | Unit (UCUM) | Description | Stability | -| -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.created_count` | Counter | `{span}` | The number of spans which have been created | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`otel.span.is_sampled`](/docs/attributes-registry/otel.md) | boolean | The sampled trace flag of the span | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - - - - - - ### Metric: `otel.sdk.span.live_count` This metric is [recommended][MetricRecommended]. diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml index 362b102aa5..0609ec0fc4 100644 --- a/model/otel/metrics.yaml +++ b/model/otel/metrics.yaml @@ -1,14 +1,4 @@ groups: - - id: metric.otel.sdk.span.created_count - type: metric - metric_name: otel.sdk.span.created_count - stability: development - brief: "The number of spans which have been created" - instrument: counter - unit: "{span}" - attributes: - - ref: otel.span.is_sampled - - id: metric.otel.sdk.span.live_count type: metric metric_name: otel.sdk.span.live_count @@ -29,7 +19,6 @@ groups: attributes: - ref: otel.span.is_sampled - - id: metric.otel.sdk.span.processor.queue_size type: metric metric_name: otel.sdk.span.processor.queue_size From df27efdd76f878bad8779ba6ea33b0cf717e26a8 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Thu, 30 Jan 2025 12:30:51 +0100 Subject: [PATCH 32/41] make queue capacity an updowncounter --- docs/otel/sdk-metrics.md | 2 +- model/otel/metrics.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index ae6b8af07d..26d5d7d598 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -142,7 +142,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.processor.queue_capacity` | Gauge | `{span}` | The maximum number of spans the queue of a given instance of an SDK span processor can hold [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.processor.queue_capacity` | UpDownCounter | `{span}` | The maximum number of spans the queue of a given instance of an SDK span processor can hold [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml index 0609ec0fc4..45641a7384 100644 --- a/model/otel/metrics.yaml +++ b/model/otel/metrics.yaml @@ -39,7 +39,7 @@ groups: brief: "The maximum number of spans the queue of a given instance of an SDK span processor can hold" note: | Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. - instrument: gauge + instrument: updowncounter unit: "{span}" attributes: - ref: otel.sdk.component.type From 33cf4b35fdcd2385c84a41f45836ab5e291a4a13 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Thu, 30 Jan 2025 12:45:25 +0100 Subject: [PATCH 33/41] Replace is_sampled with sampling_result --- docs/attributes-registry/otel.md | 12 +++++++++++- docs/otel/sdk-metrics.md | 24 ++++++++++++++++++++++-- model/otel/metrics.yaml | 4 ++-- model/otel/registry.yaml | 19 ++++++++++++++++--- 4 files changed, 51 insertions(+), 8 deletions(-) diff --git a/docs/attributes-registry/otel.md b/docs/attributes-registry/otel.md index 5aff048e35..daade1c7bf 100644 --- a/docs/attributes-registry/otel.md +++ b/docs/attributes-registry/otel.md @@ -14,12 +14,22 @@ Attributes reserved for OpenTelemetry | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `otel.span.is_sampled` | boolean | The sampled trace flag of the span | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.span.sampling_result` | string | The result value of the sampler for this span | `DROP`; `RECORD_ONLY`; `RECORD_AND_SAMPLE` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `otel.status_code` | string | Name of the code, either "OK" or "ERROR". MUST NOT be set if the status code is UNSET. | `OK`; `ERROR` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `otel.status_description` | string | Description of the Status if it has a value, otherwise not set. | `resource not found` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | --- +`otel.span.sampling_result` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `DROP` | The span is not sampled and not recording | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `RECORD_AND_SAMPLE` | The span is sampled and recording | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `RECORD_ONLY` | The span is not sampled, but recording | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +--- + `otel.status_code` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index 26d5d7d598..aabcf9e4e5 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -42,7 +42,17 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`otel.span.is_sampled`](/docs/attributes-registry/otel.md) | boolean | The sampled trace flag of the span | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.span.sampling_result`](/docs/attributes-registry/otel.md) | string | The result value of the sampler for this span | `DROP`; `RECORD_ONLY`; `RECORD_AND_SAMPLE` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +--- + +`otel.span.sampling_result` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `DROP` | The span is not sampled and not recording | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `RECORD_AND_SAMPLE` | The span is sampled and recording | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `RECORD_ONLY` | The span is not sampled, but recording | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -66,7 +76,17 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`otel.span.is_sampled`](/docs/attributes-registry/otel.md) | boolean | The sampled trace flag of the span | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.span.sampling_result`](/docs/attributes-registry/otel.md) | string | The result value of the sampler for this span | `DROP`; `RECORD_ONLY`; `RECORD_AND_SAMPLE` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +--- + +`otel.span.sampling_result` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `DROP` | The span is not sampled and not recording | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `RECORD_AND_SAMPLE` | The span is sampled and recording | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `RECORD_ONLY` | The span is not sampled, but recording | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml index 45641a7384..40ee82cca4 100644 --- a/model/otel/metrics.yaml +++ b/model/otel/metrics.yaml @@ -7,7 +7,7 @@ groups: instrument: updowncounter unit: "{span}" attributes: - - ref: otel.span.is_sampled + - ref: otel.span.sampling_result - id: metric.otel.sdk.span.ended_count type: metric @@ -17,7 +17,7 @@ groups: instrument: counter unit: "{span}" attributes: - - ref: otel.span.is_sampled + - ref: otel.span.sampling_result - id: metric.otel.sdk.span.processor.queue_size type: metric diff --git a/model/otel/registry.yaml b/model/otel/registry.yaml index 5e9c6887b0..84e6a5abc0 100644 --- a/model/otel/registry.yaml +++ b/model/otel/registry.yaml @@ -22,9 +22,22 @@ groups: brief: "Description of the Status if it has a value, otherwise not set." examples: ['resource not found'] stability: stable - - id: otel.span.is_sampled - type: boolean - brief: "The sampled trace flag of the span" + - id: otel.span.sampling_result + type: + members: + - id: drop + value: DROP + brief: 'The span is not sampled and not recording' + stability: development + - id: record_only + value: RECORD_ONLY + brief: 'The span is not sampled, but recording' + stability: development + - id: record_and_sample + value: RECORD_AND_SAMPLE + brief: 'The span is sampled and recording' + stability: development + brief: "The result value of the sampler for this span" stability: development - id: registry.otel.scope type: attribute_group From a89cc1f2dc863f1f90dcca4b872a53d5927f4dcb Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Thu, 30 Jan 2025 12:54:15 +0100 Subject: [PATCH 34/41] Clarify unrecorded spans handling --- docs/otel/sdk-metrics.md | 10 ++++++++-- model/otel/metrics.yaml | 6 ++++++ 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index aabcf9e4e5..952ff1cca9 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -38,7 +38,10 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.live_count` | UpDownCounter | `{span}` | The number of created spans for which the end operation has not been called yet | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.live_count` | UpDownCounter | `{span}` | The number of created spans for which the end operation has not been called yet [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live_count` and `otel.sdk.span.ended_count`otel.sdk.component.name`. +For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live_count` and `otel.sdk.span.ended_count`otel.sdk.component.name` or none. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -72,7 +75,10 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.ended_count` | Counter | `{span}` | The number of created spans for which the end operation was called | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.ended_count` | Counter | `{span}` | The number of created spans for which the end operation was called [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live_count` and `otel.sdk.span.ended_count`otel.sdk.component.name`. +For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live_count` and `otel.sdk.span.ended_count`otel.sdk.component.name` or none. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml index 40ee82cca4..5860f3428d 100644 --- a/model/otel/metrics.yaml +++ b/model/otel/metrics.yaml @@ -6,6 +6,9 @@ groups: brief: "The number of created spans for which the end operation has not been called yet" instrument: updowncounter unit: "{span}" + note: | + For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live_count` and `otel.sdk.span.ended_count`otel.sdk.component.name`. + For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live_count` and `otel.sdk.span.ended_count`otel.sdk.component.name` or none. attributes: - ref: otel.span.sampling_result @@ -16,6 +19,9 @@ groups: brief: "The number of created spans for which the end operation was called" instrument: counter unit: "{span}" + note: | + For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live_count` and `otel.sdk.span.ended_count`otel.sdk.component.name`. + For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live_count` and `otel.sdk.span.ended_count`otel.sdk.component.name` or none. attributes: - ref: otel.span.sampling_result From 0070795f3d6fc01705feaf4ea955bd75bcf7261f Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Thu, 30 Jan 2025 12:56:07 +0100 Subject: [PATCH 35/41] Fix example typo --- docs/attributes-registry/otel.md | 2 +- docs/otel/sdk-metrics.md | 10 +++++----- model/otel/registry.yaml | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/attributes-registry/otel.md b/docs/attributes-registry/otel.md index daade1c7bf..49bc3bf133 100644 --- a/docs/attributes-registry/otel.md +++ b/docs/attributes-registry/otel.md @@ -53,7 +53,7 @@ Attributes used for OpenTelemetry SDK self-monitoring | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| | `otel.sdk.component.name` | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otel.sdk.component.type` | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `co.example.MySpanExporter` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.component.type` | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `com.example.MySpanExporter` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. E.g. implementations MUST NOT use UUIDs as values for this attribute. diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index 952ff1cca9..3df90e2ad9 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -119,7 +119,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `com.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. E.g. implementations MUST NOT use UUIDs as values for this attribute. @@ -175,7 +175,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `com.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. E.g. implementations MUST NOT use UUIDs as values for this attribute. @@ -233,7 +233,7 @@ For the SDK Simple and Batching Span Processor a span is considered to be proces |---|---|---|---|---|---| | [`error.type`](/docs/attributes-registry/error.md) | string | A low-cardinality description of the failure reason. SDK Batching Span Processors MUST use `queue_full` for spans dropped due to a full queue. [1] | `queue_full` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [3] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [3] | `batching_span_processor`; `com.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. @@ -317,7 +317,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `com.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. E.g. implementations MUST NOT use UUIDs as values for this attribute. @@ -376,7 +376,7 @@ If no rejection reason is available, `rejected` SHOULD be used as value for `err |---|---|---|---|---|---| | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `rejected` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [3] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [3] | `batching_span_processor`; `com.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. diff --git a/model/otel/registry.yaml b/model/otel/registry.yaml index 84e6a5abc0..d219f26f85 100644 --- a/model/otel/registry.yaml +++ b/model/otel/registry.yaml @@ -93,7 +93,7 @@ groups: note: | If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. E.g. for Java the fully qualified classname SHOULD be used in this case. - examples: ["batching_span_processor", "co.example.MySpanExporter"] + examples: ["batching_span_processor", "com.example.MySpanExporter"] - id: otel.sdk.component.name type: string stability: development From 1f73e44f069016303b76071b14e41dd828bf582c Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Fri, 31 Jan 2025 12:49:43 +0100 Subject: [PATCH 36/41] Replace underscores with dots in metric names --- docs/otel/sdk-metrics.md | 64 ++++++++++++++++++++-------------------- model/otel/metrics.yaml | 36 +++++++++++----------- 2 files changed, 50 insertions(+), 50 deletions(-) diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index 3df90e2ad9..8c8b6ac31e 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -13,23 +13,23 @@ This document describes metrics emitted by the OpenTelemetry SDK components them - [Span Metrics](#span-metrics) - - [Metric: `otel.sdk.span.live_count`](#metric-otelsdkspanlive_count) - - [Metric: `otel.sdk.span.ended_count`](#metric-otelsdkspanended_count) - - [Metric: `otel.sdk.span.processor.queue_size`](#metric-otelsdkspanprocessorqueue_size) - - [Metric: `otel.sdk.span.processor.queue_capacity`](#metric-otelsdkspanprocessorqueue_capacity) - - [Metric: `otel.sdk.span.processor.spans_processed`](#metric-otelsdkspanprocessorspans_processed) - - [Metric: `otel.sdk.span.exporter.spans_inflight`](#metric-otelsdkspanexporterspans_inflight) - - [Metric: `otel.sdk.span.exporter.spans_exported`](#metric-otelsdkspanexporterspans_exported) + - [Metric: `otel.sdk.span.live.count`](#metric-otelsdkspanlivecount) + - [Metric: `otel.sdk.span.ended.count`](#metric-otelsdkspanendedcount) + - [Metric: `otel.sdk.span.processor.queue.size`](#metric-otelsdkspanprocessorqueuesize) + - [Metric: `otel.sdk.span.processor.queue.capacity`](#metric-otelsdkspanprocessorqueuecapacity) + - [Metric: `otel.sdk.span.processor.spans.processed`](#metric-otelsdkspanprocessorspansprocessed) + - [Metric: `otel.sdk.span.exporter.spans.inflight`](#metric-otelsdkspanexporterspansinflight) + - [Metric: `otel.sdk.span.exporter.spans.exported`](#metric-otelsdkspanexporterspansexported) ## Span Metrics -### Metric: `otel.sdk.span.live_count` +### Metric: `otel.sdk.span.live.count` This metric is [recommended][MetricRecommended]. - + @@ -38,10 +38,10 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.live_count` | UpDownCounter | `{span}` | The number of created spans for which the end operation has not been called yet [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.live.count` | UpDownCounter | `{span}` | The number of created spans for which the end operation has not been called yet [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live_count` and `otel.sdk.span.ended_count`otel.sdk.component.name`. -For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live_count` and `otel.sdk.span.ended_count`otel.sdk.component.name` or none. +**[1]:** For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`otel.sdk.component.name`. +For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`otel.sdk.component.name` or none. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -62,11 +62,11 @@ For spans with `recording=false` implementations MUST either record both `metric -### Metric: `otel.sdk.span.ended_count` +### Metric: `otel.sdk.span.ended.count` This metric is [recommended][MetricRecommended]. - + @@ -75,10 +75,10 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.ended_count` | Counter | `{span}` | The number of created spans for which the end operation was called [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.ended.count` | Counter | `{span}` | The number of created spans for which the end operation was called [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live_count` and `otel.sdk.span.ended_count`otel.sdk.component.name`. -For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live_count` and `otel.sdk.span.ended_count`otel.sdk.component.name` or none. +**[1]:** For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`otel.sdk.component.name`. +For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`otel.sdk.component.name` or none. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -99,11 +99,11 @@ For spans with `recording=false` implementations MUST either record both `metric -### Metric: `otel.sdk.span.processor.queue_size` +### Metric: `otel.sdk.span.processor.queue.size` This metric is [recommended][MetricRecommended]. - + @@ -112,7 +112,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.processor.queue_size` | UpDownCounter | `{span}` | The number of spans in the queue of a given instance of an SDK span processor [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.processor.queue.size` | UpDownCounter | `{span}` | The number of spans in the queue of a given instance of an SDK span processor [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. @@ -155,11 +155,11 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. -### Metric: `otel.sdk.span.processor.queue_capacity` +### Metric: `otel.sdk.span.processor.queue.capacity` This metric is [recommended][MetricRecommended]. - + @@ -168,7 +168,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.processor.queue_capacity` | UpDownCounter | `{span}` | The maximum number of spans the queue of a given instance of an SDK span processor can hold [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.processor.queue.capacity` | UpDownCounter | `{span}` | The maximum number of spans the queue of a given instance of an SDK span processor can hold [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. @@ -211,11 +211,11 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. -### Metric: `otel.sdk.span.processor.spans_processed` +### Metric: `otel.sdk.span.processor.spans.processed` This metric is [recommended][MetricRecommended]. - + @@ -224,7 +224,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.processor.spans_processed` | Counter | `{span}` | The number of spans for which the processing has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.processor.spans.processed` | Counter | `{span}` | The number of spans for which the processing has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** For successful processing, `error.type` must be empty. For failed processing, `error.type` must contain the failure cause. For the SDK Simple and Batching Span Processor a span is considered to be processed already when it has been submitted to the exporter, not when the corresponding export call has finished. @@ -297,11 +297,11 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. -### Metric: `otel.sdk.span.exporter.spans_inflight` +### Metric: `otel.sdk.span.exporter.spans.inflight` This metric is [recommended][MetricRecommended]. - + @@ -310,7 +310,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.exporter.spans_inflight` | UpDownCounter | `{span}` | The number of spans which were passed to the exporter, but that have not been exported yet (neither successful, nor failed) [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.exporter.spans.inflight` | UpDownCounter | `{span}` | The number of spans which were passed to the exporter, but that have not been exported yet (neither successful, nor failed) [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. @@ -353,11 +353,11 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. -### Metric: `otel.sdk.span.exporter.spans_exported` +### Metric: `otel.sdk.span.exporter.spans.exported` This metric is [recommended][MetricRecommended]. - + @@ -366,7 +366,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.exporter.spans_exported` | Counter | `{span}` | The number of spans for which the export has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.span.exporter.spans.exported` | Counter | `{span}` | The number of spans for which the export has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. For exporters with partial success semantics (e.g. OTLP with `rejected_spans`), rejected spans must count as failed and only non-rejected spans count as success. diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml index 5860f3428d..cfef685e32 100644 --- a/model/otel/metrics.yaml +++ b/model/otel/metrics.yaml @@ -1,33 +1,33 @@ groups: - - id: metric.otel.sdk.span.live_count + - id: metric.otel.sdk.span.live.count type: metric - metric_name: otel.sdk.span.live_count + metric_name: otel.sdk.span.live.count stability: development brief: "The number of created spans for which the end operation has not been called yet" instrument: updowncounter unit: "{span}" note: | - For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live_count` and `otel.sdk.span.ended_count`otel.sdk.component.name`. - For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live_count` and `otel.sdk.span.ended_count`otel.sdk.component.name` or none. + For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`otel.sdk.component.name`. + For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`otel.sdk.component.name` or none. attributes: - ref: otel.span.sampling_result - - id: metric.otel.sdk.span.ended_count + - id: metric.otel.sdk.span.ended.count type: metric - metric_name: otel.sdk.span.ended_count + metric_name: otel.sdk.span.ended.count stability: development brief: "The number of created spans for which the end operation was called" instrument: counter unit: "{span}" note: | - For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live_count` and `otel.sdk.span.ended_count`otel.sdk.component.name`. - For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live_count` and `otel.sdk.span.ended_count`otel.sdk.component.name` or none. + For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`otel.sdk.component.name`. + For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`otel.sdk.component.name` or none. attributes: - ref: otel.span.sampling_result - - id: metric.otel.sdk.span.processor.queue_size + - id: metric.otel.sdk.span.processor.queue.size type: metric - metric_name: otel.sdk.span.processor.queue_size + metric_name: otel.sdk.span.processor.queue.size stability: development brief: "The number of spans in the queue of a given instance of an SDK span processor" note: | @@ -38,9 +38,9 @@ groups: - ref: otel.sdk.component.type - ref: otel.sdk.component.name - - id: metric.otel.sdk.span.processor.queue_capacity + - id: metric.otel.sdk.span.processor.queue.capacity type: metric - metric_name: otel.sdk.span.processor.queue_capacity + metric_name: otel.sdk.span.processor.queue.capacity stability: development brief: "The maximum number of spans the queue of a given instance of an SDK span processor can hold" note: | @@ -51,9 +51,9 @@ groups: - ref: otel.sdk.component.type - ref: otel.sdk.component.name - - id: metric.otel.sdk.span.processor.spans_processed + - id: metric.otel.sdk.span.processor.spans.processed type: metric - metric_name: otel.sdk.span.processor.spans_processed + metric_name: otel.sdk.span.processor.spans.processed stability: development brief: "The number of spans for which the processing has finished, either successful or failed" note: | @@ -69,9 +69,9 @@ groups: A low-cardinality description of the failure reason. SDK Batching Span Processors MUST use `queue_full` for spans dropped due to a full queue. examples: ["queue_full"] - - id: metric.otel.sdk.span.exporter.spans_inflight + - id: metric.otel.sdk.span.exporter.spans.inflight type: metric - metric_name: otel.sdk.span.exporter.spans_inflight + metric_name: otel.sdk.span.exporter.spans.inflight stability: development brief: "The number of spans which were passed to the exporter, but that have not been exported yet (neither successful, nor failed)" note: | @@ -82,9 +82,9 @@ groups: - ref: otel.sdk.component.type - ref: otel.sdk.component.name - - id: metric.otel.sdk.span.exporter.spans_exported + - id: metric.otel.sdk.span.exporter.spans.exported type: metric - metric_name: otel.sdk.span.exporter.spans_exported + metric_name: otel.sdk.span.exporter.spans.exported stability: development brief: "The number of spans for which the export has finished, either successful or failed" note: | From 48b62c832f5fab602cfd07106a5ccfcafa1ecdf9 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Fri, 31 Jan 2025 13:19:05 +0100 Subject: [PATCH 37/41] Rename exporter metrics --- docs/otel/sdk-metrics.md | 16 ++++++++-------- model/otel/metrics.yaml | 8 ++++---- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index 8c8b6ac31e..7402848062 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -18,8 +18,8 @@ This document describes metrics emitted by the OpenTelemetry SDK components them - [Metric: `otel.sdk.span.processor.queue.size`](#metric-otelsdkspanprocessorqueuesize) - [Metric: `otel.sdk.span.processor.queue.capacity`](#metric-otelsdkspanprocessorqueuecapacity) - [Metric: `otel.sdk.span.processor.spans.processed`](#metric-otelsdkspanprocessorspansprocessed) - - [Metric: `otel.sdk.span.exporter.spans.inflight`](#metric-otelsdkspanexporterspansinflight) - - [Metric: `otel.sdk.span.exporter.spans.exported`](#metric-otelsdkspanexporterspansexported) + - [Metric: `otel.sdk.exporter.span.inflight.count`](#metric-otelsdkexporterspaninflightcount) + - [Metric: `otel.sdk.exporter.span.exported.count`](#metric-otelsdkexporterspanexportedcount) @@ -297,11 +297,11 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. -### Metric: `otel.sdk.span.exporter.spans.inflight` +### Metric: `otel.sdk.exporter.span.inflight.count` This metric is [recommended][MetricRecommended]. - + @@ -310,7 +310,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.exporter.spans.inflight` | UpDownCounter | `{span}` | The number of spans which were passed to the exporter, but that have not been exported yet (neither successful, nor failed) [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.exporter.span.inflight.count` | UpDownCounter | `{span}` | The number of spans which were passed to the exporter, but that have not been exported yet (neither successful, nor failed) [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. @@ -353,11 +353,11 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. -### Metric: `otel.sdk.span.exporter.spans.exported` +### Metric: `otel.sdk.exporter.span.exported.count` This metric is [recommended][MetricRecommended]. - + @@ -366,7 +366,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.exporter.spans.exported` | Counter | `{span}` | The number of spans for which the export has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.exporter.span.exported.count` | Counter | `{span}` | The number of spans for which the export has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. For exporters with partial success semantics (e.g. OTLP with `rejected_spans`), rejected spans must count as failed and only non-rejected spans count as success. diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml index cfef685e32..466e6b686e 100644 --- a/model/otel/metrics.yaml +++ b/model/otel/metrics.yaml @@ -69,9 +69,9 @@ groups: A low-cardinality description of the failure reason. SDK Batching Span Processors MUST use `queue_full` for spans dropped due to a full queue. examples: ["queue_full"] - - id: metric.otel.sdk.span.exporter.spans.inflight + - id: metric.otel.sdk.exporter.span.inflight.count type: metric - metric_name: otel.sdk.span.exporter.spans.inflight + metric_name: otel.sdk.exporter.span.inflight.count stability: development brief: "The number of spans which were passed to the exporter, but that have not been exported yet (neither successful, nor failed)" note: | @@ -82,9 +82,9 @@ groups: - ref: otel.sdk.component.type - ref: otel.sdk.component.name - - id: metric.otel.sdk.span.exporter.spans.exported + - id: metric.otel.sdk.exporter.span.exported.count type: metric - metric_name: otel.sdk.span.exporter.spans.exported + metric_name: otel.sdk.exporter.span.exported.count stability: development brief: "The number of spans for which the export has finished, either successful or failed" note: | From 830edfb15972eb6ff2c7475996f1bcd3fec340ba Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Fri, 31 Jan 2025 13:30:07 +0100 Subject: [PATCH 38/41] Add server.* attributes to exporter metrics --- docs/otel/sdk-metrics.md | 12 ++++++++++++ model/otel/metrics.yaml | 8 ++++++++ 2 files changed, 20 insertions(+) diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index 7402848062..cd0c69b57e 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -318,6 +318,8 @@ This metric is [recommended][MetricRecommended]. |---|---|---|---|---|---| | [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `com.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. E.g. implementations MUST NOT use UUIDs as values for this attribute. @@ -336,6 +338,10 @@ These values will therefore be reused in the case of an application restart. **[2] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. E.g. for Java the fully qualified classname SHOULD be used in this case. +**[3] `server.address`:** recommended when applicable + +**[4] `server.port`:** recommended when applicable + --- `otel.sdk.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. @@ -377,6 +383,8 @@ If no rejection reason is available, `rejected` SHOULD be used as value for `err | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `rejected` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [3] | `batching_span_processor`; `com.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [5] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. @@ -415,6 +423,10 @@ These values will therefore be reused in the case of an application restart. **[3] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. E.g. for Java the fully qualified classname SHOULD be used in this case. +**[4] `server.address`:** recommended when applicable + +**[5] `server.port`:** recommended when applicable + --- `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml index 466e6b686e..949de6230b 100644 --- a/model/otel/metrics.yaml +++ b/model/otel/metrics.yaml @@ -81,6 +81,10 @@ groups: attributes: - ref: otel.sdk.component.type - ref: otel.sdk.component.name + - ref: server.address + note: recommended when applicable + - ref: server.port + note: recommended when applicable - id: metric.otel.sdk.exporter.span.exported.count type: metric @@ -96,5 +100,9 @@ groups: attributes: - ref: otel.sdk.component.type - ref: otel.sdk.component.name + - ref: server.address + note: recommended when applicable + - ref: server.port + note: recommended when applicable - ref: error.type examples: ["rejected"] From 1bb28fee8420863a498ed9024c7d888908d366d2 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Mon, 3 Feb 2025 09:44:48 +0100 Subject: [PATCH 39/41] Renamed span processor metrics --- docs/otel/sdk-metrics.md | 24 ++++++++++++------------ model/otel/metrics.yaml | 12 ++++++------ 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index cd0c69b57e..dadfcaaf22 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -15,9 +15,9 @@ This document describes metrics emitted by the OpenTelemetry SDK components them - [Span Metrics](#span-metrics) - [Metric: `otel.sdk.span.live.count`](#metric-otelsdkspanlivecount) - [Metric: `otel.sdk.span.ended.count`](#metric-otelsdkspanendedcount) - - [Metric: `otel.sdk.span.processor.queue.size`](#metric-otelsdkspanprocessorqueuesize) - - [Metric: `otel.sdk.span.processor.queue.capacity`](#metric-otelsdkspanprocessorqueuecapacity) - - [Metric: `otel.sdk.span.processor.spans.processed`](#metric-otelsdkspanprocessorspansprocessed) + - [Metric: `otel.sdk.processor.span.queue.size`](#metric-otelsdkprocessorspanqueuesize) + - [Metric: `otel.sdk.processor.span.queue.capacity`](#metric-otelsdkprocessorspanqueuecapacity) + - [Metric: `otel.sdk.processor.span.processed.count`](#metric-otelsdkprocessorspanprocessedcount) - [Metric: `otel.sdk.exporter.span.inflight.count`](#metric-otelsdkexporterspaninflightcount) - [Metric: `otel.sdk.exporter.span.exported.count`](#metric-otelsdkexporterspanexportedcount) @@ -99,11 +99,11 @@ For spans with `recording=false` implementations MUST either record both `metric -### Metric: `otel.sdk.span.processor.queue.size` +### Metric: `otel.sdk.processor.span.queue.size` This metric is [recommended][MetricRecommended]. - + @@ -112,7 +112,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.processor.queue.size` | UpDownCounter | `{span}` | The number of spans in the queue of a given instance of an SDK span processor [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.processor.span.queue.size` | UpDownCounter | `{span}` | The number of spans in the queue of a given instance of an SDK span processor [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. @@ -155,11 +155,11 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. -### Metric: `otel.sdk.span.processor.queue.capacity` +### Metric: `otel.sdk.processor.span.queue.capacity` This metric is [recommended][MetricRecommended]. - + @@ -168,7 +168,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.processor.queue.capacity` | UpDownCounter | `{span}` | The maximum number of spans the queue of a given instance of an SDK span processor can hold [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.processor.span.queue.capacity` | UpDownCounter | `{span}` | The maximum number of spans the queue of a given instance of an SDK span processor can hold [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. @@ -211,11 +211,11 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. -### Metric: `otel.sdk.span.processor.spans.processed` +### Metric: `otel.sdk.processor.span.processed.count` This metric is [recommended][MetricRecommended]. - + @@ -224,7 +224,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `otel.sdk.span.processor.spans.processed` | Counter | `{span}` | The number of spans for which the processing has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.processor.span.processed.count` | Counter | `{span}` | The number of spans for which the processing has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** For successful processing, `error.type` must be empty. For failed processing, `error.type` must contain the failure cause. For the SDK Simple and Batching Span Processor a span is considered to be processed already when it has been submitted to the exporter, not when the corresponding export call has finished. diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml index 949de6230b..1abdff9f16 100644 --- a/model/otel/metrics.yaml +++ b/model/otel/metrics.yaml @@ -25,9 +25,9 @@ groups: attributes: - ref: otel.span.sampling_result - - id: metric.otel.sdk.span.processor.queue.size + - id: metric.otel.sdk.processor.span.queue.size type: metric - metric_name: otel.sdk.span.processor.queue.size + metric_name: otel.sdk.processor.span.queue.size stability: development brief: "The number of spans in the queue of a given instance of an SDK span processor" note: | @@ -38,9 +38,9 @@ groups: - ref: otel.sdk.component.type - ref: otel.sdk.component.name - - id: metric.otel.sdk.span.processor.queue.capacity + - id: metric.otel.sdk.processor.span.queue.capacity type: metric - metric_name: otel.sdk.span.processor.queue.capacity + metric_name: otel.sdk.processor.span.queue.capacity stability: development brief: "The maximum number of spans the queue of a given instance of an SDK span processor can hold" note: | @@ -51,9 +51,9 @@ groups: - ref: otel.sdk.component.type - ref: otel.sdk.component.name - - id: metric.otel.sdk.span.processor.spans.processed + - id: metric.otel.sdk.processor.span.processed.count type: metric - metric_name: otel.sdk.span.processor.spans.processed + metric_name: otel.sdk.processor.span.processed.count stability: development brief: "The number of spans for which the processing has finished, either successful or failed" note: | From 53a806ac53f84d15f2ff7492a62681ec6b5dc5ea Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Mon, 3 Feb 2025 09:55:46 +0100 Subject: [PATCH 40/41] Renamed component attributes --- docs/attributes-registry/otel.md | 40 +++++++-------- docs/otel/sdk-metrics.md | 88 ++++++++++++++++---------------- model/otel/metrics.yaml | 28 +++++----- model/otel/registry.yaml | 20 ++++---- 4 files changed, 88 insertions(+), 88 deletions(-) diff --git a/docs/attributes-registry/otel.md b/docs/attributes-registry/otel.md index 49bc3bf133..a750491f79 100644 --- a/docs/attributes-registry/otel.md +++ b/docs/attributes-registry/otel.md @@ -4,8 +4,8 @@ # OTel - [OTel Attributes](#otel-attributes) +- [OTel Component Attributes](#otel-component-attributes) - [OTel Scope Attributes](#otel-scope-attributes) -- [OTel SDK Telemetry Attributes](#otel-sdk-telemetry-attributes) - [Deprecated OTel Library Attributes](#deprecated-otel-library-attributes) ## OTel Attributes @@ -37,44 +37,35 @@ Attributes reserved for OpenTelemetry | `ERROR` | The operation contains an error. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `OK` | The operation has been validated by an Application developer or Operator to have completed successfully. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -## OTel Scope Attributes - -Attributes used by non-OTLP exporters to represent OpenTelemetry Scope's concepts. - -| Attribute | Type | Description | Examples | Stability | -|---|---|---|---|---| -| `otel.scope.name` | string | The name of the instrumentation scope - (`InstrumentationScope.Name` in OTLP). | `io.opentelemetry.contrib.mongodb` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `otel.scope.version` | string | The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). | `1.0.0` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - -## OTel SDK Telemetry Attributes +## OTel Component Attributes -Attributes used for OpenTelemetry SDK self-monitoring +Attributes used for OpenTelemetry component self-monitoring | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `otel.sdk.component.name` | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `otel.sdk.component.type` | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `com.example.MySpanExporter` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.component.name` | string | A name uniquely identifying the instance of the OpenTelemetry component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.component.type` | string | A name identifying the type of the OpenTelemetry component. [2] | `batching_span_processor`; `com.example.MySpanExporter` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. +**[1] `otel.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. E.g. implementations MUST NOT use UUIDs as values for this attribute. -Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. -Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. +Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. +Hereby `otel.component.type` refers to the corresponding attribute value of the component. The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` -as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +as `otel.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. -**[2] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. +**[2] `otel.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. E.g. for Java the fully qualified classname SHOULD be used in this case. --- -`otel.sdk.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +`otel.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| @@ -84,6 +75,15 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | `otlp_http_span_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +## OTel Scope Attributes + +Attributes used by non-OTLP exporters to represent OpenTelemetry Scope's concepts. + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `otel.scope.name` | string | The name of the instrumentation scope - (`InstrumentationScope.Name` in OTLP). | `io.opentelemetry.contrib.mongodb` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `otel.scope.version` | string | The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). | `1.0.0` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + ## Deprecated OTel Library Attributes Describes deprecated otel.library attributes. diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index dadfcaaf22..4a71ec383c 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -40,8 +40,8 @@ This metric is [recommended][MetricRecommended]. | -------- | --------------- | ----------- | -------------- | --------- | | `otel.sdk.span.live.count` | UpDownCounter | `{span}` | The number of created spans for which the end operation has not been called yet [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`otel.sdk.component.name`. -For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`otel.sdk.component.name` or none. +**[1]:** For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`. +For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count` or none. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -77,8 +77,8 @@ This metric is [recommended][MetricRecommended]. | -------- | --------------- | ----------- | -------------- | --------- | | `otel.sdk.span.ended.count` | Counter | `{span}` | The number of created spans for which the end operation was called [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`otel.sdk.component.name`. -For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`otel.sdk.component.name` or none. +**[1]:** For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`. +For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count` or none. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -118,29 +118,29 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `com.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry component. [2] | `batching_span_processor`; `com.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. +**[1] `otel.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. E.g. implementations MUST NOT use UUIDs as values for this attribute. -Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. -Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. +Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. +Hereby `otel.component.type` refers to the corresponding attribute value of the component. The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` -as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +as `otel.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. -**[2] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. +**[2] `otel.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. E.g. for Java the fully qualified classname SHOULD be used in this case. --- -`otel.sdk.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +`otel.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| @@ -174,29 +174,29 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `com.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry component. [2] | `batching_span_processor`; `com.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. +**[1] `otel.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. E.g. implementations MUST NOT use UUIDs as values for this attribute. -Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. -Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. +Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. +Hereby `otel.component.type` refers to the corresponding attribute value of the component. The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` -as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +as `otel.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. -**[2] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. +**[2] `otel.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. E.g. for Java the fully qualified classname SHOULD be used in this case. --- -`otel.sdk.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +`otel.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| @@ -232,8 +232,8 @@ For the SDK Simple and Batching Span Processor a span is considered to be proces | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`error.type`](/docs/attributes-registry/error.md) | string | A low-cardinality description of the failure reason. SDK Batching Span Processors MUST use `queue_full` for spans dropped due to a full queue. [1] | `queue_full` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [3] | `batching_span_processor`; `com.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry component within its containing SDK instance. [2] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry component. [3] | `batching_span_processor`; `com.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. @@ -255,21 +255,21 @@ it's RECOMMENDED to: - Use a domain-specific attribute - Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. -**[2] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. +**[2] `otel.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. E.g. implementations MUST NOT use UUIDs as values for this attribute. -Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. -Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. +Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. +Hereby `otel.component.type` refers to the corresponding attribute value of the component. The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` -as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +as `otel.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. -**[3] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. +**[3] `otel.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. E.g. for Java the fully qualified classname SHOULD be used in this case. --- @@ -282,7 +282,7 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. --- -`otel.sdk.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +`otel.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| @@ -316,26 +316,26 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `com.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry component. [2] | `batching_span_processor`; `com.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -**[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. +**[1] `otel.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. E.g. implementations MUST NOT use UUIDs as values for this attribute. -Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. -Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. +Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. +Hereby `otel.component.type` refers to the corresponding attribute value of the component. The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` -as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +as `otel.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. -**[2] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. +**[2] `otel.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. E.g. for Java the fully qualified classname SHOULD be used in this case. **[3] `server.address`:** recommended when applicable @@ -344,7 +344,7 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. --- -`otel.sdk.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +`otel.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| @@ -381,8 +381,8 @@ If no rejection reason is available, `rejected` SHOULD be used as value for `err | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `rejected` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [3] | `batching_span_processor`; `com.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry component within its containing SDK instance. [2] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry component. [3] | `batching_span_processor`; `com.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Server port number. [5] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -406,21 +406,21 @@ it's RECOMMENDED to: - Use a domain-specific attribute - Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. -**[2] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. +**[2] `otel.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. E.g. implementations MUST NOT use UUIDs as values for this attribute. -Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. -Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. +Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. +Hereby `otel.component.type` refers to the corresponding attribute value of the component. The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` -as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +as `otel.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. -**[3] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. +**[3] `otel.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. E.g. for Java the fully qualified classname SHOULD be used in this case. **[4] `server.address`:** recommended when applicable @@ -437,7 +437,7 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. --- -`otel.sdk.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +`otel.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml index 1abdff9f16..08ba069ef1 100644 --- a/model/otel/metrics.yaml +++ b/model/otel/metrics.yaml @@ -7,8 +7,8 @@ groups: instrument: updowncounter unit: "{span}" note: | - For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`otel.sdk.component.name`. - For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`otel.sdk.component.name` or none. + For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`. + For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count` or none. attributes: - ref: otel.span.sampling_result @@ -20,8 +20,8 @@ groups: instrument: counter unit: "{span}" note: | - For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`otel.sdk.component.name`. - For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`otel.sdk.component.name` or none. + For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`. + For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count` or none. attributes: - ref: otel.span.sampling_result @@ -35,8 +35,8 @@ groups: instrument: updowncounter unit: "{span}" attributes: - - ref: otel.sdk.component.type - - ref: otel.sdk.component.name + - ref: otel.component.type + - ref: otel.component.name - id: metric.otel.sdk.processor.span.queue.capacity type: metric @@ -48,8 +48,8 @@ groups: instrument: updowncounter unit: "{span}" attributes: - - ref: otel.sdk.component.type - - ref: otel.sdk.component.name + - ref: otel.component.type + - ref: otel.component.name - id: metric.otel.sdk.processor.span.processed.count type: metric @@ -62,8 +62,8 @@ groups: instrument: counter unit: "{span}" attributes: - - ref: otel.sdk.component.type - - ref: otel.sdk.component.name + - ref: otel.component.type + - ref: otel.component.name - ref: error.type brief: > A low-cardinality description of the failure reason. SDK Batching Span Processors MUST use `queue_full` for spans dropped due to a full queue. @@ -79,8 +79,8 @@ groups: instrument: updowncounter unit: "{span}" attributes: - - ref: otel.sdk.component.type - - ref: otel.sdk.component.name + - ref: otel.component.type + - ref: otel.component.name - ref: server.address note: recommended when applicable - ref: server.port @@ -98,8 +98,8 @@ groups: instrument: counter unit: "{span}" attributes: - - ref: otel.sdk.component.type - - ref: otel.sdk.component.name + - ref: otel.component.type + - ref: otel.component.name - ref: server.address note: recommended when applicable - ref: server.port diff --git a/model/otel/registry.yaml b/model/otel/registry.yaml index d219f26f85..4225712da2 100644 --- a/model/otel/registry.yaml +++ b/model/otel/registry.yaml @@ -54,12 +54,12 @@ groups: brief: The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). examples: ['1.0.0'] stability: stable - - id: registry.otel.sdk + - id: registry.otel.component type: attribute_group - display_name: OTel SDK Telemetry Attributes - brief: Attributes used for OpenTelemetry SDK self-monitoring + display_name: OTel Component Attributes + brief: Attributes used for OpenTelemetry component self-monitoring attributes: - - id: otel.sdk.component.type + - id: otel.component.type type: members: - id: batching_span_processor @@ -89,28 +89,28 @@ groups: stability: development stability: development brief: > - A name identifying the type of the OpenTelemetry SDK component. + A name identifying the type of the OpenTelemetry component. note: | If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. E.g. for Java the fully qualified classname SHOULD be used in this case. examples: ["batching_span_processor", "com.example.MySpanExporter"] - - id: otel.sdk.component.name + - id: otel.component.name type: string stability: development brief: > - A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. + A name uniquely identifying the instance of the OpenTelemetry component within its containing SDK instance. note: | Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. E.g. implementations MUST NOT use UUIDs as values for this attribute. - Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. - Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. + Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. + Hereby `otel.component.type` refers to the corresponding attribute value of the component. The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an instance of the given component type is started. With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` - as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. + as `otel.component.name`, the second one `batching_span_processor/1` and so on. These values will therefore be reused in the case of an application restart. examples: ["otlp_grpc_span_exporter/0", "custom-name"] From 9b18062f36f23868a247747b47e9d176aa9cc4e6 Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Mon, 3 Feb 2025 10:01:59 +0100 Subject: [PATCH 41/41] Add error.type examples, clarify handling of non-recording spans --- docs/otel/sdk-metrics.md | 6 +++--- model/otel/metrics.yaml | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index 4a71ec383c..863848d299 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -41,7 +41,7 @@ This metric is [recommended][MetricRecommended]. | `otel.sdk.span.live.count` | UpDownCounter | `{span}` | The number of created spans for which the end operation has not been called yet [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`. -For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count` or none. +For spans with `recording=false` implementations SHOULD record this metric, they MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count` or none. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -78,7 +78,7 @@ This metric is [recommended][MetricRecommended]. | `otel.sdk.span.ended.count` | Counter | `{span}` | The number of created spans for which the end operation was called [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`. -For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count` or none. +For spans with `recording=false` implementations SHOULD record this metric, they MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count` or none. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| @@ -380,7 +380,7 @@ If no rejection reason is available, `rejected` SHOULD be used as value for `err | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `rejected` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `rejected`; `timeout`; `500`; `java.net.UnknownHostException` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`otel.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry component within its containing SDK instance. [2] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`otel.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry component. [3] | `batching_span_processor`; `com.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml index 08ba069ef1..fbaaa40aee 100644 --- a/model/otel/metrics.yaml +++ b/model/otel/metrics.yaml @@ -8,7 +8,7 @@ groups: unit: "{span}" note: | For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`. - For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count` or none. + For spans with `recording=false` implementations SHOULD record this metric, they MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count` or none. attributes: - ref: otel.span.sampling_result @@ -21,7 +21,7 @@ groups: unit: "{span}" note: | For spans with `recording=true` implementations MUST record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count`. - For spans with `recording=false` implementations MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count` or none. + For spans with `recording=false` implementations SHOULD record this metric, they MUST either record both `metric.otel.sdk.span.live.count` and `otel.sdk.span.ended.count` or none. attributes: - ref: otel.span.sampling_result @@ -105,4 +105,4 @@ groups: - ref: server.port note: recommended when applicable - ref: error.type - examples: ["rejected"] + examples: ["rejected", "timeout", "500", "java.net.UnknownHostException"]