diff --git a/.chloggen/sdk-span-metrics.yaml b/.chloggen/sdk-span-metrics.yaml new file mode 100644 index 0000000000..360ea4f2c4 --- /dev/null +++ b/.chloggen/sdk-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: 'otel' + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Adds SDK self-monitoring metrics for span processing + +# 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: diff --git a/docs/attributes-registry/otel.md b/docs/attributes-registry/otel.md index 2c236b530e..e21eeacac4 100644 --- a/docs/attributes-registry/otel.md +++ b/docs/attributes-registry/otel.md @@ -8,6 +8,7 @@ - [OTel Attributes](#otel-attributes) - [OTel Scope Attributes](#otel-scope-attributes) +- [OTel SDK Telemetry Attributes](#otel-sdk-telemetry-attributes) - [Deprecated OTel Library Attributes](#deprecated-otel-library-attributes) ## OTel Attributes @@ -16,6 +17,7 @@ Attributes reserved for OpenTelemetry | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| +| `otel.span.is_sampled` | boolean | The sampled trace flag of the span | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `otel.status_code` | string | Name of the code, either "OK" or "ERROR". MUST NOT be set if the status code is UNSET. | `OK`; `ERROR` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `otel.status_description` | string | Description of the Status if it has a value, otherwise not set. | `resource not found` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | @@ -37,6 +39,44 @@ Attributes used by non-OTLP exporters to represent OpenTelemetry Scope's concept | `otel.scope.name` | string | The name of the instrumentation scope - (`InstrumentationScope.Name` in OTLP). | `io.opentelemetry.contrib.mongodb` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `otel.scope.version` | string | The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). | `1.0.0` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +## OTel SDK Telemetry Attributes + +Attributes used for OpenTelemetry SDK self-monitoring + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `otel.sdk.component.name` | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otel.sdk.component.type` | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `co.example.MySpanExporter` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. +E.g. implementations MUST NOT use UUIDs as values for this attribute. + +Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. +Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. + +The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. +For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an +instance of the given component type is started. + +With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` +as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +These values will therefore be reused in the case of an application restart. + +**[2] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. +E.g. for Java the fully qualified classname SHOULD be used in this case. + +--- + +`otel.sdk.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_span_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_span_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_span_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + ## Deprecated OTel Library Attributes Describes deprecated otel.library attributes. diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 63a24f3179..618a6c0a54 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -34,6 +34,7 @@ The following semantic conventions surrounding metrics are defined: * [K8s](/docs/system/k8s-metrics.md): For K8s metrics. * [Process](/docs/system/process-metrics.md): For standard process metrics. * [Runtime Environment](/docs/runtime/README.md#metrics): For runtime environment metrics. +* [OTel SDK Telemetry](/docs/otel/sdk-metrics.md): Metrics emitted by the OpenTelemetry SDK components. Apart from semantic conventions for metrics, [traces](trace.md), [logs](logs.md), and [events](events.md), OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/resource/sdk.md) with diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md new file mode 100644 index 0000000000..cec62f15a3 --- /dev/null +++ b/docs/otel/sdk-metrics.md @@ -0,0 +1,443 @@ + + +# Semantic Conventions for OpenTelemetry SDK metrics + +**Status**: [Development][DocumentStatus] + +This document describes metrics emitted by the OpenTelemetry SDK components themselves about their internal state. + + + + + +- [Span Metrics](#span-metrics) + - [Metric: `otel.sdk.span.created_count`](#metric-otelsdkspancreated_count) + - [Metric: `otel.sdk.span.live_count`](#metric-otelsdkspanlive_count) + - [Metric: `otel.sdk.span.ended_count`](#metric-otelsdkspanended_count) + - [Metric: `otel.sdk.span.processor.queue_size`](#metric-otelsdkspanprocessorqueue_size) + - [Metric: `otel.sdk.span.processor.queue_capacity`](#metric-otelsdkspanprocessorqueue_capacity) + - [Metric: `otel.sdk.span.processor.spans_processed`](#metric-otelsdkspanprocessorspans_processed) + - [Metric: `otel.sdk.span.exporter.spans_inflight`](#metric-otelsdkspanexporterspans_inflight) + - [Metric: `otel.sdk.span.exporter.spans_exported`](#metric-otelsdkspanexporterspans_exported) + + + +## Span Metrics + +### Metric: `otel.sdk.span.created_count` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `otel.sdk.span.created_count` | Counter | `{span}` | The number of spans which have been created | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`otel.span.is_sampled`](/docs/attributes-registry/otel.md) | boolean | The sampled trace flag of the span | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `otel.sdk.span.live_count` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `otel.sdk.span.live_count` | UpDownCounter | `{span}` | The number of created spans for which the end operation has not been called yet | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`otel.span.is_sampled`](/docs/attributes-registry/otel.md) | boolean | The sampled trace flag of the span | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `otel.sdk.span.ended_count` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `otel.sdk.span.ended_count` | Counter | `{span}` | The number of created spans for which the end operation was called | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`otel.span.is_sampled`](/docs/attributes-registry/otel.md) | boolean | The sampled trace flag of the span | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `otel.sdk.span.processor.queue_size` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `otel.sdk.span.processor.queue_size` | UpDownCounter | `{span}` | The number of spans in the queue of a given instance of an SDK span processor [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[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 | +|---|---|---|---|---|---| +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. +E.g. implementations MUST NOT use UUIDs as values for this attribute. + +Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. +Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. + +The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. +For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an +instance of the given component type is started. + +With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` +as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +These values will therefore be reused in the case of an application restart. + +**[2] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. +E.g. for Java the fully qualified classname SHOULD be used in this case. + +--- + +`otel.sdk.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_span_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_span_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_span_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `otel.sdk.span.processor.queue_capacity` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `otel.sdk.span.processor.queue_capacity` | Gauge | `{span}` | The maximum number of spans the queue of a given instance of an SDK span processor can hold [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[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 | +|---|---|---|---|---|---| +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. +E.g. implementations MUST NOT use UUIDs as values for this attribute. + +Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. +Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. + +The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. +For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an +instance of the given component type is started. + +With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` +as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +These values will therefore be reused in the case of an application restart. + +**[2] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. +E.g. for Java the fully qualified classname SHOULD be used in this case. + +--- + +`otel.sdk.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_span_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_span_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_span_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `otel.sdk.span.processor.spans_processed` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `otel.sdk.span.processor.spans_processed` | Counter | `{span}` | The number of spans for which the processing has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** For successful processing, `error.type` must be empty. For failed processing, `error.type` must contain the failure cause. +For the SDK Simple and Batching Span Processor a span is considered to be processed already when it has been submitted to the exporter, not when the corresponding export call has finished. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`error.type`](/docs/attributes-registry/error.md) | string | A low-cardinality description of the failure reason. SDK Batching Span Processors MUST use `queue_full` for spans dropped due to a full queue. [1] | `queue_full` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [3] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. + +When `error.type` is set to a type (e.g., an exception type), its +canonical class name identifying the type within the artifact SHOULD be used. + +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low. +Telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time when no +additional filters are applied. + +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + +If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), +it's RECOMMENDED to: + +- Use a domain-specific attribute +- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. + +**[2] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. +E.g. implementations MUST NOT use UUIDs as values for this attribute. + +Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. +Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. + +The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. +For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an +instance of the given component type is started. + +With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` +as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +These values will therefore be reused in the case of an application restart. + +**[3] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. +E.g. for Java the fully qualified classname SHOULD be used in this case. + +--- + +`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +--- + +`otel.sdk.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_span_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_span_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_span_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `otel.sdk.span.exporter.spans_inflight` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `otel.sdk.span.exporter.spans_inflight` | UpDownCounter | `{span}` | The number of spans which were passed to the exporter, but that have not been exported yet (neither successful, nor failed) [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [2] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. +E.g. implementations MUST NOT use UUIDs as values for this attribute. + +Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. +Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. + +The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. +For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an +instance of the given component type is started. + +With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` +as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +These values will therefore be reused in the case of an application restart. + +**[2] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. +E.g. for Java the fully qualified classname SHOULD be used in this case. + +--- + +`otel.sdk.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_span_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_span_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_span_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `otel.sdk.span.exporter.spans_exported` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `otel.sdk.span.exporter.spans_exported` | Counter | `{span}` | The number of spans for which the export has finished, either successful or failed [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. +For exporters with partial success semantics (e.g. OTLP with `rejected_spans`), rejected spans must count as failed and only non-rejected spans count as success. +If no rejection reason is available, `rejected` SHOULD be used as value for `error.type`. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `rejected` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`otel.sdk.component.name`](/docs/attributes-registry/otel.md) | string | A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. [2] | `otlp_grpc_span_exporter/0`; `custom-name` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`otel.sdk.component.type`](/docs/attributes-registry/otel.md) | string | A name identifying the type of the OpenTelemetry SDK component. [3] | `batching_span_processor`; `co.example.MySpanExporter` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. + +When `error.type` is set to a type (e.g., an exception type), its +canonical class name identifying the type within the artifact SHOULD be used. + +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low. +Telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time when no +additional filters are applied. + +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + +If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), +it's RECOMMENDED to: + +- Use a domain-specific attribute +- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. + +**[2] `otel.sdk.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. +E.g. implementations MUST NOT use UUIDs as values for this attribute. + +Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. +Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. + +The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. +For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an +instance of the given component type is started. + +With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` +as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. +These values will therefore be reused in the case of an application restart. + +**[3] `otel.sdk.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. +E.g. for Java the fully qualified classname SHOULD be used in this case. + +--- + +`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +--- + +`otel.sdk.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `batching_span_processor` | The builtin SDK Batching Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_grpc_span_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_json_span_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `otlp_http_span_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `simple_span_processor` | The builtin SDK Simple Span Processor | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/model/otel/common.yaml b/model/otel/common.yaml index ddb8dd1e22..1051371079 100644 --- a/model/otel/common.yaml +++ b/model/otel/common.yaml @@ -1,7 +1,7 @@ groups: - id: otel_span type: attribute_group - brief: Span attributes used by non-OTLP exporters to represent OpenTelemetry Span's concepts. + brief: Span attributes used by non-OTLP exporters or on metrics to represent OpenTelemetry Span's concepts. attributes: - ref: otel.status_code requirement_level: recommended diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml new file mode 100644 index 0000000000..362b102aa5 --- /dev/null +++ b/model/otel/metrics.yaml @@ -0,0 +1,105 @@ +groups: + - id: metric.otel.sdk.span.created_count + type: metric + metric_name: otel.sdk.span.created_count + stability: development + brief: "The number of spans which have been created" + instrument: counter + unit: "{span}" + attributes: + - ref: otel.span.is_sampled + + - id: metric.otel.sdk.span.live_count + type: metric + metric_name: otel.sdk.span.live_count + stability: development + brief: "The number of created spans for which the end operation has not been called yet" + instrument: updowncounter + unit: "{span}" + attributes: + - ref: otel.span.is_sampled + + - id: metric.otel.sdk.span.ended_count + type: metric + metric_name: otel.sdk.span.ended_count + stability: development + brief: "The number of created spans for which the end operation was called" + instrument: counter + unit: "{span}" + attributes: + - ref: otel.span.is_sampled + + + - id: metric.otel.sdk.span.processor.queue_size + type: metric + metric_name: otel.sdk.span.processor.queue_size + stability: development + brief: "The number of spans in the queue of a given instance of an SDK span processor" + note: | + Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. + instrument: updowncounter + unit: "{span}" + attributes: + - ref: otel.sdk.component.type + - ref: otel.sdk.component.name + + - id: metric.otel.sdk.span.processor.queue_capacity + type: metric + metric_name: otel.sdk.span.processor.queue_capacity + stability: development + brief: "The maximum number of spans the queue of a given instance of an SDK span processor can hold" + note: | + Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor. + instrument: gauge + unit: "{span}" + attributes: + - ref: otel.sdk.component.type + - ref: otel.sdk.component.name + + - id: metric.otel.sdk.span.processor.spans_processed + type: metric + metric_name: otel.sdk.span.processor.spans_processed + stability: development + brief: "The number of spans for which the processing has finished, either successful or failed" + note: | + For successful processing, `error.type` must be empty. For failed processing, `error.type` must contain the failure cause. + For the SDK Simple and Batching Span Processor a span is considered to be processed already when it has been submitted to the exporter, not when the corresponding export call has finished. + instrument: counter + unit: "{span}" + attributes: + - ref: otel.sdk.component.type + - ref: otel.sdk.component.name + - ref: error.type + brief: > + A low-cardinality description of the failure reason. SDK Batching Span Processors MUST use `queue_full` for spans dropped due to a full queue. + examples: ["queue_full"] + + - id: metric.otel.sdk.span.exporter.spans_inflight + type: metric + metric_name: otel.sdk.span.exporter.spans_inflight + stability: development + brief: "The number of spans which were passed to the exporter, but that have not been exported yet (neither successful, nor failed)" + note: | + For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. + instrument: updowncounter + unit: "{span}" + attributes: + - ref: otel.sdk.component.type + - ref: otel.sdk.component.name + + - id: metric.otel.sdk.span.exporter.spans_exported + type: metric + metric_name: otel.sdk.span.exporter.spans_exported + stability: development + brief: "The number of spans for which the export has finished, either successful or failed" + note: | + For successful exports, `error.type` must be empty. For failed exports, `error.type` must contain the failure cause. + For exporters with partial success semantics (e.g. OTLP with `rejected_spans`), rejected spans must count as failed and only non-rejected spans count as success. + If no rejection reason is available, `rejected` SHOULD be used as value for `error.type`. + instrument: counter + unit: "{span}" + attributes: + - ref: otel.sdk.component.type + - ref: otel.sdk.component.name + - ref: error.type + examples: ["rejected"] diff --git a/model/otel/registry.yaml b/model/otel/registry.yaml index 01b1a19a8c..5e9c6887b0 100644 --- a/model/otel/registry.yaml +++ b/model/otel/registry.yaml @@ -22,6 +22,10 @@ groups: brief: "Description of the Status if it has a value, otherwise not set." examples: ['resource not found'] stability: stable + - id: otel.span.is_sampled + type: boolean + brief: "The sampled trace flag of the span" + stability: development - id: registry.otel.scope type: attribute_group display_name: OTel Scope Attributes @@ -37,3 +41,63 @@ groups: brief: The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). examples: ['1.0.0'] stability: stable + - id: registry.otel.sdk + type: attribute_group + display_name: OTel SDK Telemetry Attributes + brief: Attributes used for OpenTelemetry SDK self-monitoring + attributes: + - id: otel.sdk.component.type + type: + members: + - id: batching_span_processor + value: "batching_span_processor" + brief: > + The builtin SDK Batching Span Processor + stability: development + - id: simple_span_processor + value: "simple_span_processor" + brief: > + The builtin SDK Simple Span Processor + stability: development + - id: otlp_grpc_span_exporter + value: "otlp_grpc_span_exporter" + brief: > + OTLP span exporter over gRPC with protobuf serialization + stability: development + - id: otlp_http_span_exporter + value: "otlp_http_span_exporter" + brief: > + OTLP span exporter over HTTP with protobuf serialization + stability: development + - id: otlp_http_json_span_exporter + value: "otlp_http_json_span_exporter" + brief: > + OTLP span exporter over HTTP with JSON serialization + stability: development + stability: development + brief: > + A name identifying the type of the OpenTelemetry SDK component. + note: | + If none of the standardized values apply, implementations SHOULD use the language-defined name of the type. + E.g. for Java the fully qualified classname SHOULD be used in this case. + examples: ["batching_span_processor", "co.example.MySpanExporter"] + - id: otel.sdk.component.name + type: string + stability: development + brief: > + A name uniquely identifying the instance of the OpenTelemetry SDK component within its containing SDK instance. + note: | + Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts. + E.g. implementations MUST NOT use UUIDs as values for this attribute. + + Implementations MAY achieve these goals by following a `/` pattern, e.g. `batching_span_processor/0`. + Hereby `otel.sdk.component.type` refers to the corresponding attribute value of the component. + + The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed. + For example, `` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an + instance of the given component type is started. + + With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0` + as `otel.sdk.component.name`, the second one `batching_span_processor/1` and so on. + These values will therefore be reused in the case of an application restart. + examples: ["otlp_grpc_span_exporter/0", "custom-name"]