From 8f2b66656d09948cb7cbbe954dd36e06d9d5783e Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Fri, 29 Nov 2024 11:03:38 +0100 Subject: [PATCH 01/13] 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/13] 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/13] 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/13] 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/13] 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/13] 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/13] 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/13] 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/13] 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/13] 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/13] 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/13] 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/13] 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"]