Semantic Conventions for OpenTelemetry SDK metrics
Status: Development
This document describes metrics emitted by the OpenTelemetry SDK components themselves about their internal state.
Span Metrics
Metric: otel.sdk.span.live.count
This metric is recommended.
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
|---|---|---|---|---|
otel.sdk.span.live.count | UpDownCounter | {span} | The number of created spans for which the end operation has not been called yet [1] |  |
[1]: For spans with recording=true: Implementations MUST record both otel.sdk.span.live.count and otel.sdk.span.ended.count.
For spans with recording=false: If implementations decide to record this metric, they MUST also record otel.sdk.span.ended.count.
| Attribute | Type | Description | Examples | Requirement Level | Stability |
|---|---|---|---|---|---|
otel.span.sampling_result | string | The result value of the sampler for this span | DROP; RECORD_ONLY; RECORD_AND_SAMPLE | Recommended | |
otel.span.sampling_result has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
|---|---|---|
DROP | The span is not sampled and not recording | |
RECORD_AND_SAMPLE | The span is sampled and recording | |
RECORD_ONLY | The span is not sampled, but recording | |
Metric: otel.sdk.span.ended.count
This metric is recommended.
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
|---|---|---|---|---|
otel.sdk.span.ended.count | Counter | {span} | The number of created spans for which the end operation was called [1] | |
[1]: For spans with recording=true: Implementations MUST record both otel.sdk.span.live.count and otel.sdk.span.ended.count.
For spans with recording=false: If implementations decide to record this metric, they MUST also record otel.sdk.span.live.count.
| Attribute | Type | Description | Examples | Requirement Level | Stability |
|---|---|---|---|---|---|
otel.span.sampling_result | string | The result value of the sampler for this span | DROP; RECORD_ONLY; RECORD_AND_SAMPLE | Recommended | |
otel.span.sampling_result has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
|---|---|---|
DROP | The span is not sampled and not recording | |
RECORD_AND_SAMPLE | The span is sampled and recording | |
RECORD_ONLY | The span is not sampled, but recording | |
Metric: otel.sdk.processor.span.queue.size
This metric is recommended.
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
|---|---|---|---|---|
otel.sdk.processor.span.queue.size | UpDownCounter | {span} | The number of spans in the queue of a given instance of an SDK span processor [1] | |
[1]: Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor.
| Attribute | Type | Description | Examples | Requirement Level | Stability |
|---|---|---|---|---|---|
otel.component.name | string | A name uniquely identifying the instance of the OpenTelemetry component within its containing SDK instance. [1] | otlp_grpc_span_exporter/0; custom-name | Recommended | |
otel.component.type | string | A name identifying the type of the OpenTelemetry component. [2] | batching_span_processor; com.example.MySpanExporter | Recommended | |
[1] otel.component.name: Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts.
E.g. implementations MUST NOT use UUIDs as values for this attribute.
Implementations MAY achieve these goals by following a <otel.component.type>/<instance-counter> pattern, e.g. batching_span_processor/0.
Hereby otel.component.type refers to the corresponding attribute value of the component.
The value of instance-counter MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed.
For example, <instance-counter> 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.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.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.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 | |
otlp_grpc_span_exporter | OTLP span exporter over gRPC with protobuf serialization | |
otlp_http_json_span_exporter | OTLP span exporter over HTTP with JSON serialization | |
otlp_http_span_exporter | OTLP span exporter over HTTP with protobuf serialization | |
simple_span_processor | The builtin SDK Simple Span Processor | |
Metric: otel.sdk.processor.span.queue.capacity
This metric is recommended.
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
|---|---|---|---|---|
otel.sdk.processor.span.queue.capacity | UpDownCounter | {span} | The maximum number of spans the queue of a given instance of an SDK span processor can hold [1] | |
[1]: Only applies to span processors which use a queue, e.g. the SDK Batching Span Processor.
| Attribute | Type | Description | Examples | Requirement Level | Stability |
|---|---|---|---|---|---|
otel.component.name | string | A name uniquely identifying the instance of the OpenTelemetry component within its containing SDK instance. [1] | otlp_grpc_span_exporter/0; custom-name | Recommended | |
otel.component.type | string | A name identifying the type of the OpenTelemetry component. [2] | batching_span_processor; com.example.MySpanExporter | Recommended | |
[1] otel.component.name: Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts.
E.g. implementations MUST NOT use UUIDs as values for this attribute.
Implementations MAY achieve these goals by following a <otel.component.type>/<instance-counter> pattern, e.g. batching_span_processor/0.
Hereby otel.component.type refers to the corresponding attribute value of the component.
The value of instance-counter MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed.
For example, <instance-counter> 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.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.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.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 | |
otlp_grpc_span_exporter | OTLP span exporter over gRPC with protobuf serialization | |
otlp_http_json_span_exporter | OTLP span exporter over HTTP with JSON serialization | |
otlp_http_span_exporter | OTLP span exporter over HTTP with protobuf serialization | |
simple_span_processor | The builtin SDK Simple Span Processor | |
Metric: otel.sdk.processor.span.processed.count
This metric is recommended.
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
|---|---|---|---|---|
otel.sdk.processor.span.processed.count | Counter | {span} | The number of spans for which the processing has finished, either successful or failed [1] | |
[1]: For successful processing, error.type MUST NOT be set. 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 | Stability |
|---|---|---|---|---|---|
error.type | 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 |  |
otel.component.name | string | A name uniquely identifying the instance of the OpenTelemetry component within its containing SDK instance. [2] | otlp_grpc_span_exporter/0; custom-name | Recommended | |
otel.component.type | string | A name identifying the type of the OpenTelemetry component. [3] | batching_span_processor; com.example.MySpanExporter | Recommended | |
[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.typeto capture all errors, regardless of whether they are defined within the domain-specific set or not.
[2] otel.component.name: Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts.
E.g. implementations MUST NOT use UUIDs as values for this attribute.
Implementations MAY achieve these goals by following a <otel.component.type>/<instance-counter> pattern, e.g. batching_span_processor/0.
Hereby otel.component.type refers to the corresponding attribute value of the component.
The value of instance-counter MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed.
For example, <instance-counter> 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.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.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. | |
otel.component.type has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
|---|---|---|
batching_span_processor | The builtin SDK Batching Span Processor | |
otlp_grpc_span_exporter | OTLP span exporter over gRPC with protobuf serialization | |
otlp_http_json_span_exporter | OTLP span exporter over HTTP with JSON serialization | |
otlp_http_span_exporter | OTLP span exporter over HTTP with protobuf serialization | |
simple_span_processor | The builtin SDK Simple Span Processor | |
Metric: otel.sdk.exporter.span.inflight.count
This metric is recommended.
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
|---|---|---|---|---|
otel.sdk.exporter.span.inflight.count | UpDownCounter | {span} | The number of spans which were passed to the exporter, but that have not been exported yet (neither successful, nor failed) [1] | |
[1]: For successful exports, error.type MUST NOT be set. For failed exports, error.type must contain the failure cause.
| Attribute | Type | Description | Examples | Requirement Level | Stability |
|---|---|---|---|---|---|
otel.component.name | string | A name uniquely identifying the instance of the OpenTelemetry component within its containing SDK instance. [1] | otlp_grpc_span_exporter/0; custom-name | Recommended | |
otel.component.type | string | A name identifying the type of the OpenTelemetry component. [2] | batching_span_processor; com.example.MySpanExporter | Recommended | |
server.address | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | example.com; 10.1.2.80; /tmp/my.sock | Recommended when applicable | |
server.port | int | Server port number. [4] | 80; 8080; 443 | Recommended when applicable | |
[1] otel.component.name: Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts.
E.g. implementations MUST NOT use UUIDs as values for this attribute.
Implementations MAY achieve these goals by following a <otel.component.type>/<instance-counter> pattern, e.g. batching_span_processor/0.
Hereby otel.component.type refers to the corresponding attribute value of the component.
The value of instance-counter MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed.
For example, <instance-counter> 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.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.component.type: If none of the standardized values apply, implementations SHOULD use the language-defined name of the type.
E.g. for Java the fully qualified classname SHOULD be used in this case.
[3] server.address: When observed from the client side, and when communicating through an intermediary, server.address SHOULD represent the server address behind any intermediaries, for example proxies, if it’s available.
[4] server.port: When observed from the client side, and when communicating through an intermediary, server.port SHOULD represent the server port behind any intermediaries, for example proxies, if it’s available.
otel.component.type has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
|---|---|---|
batching_span_processor | The builtin SDK Batching Span Processor | |
otlp_grpc_span_exporter | OTLP span exporter over gRPC with protobuf serialization | |
otlp_http_json_span_exporter | OTLP span exporter over HTTP with JSON serialization | |
otlp_http_span_exporter | OTLP span exporter over HTTP with protobuf serialization | |
simple_span_processor | The builtin SDK Simple Span Processor | |
Metric: otel.sdk.exporter.span.exported.count
This metric is recommended.
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
|---|---|---|---|---|
otel.sdk.exporter.span.exported.count | Counter | {span} | The number of spans for which the export has finished, either successful or failed [1] | |
[1]: For successful exports, error.type MUST NOT be set. 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 | Stability |
|---|---|---|---|---|---|
error.type | string | Describes a class of error the operation ended with. [1] | rejected; timeout; 500; java.net.UnknownHostException | Recommended | |
otel.component.name | string | A name uniquely identifying the instance of the OpenTelemetry component within its containing SDK instance. [2] | otlp_grpc_span_exporter/0; custom-name | Recommended | |
otel.component.type | string | A name identifying the type of the OpenTelemetry component. [3] | batching_span_processor; com.example.MySpanExporter | Recommended | |
server.address | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [4] | example.com; 10.1.2.80; /tmp/my.sock | Recommended when applicable | |
server.port | int | Server port number. [5] | 80; 8080; 443 | Recommended when applicable | |
[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.typeto capture all errors, regardless of whether they are defined within the domain-specific set or not.
[2] otel.component.name: Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts.
E.g. implementations MUST NOT use UUIDs as values for this attribute.
Implementations MAY achieve these goals by following a <otel.component.type>/<instance-counter> pattern, e.g. batching_span_processor/0.
Hereby otel.component.type refers to the corresponding attribute value of the component.
The value of instance-counter MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed.
For example, <instance-counter> 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.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.component.type: If none of the standardized values apply, implementations SHOULD use the language-defined name of the type.
E.g. for Java the fully qualified classname SHOULD be used in this case.
[4] server.address: When observed from the client side, and when communicating through an intermediary, server.address SHOULD represent the server address behind any intermediaries, for example proxies, if it’s available.
[5] server.port: When observed from the client side, and when communicating through an intermediary, server.port SHOULD represent the server port behind any intermediaries, for example proxies, if it’s available.
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. | |
otel.component.type has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
|---|---|---|
batching_span_processor | The builtin SDK Batching Span Processor | |
otlp_grpc_span_exporter | OTLP span exporter over gRPC with protobuf serialization | |
otlp_http_json_span_exporter | OTLP span exporter over HTTP with JSON serialization | |
otlp_http_span_exporter | OTLP span exporter over HTTP with protobuf serialization | |
simple_span_processor | The builtin SDK Simple Span Processor | |
Feedback
Was this page helpful?
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!