From 89f9bf3b3141626229ac39c9437e1832b38f104f Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Tue, 3 Oct 2023 12:13:38 -0400 Subject: [PATCH] Remove local stubs of semantic conventions. (#3711) --- .github/CODEOWNERS | 11 +- spec-compliance-matrix.md | 2 +- specification/common/attribute-naming.md | 14 +- .../common/attribute-requirement-level.md | 6 +- specification/compatibility/opencensus.md | 2 +- specification/compatibility/opentracing.md | 4 +- .../prometheus_and_openmetrics.md | 2 +- .../sdk-environment-variables.md | 4 +- specification/glossary.md | 2 +- specification/logs/README.md | 1 - specification/logs/data-model-appendix.md | 2 +- specification/logs/data-model.md | 7 +- specification/logs/event-api.md | 4 +- .../logs/semantic_conventions/README.md | 21 - .../logs/semantic_conventions/events.md | 50 -- .../logs/semantic_conventions/exceptions.md | 55 -- .../semantic_conventions/feature-flags.md | 58 -- .../logs/semantic_conventions/general.md | 32 - .../logs/semantic_conventions/media.md | 50 -- specification/metrics/README.md | 1 - specification/metrics/data-model.md | 2 +- .../metrics/semantic_conventions/README.md | 230 ------- .../semantic_conventions/database-metrics.md | 66 -- .../semantic_conventions/faas-metrics.md | 88 --- .../semantic_conventions/hardware-metrics.md | 394 ------------ .../semantic_conventions/http-metrics.md | 355 ----------- .../instrumentation/README.md | 6 - .../instrumentation/kafka.md | 89 --- .../semantic_conventions/process-metrics.md | 54 -- .../semantic_conventions/rpc-metrics.md | 227 ------- .../runtime-environment-metrics.md | 404 ------------ .../semantic_conventions/system-metrics.md | 194 ------ specification/performance-benchmark.md | 2 +- specification/protocol/exporter.md | 2 +- specification/resource/sdk.md | 4 +- .../resource/semantic_conventions/README.md | 231 ------- .../resource/semantic_conventions/browser.md | 35 -- .../resource/semantic_conventions/cloud.md | 90 --- .../cloud_provider/aws/README.md | 27 - .../cloud_provider/aws/ecs.md | 30 - .../cloud_provider/aws/eks.md | 18 - .../cloud_provider/aws/logs.md | 27 - .../cloud_provider/gcp/README.md | 15 - .../cloud_provider/gcp/cloud_run.md | 19 - .../cloud_provider/heroku.md | 35 -- .../semantic_conventions/container.md | 22 - .../deployment_environment.md | 18 - .../resource/semantic_conventions/device.md | 29 - .../resource/semantic_conventions/faas.md | 86 --- .../resource/semantic_conventions/host.md | 63 -- .../resource/semantic_conventions/k8s.md | 216 ------- .../resource/semantic_conventions/os.md | 39 -- .../resource/semantic_conventions/process.md | 226 ------- .../semantic_conventions/webengine.md | 29 - specification/trace/api.md | 4 +- specification/trace/exceptions.md | 2 +- specification/trace/sdk_exporters/jaeger.md | 2 +- specification/trace/sdk_exporters/zipkin.md | 12 +- .../trace/semantic_conventions/README.md | 50 -- .../trace/semantic_conventions/cloudevents.md | 209 ------- .../semantic_conventions/compatibility.md | 41 -- .../trace/semantic_conventions/database.md | 369 ----------- .../trace/semantic_conventions/exceptions.md | 112 ---- .../trace/semantic_conventions/faas.md | 262 -------- .../semantic_conventions/feature-flags.md | 62 -- .../trace/semantic_conventions/http.md | 461 -------------- .../instrumentation/aws-lambda.md | 254 -------- .../instrumentation/aws-sdk.md | 257 -------- .../instrumentation/graphql.md | 34 - .../trace/semantic_conventions/messaging.md | 581 ------------------ .../trace/semantic_conventions/rpc.md | 355 ----------- .../semantic_conventions/span-general.md | 385 ------------ supplementary-guidelines/compatibility/aws.md | 2 +- 73 files changed, 42 insertions(+), 7112 deletions(-) delete mode 100644 specification/logs/semantic_conventions/README.md delete mode 100644 specification/logs/semantic_conventions/events.md delete mode 100644 specification/logs/semantic_conventions/exceptions.md delete mode 100644 specification/logs/semantic_conventions/feature-flags.md delete mode 100644 specification/logs/semantic_conventions/general.md delete mode 100644 specification/logs/semantic_conventions/media.md delete mode 100644 specification/metrics/semantic_conventions/README.md delete mode 100644 specification/metrics/semantic_conventions/database-metrics.md delete mode 100644 specification/metrics/semantic_conventions/faas-metrics.md delete mode 100644 specification/metrics/semantic_conventions/hardware-metrics.md delete mode 100644 specification/metrics/semantic_conventions/http-metrics.md delete mode 100644 specification/metrics/semantic_conventions/instrumentation/README.md delete mode 100644 specification/metrics/semantic_conventions/instrumentation/kafka.md delete mode 100644 specification/metrics/semantic_conventions/process-metrics.md delete mode 100644 specification/metrics/semantic_conventions/rpc-metrics.md delete mode 100644 specification/metrics/semantic_conventions/runtime-environment-metrics.md delete mode 100644 specification/metrics/semantic_conventions/system-metrics.md delete mode 100644 specification/resource/semantic_conventions/README.md delete mode 100644 specification/resource/semantic_conventions/browser.md delete mode 100644 specification/resource/semantic_conventions/cloud.md delete mode 100644 specification/resource/semantic_conventions/cloud_provider/aws/README.md delete mode 100644 specification/resource/semantic_conventions/cloud_provider/aws/ecs.md delete mode 100644 specification/resource/semantic_conventions/cloud_provider/aws/eks.md delete mode 100644 specification/resource/semantic_conventions/cloud_provider/aws/logs.md delete mode 100644 specification/resource/semantic_conventions/cloud_provider/gcp/README.md delete mode 100644 specification/resource/semantic_conventions/cloud_provider/gcp/cloud_run.md delete mode 100644 specification/resource/semantic_conventions/cloud_provider/heroku.md delete mode 100644 specification/resource/semantic_conventions/container.md delete mode 100644 specification/resource/semantic_conventions/deployment_environment.md delete mode 100644 specification/resource/semantic_conventions/device.md delete mode 100644 specification/resource/semantic_conventions/faas.md delete mode 100644 specification/resource/semantic_conventions/host.md delete mode 100644 specification/resource/semantic_conventions/k8s.md delete mode 100644 specification/resource/semantic_conventions/os.md delete mode 100644 specification/resource/semantic_conventions/process.md delete mode 100644 specification/resource/semantic_conventions/webengine.md delete mode 100644 specification/trace/semantic_conventions/README.md delete mode 100644 specification/trace/semantic_conventions/cloudevents.md delete mode 100644 specification/trace/semantic_conventions/compatibility.md delete mode 100644 specification/trace/semantic_conventions/database.md delete mode 100644 specification/trace/semantic_conventions/exceptions.md delete mode 100644 specification/trace/semantic_conventions/faas.md delete mode 100644 specification/trace/semantic_conventions/feature-flags.md delete mode 100644 specification/trace/semantic_conventions/http.md delete mode 100644 specification/trace/semantic_conventions/instrumentation/aws-lambda.md delete mode 100644 specification/trace/semantic_conventions/instrumentation/aws-sdk.md delete mode 100644 specification/trace/semantic_conventions/instrumentation/graphql.md delete mode 100644 specification/trace/semantic_conventions/messaging.md delete mode 100644 specification/trace/semantic_conventions/rpc.md delete mode 100644 specification/trace/semantic_conventions/span-general.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index d1bfc690008..a03601d88a4 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -27,9 +27,8 @@ specification/metrics/ @open-telemetry/technical-committee @open-telemetry/spec experimental/logs/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-logs-approvers specification/logs/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-logs-approvers -# Semantic Conventions owners (global + trace/metrics/logs/semconv) -semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-semconv-approvers -specification/trace/semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-trace-approvers @open-telemetry/specs-semconv-approvers -specification/metrics/semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-metrics-approvers @open-telemetry/specs-semconv-approvers -specification/logs/semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-logs-approvers @open-telemetry/specs-semconv-approvers -specification/resource/semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-semconv-approvers +# Semantic Conventions owners (global) +specification/semantic-conventions.md @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-semconv-approvers +specification/telemetry-stability.md @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-semconv-approvers +# Note: Common is about naming conventions, relevant to semconv +specification/common/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-semconv-approvers diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index d1bd1c0d148..2dca0bfe514 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -241,7 +241,7 @@ Disclaimer: this list of features is still a work in progress, please refer to t | Create empty | | + | + | + | + | + | + | + | + | + | + | + | | [Merge (v2)](specification/resource/sdk.md#merge) | | + | + | | + | + | + | + | + | + | + | | | Retrieve attributes | | + | + | + | + | + | + | + | + | + | + | + | -| [Default value](specification/resource/semantic_conventions/README.md#semantic-attributes-with-sdk-provided-default-value) for service.name | | + | + | | + | + | + | + | | + | + | | +| [Default value](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/resource#semantic-attributes-with-dedicated-environment-variable) for service.name | | + | + | | + | + | + | + | | + | + | | | [Resource detector](specification/resource/sdk.md#detecting-resource-information-from-the-environment) interface/mechanism | | + | + | + | + | + | + | + | + | + | + | + | | [Resource detectors populate Schema URL](specification/resource/sdk.md#detecting-resource-information-from-the-environment) | | + | + | | | | - | + | | | - | | diff --git a/specification/common/attribute-naming.md b/specification/common/attribute-naming.md index badb9acbd07..548703db6f2 100644 --- a/specification/common/attribute-naming.md +++ b/specification/common/attribute-naming.md @@ -65,7 +65,7 @@ Names SHOULD follow these rules: values: the executable name and command arguments. - When an attribute represents a measurement, - [Metric Name Pluralization Guidelines](../metrics/semantic_conventions/README.md#pluralization) + [Metric Name Pluralization Guidelines](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/metrics.md#pluralization) SHOULD be followed for the attribute name. ## Name Reuse Prohibition @@ -83,11 +83,7 @@ denote old attribute names in rename operations). of a namespace. - When coming up with a new semantic convention make sure to check existing - namespaces for - [Resources](../resource/semantic_conventions/README.md), - [Spans](../trace/semantic_conventions/README.md), - and - [Metrics](../metrics/semantic_conventions/README.md) + namespaces ([Semantic Conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md)) to see if the new name fits. - When a new namespace is necessary consider whether it should be a top-level @@ -111,11 +107,7 @@ denote old attribute names in rename operations). ## Recommendations for Application Developers As an application developer when you need to record an attribute first consult -existing semantic conventions for -[Resources](../resource/semantic_conventions/README.md), -[Spans](../trace/semantic_conventions/README.md), -and -[Metrics](../metrics/semantic_conventions/README.md). +existing [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md). If an appropriate name does not exists you will need to come up with a new name. To do that consider a few options: diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index 52f8e34f269..1866c413cab 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -34,7 +34,8 @@ For example, Metric attributes that may have high cardinality can only be define A semantic convention that refers to an attribute from another semantic convention MAY modify the requirement level within its own scope. Otherwise, requirement level from the referred semantic convention applies. -For example, [Database semantic convention](../trace/semantic_conventions/database.md) references `network.transport` attribute defined in [General attributes](../trace/semantic_conventions/span-general.md) with `Conditionally Required` level on it. + +For example, [Database semantic convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/README.md) references `network.transport` attribute defined in [General attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/README.md) with `Conditionally Required` level on it. ## Required @@ -50,7 +51,8 @@ All instrumentations MUST populate the attribute when the given condition is sat When a `Conditionally Required` attribute's condition is not satisfied, and there is no requirement to populate the attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Opt-In` requirement level on the attribute. -For example, `server.address` is `Conditionally Required` by the [Database convention](../trace/semantic_conventions/database.md) when available. When `server.socket.address` is available instead, instrumentation can do a DNS lookup, cache and populate `server.address`, but only if the user explicitly enables the instrumentation to do so, considering the performance issues that DNS lookups introduce. + +For example, `server.address` is `Conditionally Required` by the [Database convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/README.md) when available. When `server.socket.address` is available instead, instrumentation can do a DNS lookup, cache and populate `server.address`, but only if the user explicitly enables the instrumentation to do so, considering the performance issues that DNS lookups introduce. ## Recommended diff --git a/specification/compatibility/opencensus.md b/specification/compatibility/opencensus.md index f1e55bac3ce..390935d427b 100644 --- a/specification/compatibility/opencensus.md +++ b/specification/compatibility/opencensus.md @@ -17,7 +17,7 @@ instrumented codebases. Migrating from OpenCensus to OpenTelemetry may require breaking changes to the telemetry produced because of: -* Different or new semantic conventions for names and attributes (e.g. [`grpc.io/server/server_latency`](https://github.com/census-instrumentation/opencensus-specs/blob/master/stats/gRPC.md#server) vs [`rpc.server.duration`](/specification/metrics/semantic_conventions/rpc-metrics.md#rpc-server)) +* Different or new semantic conventions for names and attributes (e.g. [`grpc.io/server/server_latency`](https://github.com/census-instrumentation/opencensus-specs/blob/master/stats/gRPC.md#server) vs [`rpc.server.duration`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/rpc/rpc-metrics.md#metric-rpcserverduration)) * Data model differences (e.g. OpenCensus supports [SumOfSquaredDeviations](https://github.com/census-instrumentation/opencensus-proto/blob/v0.3.0/src/opencensus/proto/metrics/v1/metrics.proto#L195), OTLP does not) * Instrumentation API feature differences (e.g. OpenCensus supports [context-based attributes](https://github.com/census-instrumentation/opencensus-specs/blob/master/stats/Record.md#recording-stats)), OTel does not) * Differences between equivalent OC and OTel exporters (e.g. the OpenTelemetry Prometheus exporter [adds type and unit suffixes](prometheus_and_openmetrics.md#metric-metadata-1); OpenCensus [does not](https://github.com/census-ecosystem/opencensus-go-exporter-prometheus/blob/v0.4.1/prometheus.go#L227)) diff --git a/specification/compatibility/opentracing.md b/specification/compatibility/opentracing.md index 1481b0af2b7..b75547b8577 100644 --- a/specification/compatibility/opentracing.md +++ b/specification/compatibility/opentracing.md @@ -136,7 +136,7 @@ with **Child Of** type in the entire list is used as parent, else the the first `SpanContext` is used as parent. All values in the list MUST be added as [Link](../trace/api.md)s with the reference type value as a `Link` attribute, i.e. -[opentracing.ref_type](../trace/semantic_conventions/compatibility.md#opentracing) +[opentracing.ref_type](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/trace-compatibility.md#opentracing) set to `follows_from` or `child_of`. If a list of `Span` references is specified, the union of their @@ -396,7 +396,7 @@ the pair set, or else fallback to use the `log` literal string. If pair set contains an `event=error` entry, the values MUST be [mapped](https://github.com/opentracing/specification/blob/master/semantic_conventions.md#log-fields-table) to an `Event` with the conventions outlined in the -[Exception semantic conventions](../trace/semantic_conventions/exceptions.md) document: +[Exception semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/exceptions/exceptions-spans.md) document: - If an entry with `error.object` key exists and the value is a language-specific error object, a call to `RecordException(e)` is performed along the rest of diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md index 4e5304ad6dc..ecb74fc73dd 100644 --- a/specification/compatibility/prometheus_and_openmetrics.md +++ b/specification/compatibility/prometheus_and_openmetrics.md @@ -402,7 +402,7 @@ labels distinguish targets and are expected to be present on metrics exposed on a Prometheus pull exporter (a ["federated"](https://prometheus.io/docs/prometheus/latest/federation/) Prometheus endpoint) or pushed via Prometheus remote-write. In OTLP, the `service.name`, `service.namespace`, and `service.instance.id` triplet is -[required to be unique](../resource/semantic_conventions/README.md#service), +[required to be unique](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#service), which makes them good candidates to use to construct `job` and `instance`. In the collector Prometheus exporters, the `service.name` and `service.namespace` attributes MUST be combined as `/`, or diff --git a/specification/configuration/sdk-environment-variables.md b/specification/configuration/sdk-environment-variables.md index 25069ba56f9..3edd66f0513 100644 --- a/specification/configuration/sdk-environment-variables.md +++ b/specification/configuration/sdk-environment-variables.md @@ -77,8 +77,8 @@ For example, the value `12000` indicates 12000 milliseconds, i.e., 12 seconds. | Name | Description | Default | Notes | |--------------------------|---------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | OTEL_SDK_DISABLED | Disable the SDK for all signals | false | Boolean value. If "true", a no-op SDK implementation will be used for all telemetry signals. Any other value or absence of the variable will have no effect and the SDK will remain enabled. This setting has no effect on propagators configured through the OTEL_PROPAGATORS variable. | -| OTEL_RESOURCE_ATTRIBUTES | Key-value pairs to be used as resource attributes | See [Resource semantic conventions](../resource/semantic_conventions/README.md#semantic-attributes-with-sdk-provided-default-value) for details. | See [Resource SDK](../resource/sdk.md#specifying-resource-information-via-an-environment-variable) for more details. | -| OTEL_SERVICE_NAME | Sets the value of the [`service.name`](../resource/semantic_conventions/README.md#service) resource attribute | | If `service.name` is also provided in `OTEL_RESOURCE_ATTRIBUTES`, then `OTEL_SERVICE_NAME` takes precedence. | +| OTEL_RESOURCE_ATTRIBUTES | Key-value pairs to be used as resource attributes | See [Resource semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#semantic-attributes-with-dedicated-environment-variable) for details. | See [Resource SDK](../resource/sdk.md#specifying-resource-information-via-an-environment-variable) for more details. | +| OTEL_SERVICE_NAME | Sets the value of the [`service.name`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#service) resource attribute | | If `service.name` is also provided in `OTEL_RESOURCE_ATTRIBUTES`, then `OTEL_SERVICE_NAME` takes precedence. | | OTEL_LOG_LEVEL | Log level used by the SDK logger | "info" | | | OTEL_PROPAGATORS | Propagators to be used as a comma-separated list | "tracecontext,baggage" | Values MUST be deduplicated in order to register a `Propagator` only once. | | OTEL_TRACES_SAMPLER | Sampler to be used for traces | "parentbased_always_on" | See [Sampling](../trace/sdk.md#sampling) | diff --git a/specification/glossary.md b/specification/glossary.md index 8263a4658b3..1944b7387af 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -117,7 +117,7 @@ Synonym: *Auto-instrumentation*. Denotes the library that implements the *OpenTelemetry API*. See [Library Guidelines](library-guidelines.md#sdk-implementation) and -[Library resource semantic conventions](resource/semantic_conventions/README.md#telemetry-sdk). +[Library resource semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#telemetry-sdk). ### Constructors diff --git a/specification/logs/README.md b/specification/logs/README.md index e2afcfdd159..b0c3fb5acbe 100644 --- a/specification/logs/README.md +++ b/specification/logs/README.md @@ -444,5 +444,4 @@ standard output. * [Logs SDK](./sdk.md) * [Logs Data Model](./data-model.md) * [Event API](./event-api.md) -* [Semantic Conventions](./semantic_conventions/README.md) * [Trace Context in non-OTLP Log Formats](../compatibility/logging_trace_context.md) diff --git a/specification/logs/data-model-appendix.md b/specification/logs/data-model-appendix.md index 6dbf00e9611..b5808cf7706 100644 --- a/specification/logs/data-model-appendix.md +++ b/specification/logs/data-model-appendix.md @@ -794,7 +794,7 @@ All other fields | | \* Not yet formalized into ECS. \*\* A resource that doesn’t exist in the -[OpenTelemetry resource semantic convention](../resource/semantic_conventions/README.md). +[OpenTelemetry resource semantic convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md). This is a selection of the most relevant fields. See [for the full reference](https://www.elastic.co/guide/en/ecs/current/ecs-field-reference.html) diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index 2c57f4915d7..1122af21196 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -425,7 +425,7 @@ the record or about the infrastructure where the application runs. Data formats that represent this data model may be designed in a manner that allows the `Resource` field to be recorded only once per batch of log records that come from the same source. SHOULD follow OpenTelemetry -[semantic conventions for Resources](../resource/semantic_conventions/README.md). +[semantic conventions for Resources](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md). This field is optional. ### Field: `InstrumentationScope` @@ -450,8 +450,7 @@ Description: Additional information about the specific event occurrence. Unlike the `Resource` field, which is fixed for a particular source, `Attributes` can vary for each occurrence of the event coming from the same source. Can contain information about the request context (other than TraceId/SpanId). SHOULD follow -OpenTelemetry [semantic conventions for Log Attributes](./semantic_conventions/README.md) or -[semantic conventions for Span Attributes](../trace/semantic_conventions/README.md). +OpenTelemetry [semantic conventions for attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md). This field is optional. #### Errors and Exceptions @@ -460,7 +459,7 @@ Additional information about errors and/or exceptions that are associated with a log record MAY be included in the structured data in the `Attributes` section of the record. If included, they MUST follow the OpenTelemetry -[semantic conventions for exception-related attributes](./semantic_conventions/exceptions.md#attributes). +[semantic conventions for exception-related attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/exceptions/exceptions-logs.md). ## Example Log Records diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 78facadb2a3..6c59ac226b3 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -34,7 +34,7 @@ LogRecords and Events: Events are LogRecords which have a `name` and `domain`. Within a particular `domain`, the `name` uniquely defines a particular class or type of event. Events with the same `domain` / `name` follow the same schema which assists in analysis in observability platforms. Events are described in -more detail in the [semantic conventions](./semantic_conventions/events.md). +more detail in the [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). While the logging space has a diverse legacy with many existing logging libraries in different languages, there is not ubiquitous alignment with @@ -43,7 +43,7 @@ OpenTelemetry events is clunky or error-prone. The Event API offers convenience methods for [emitting LogRecords](./bridge-api.md#emit-a-logrecord) that conform -to the [semantic conventions for Events](./semantic_conventions/events.md). +to the [semantic conventions for Events](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). Unlike the [Logs Bridge API](./bridge-api.md), application developers and instrumentation authors are encouraged to call this API directly. diff --git a/specification/logs/semantic_conventions/README.md b/specification/logs/semantic_conventions/README.md deleted file mode 100644 index c0fba6e39c6..00000000000 --- a/specification/logs/semantic_conventions/README.md +++ /dev/null @@ -1,21 +0,0 @@ -# Log Attribute Semantic Conventions - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -The following semantic conventions for logs are defined: - -* [General](general.md): General semantic attributes that may be used in describing Log Records. -* [Log Media](media.md): Semantic attributes that may be used in describing the source of a log. - -The following semantic conventions for events are defined: - -* [Events](events.md): Semantic attributes that must be used to represent Events using log data model. - -Apart from semantic conventions for logs, [traces](../../trace/semantic_conventions/README.md), and [metrics](../../metrics/semantic_conventions/README.md), -OpenTelemetry also defines the concept of overarching [Resources](../../resource/sdk.md) with their own -[Resource Semantic Conventions](../../resource/semantic_conventions/README.md). diff --git a/specification/logs/semantic_conventions/events.md b/specification/logs/semantic_conventions/events.md deleted file mode 100644 index a59f29936d0..00000000000 --- a/specification/logs/semantic_conventions/events.md +++ /dev/null @@ -1,50 +0,0 @@ -# Semantic Convention for event attributes - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -This document describes the attributes of standalone Events that are represented -in the data model by `LogRecord`s. Events are recorded as LogRecords that are shaped -in a special way: Event LogRecords have the attributes `event.domain` -and `event.name` (and possibly other LogRecord attributes). - -The `event.domain` attribute is used to logically separate events from different -systems. For example, to record Events from browser apps, mobile apps and -Kubernetes, we could use `browser`, `device` and `k8s` as the domain for their -Events. This provides a clean separation of semantics for events in each of the -domains. - -Within a particular domain, the `event.name` attribute identifies the event. -Events with same domain and name are structurally similar to one another. For -example, some domains could have well-defined schema for their events based on -event names. - -When recording events from an existing system as OpenTelemetry Events, it is -possible that the existing system does not have the equivalent of a name or -requires multiple fields to identify the structure of the events. In such cases, -OpenTelemetry recommends using a combination of one or more fields as the name -such that the name identifies the event structurally. It is also recommended that -the event names have low-cardinality, so care must be taken to use fields -that identify the class of Events but not the instance of the Event. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `event.name` | string | The name identifies the event. | `click`; `exception` | Required | -| `event.domain` | string | The domain identifies the business context for the events. [1] | `browser` | Required | - -**[1]:** Events across different domains may have same `event.name`, yet be -unrelated events. - -`event.domain` 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 | -|---|---| -| `browser` | Events from browser apps | -| `device` | Events from mobile apps | -| `k8s` | Events from Kubernetes | - diff --git a/specification/logs/semantic_conventions/exceptions.md b/specification/logs/semantic_conventions/exceptions.md deleted file mode 100644 index 50c0a916ef6..00000000000 --- a/specification/logs/semantic_conventions/exceptions.md +++ /dev/null @@ -1,55 +0,0 @@ -# Semantic Conventions for Exceptions - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -This document defines semantic conventions for recording exceptions on -[logs](../bridge-api.md#emit-a-logrecord) and [events](../event-api.md#emit-event) -emitted through the [Logger API](../bridge-api.md#logger). - - - -- [Recording an Exception](#recording-an-exception) -- [Attributes](#attributes) - * [Stacktrace Representation](#stacktrace-representation) - - - -## Recording an Exception - -Exceptions SHOULD be recorded as attributes on the -[LogRecord](../data-model.md#log-and-event-record-definition) passed to the [Logger](../bridge-api.md#logger) emit -operations. Exceptions MAY be recorded on "logs" or "events" depending on the -context. - -To encapsulate proper handling of exceptions API authors MAY provide a -constructor, `RecordException` method/extension, or similar helper mechanism on -the `LogRecord` class/structure or wherever it makes the most sense depending on -the language runtime. - -## Attributes - -The table below indicates which attributes should be added to the -[LogRecord](../data-model.md#log-and-event-record-definition) and their types. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below | -| `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | Recommended | -| `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | See below | - -**Additional attribute requirements:** At least one of the following sets of attributes is required: - -* `exception.type` -* `exception.message` - - -### Stacktrace Representation - -Same as [Trace Semantic Conventions for Exceptions - Stacktrace -Representation](../../trace/semantic_conventions/exceptions.md#stacktrace-representation). diff --git a/specification/logs/semantic_conventions/feature-flags.md b/specification/logs/semantic_conventions/feature-flags.md deleted file mode 100644 index 8ea7c4a1523..00000000000 --- a/specification/logs/semantic_conventions/feature-flags.md +++ /dev/null @@ -1,58 +0,0 @@ -# Semantic Conventions for Feature Flag Evaluations - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -This document defines semantic conventions for recording feature flag evaluations as -a [log record](../data-model.md#log-and-event-record-definition) emitted through the -[Logger API](../bridge-api.md#emit-a-logrecord). -This is useful when a flag is evaluated outside of a transaction context -such as when the application loads or on a timer. -To record a flag evaluation as a part of a transaction context, -consider [recording it as a span event](../../trace/semantic_conventions/feature-flags.md). - -For more information about why it is useful to capture feature flag evaluations, -refer to the [motivation](../../trace/semantic_conventions/feature-flags.md#motivation) -section of the trace semantic convention for feature flag evaluations. - - - -- [Recording an Evaluation](#recording-an-evaluation) -- [Attributes](#attributes) - - - -## Recording an Evaluation - -Feature flag evaluations SHOULD be recorded as attributes on the -[LogRecord](../data-model.md#log-and-event-record-definition) passed to the [Logger](../bridge-api.md#logger) emit -operations. Evaluations MAY be recorded on "logs" or "events" depending on the -context. - -## Attributes - -The table below indicates which attributes should be added to the -[LogRecord](../data-model.md#log-and-event-record-definition) and their types. - - -The event name MUST be `feature_flag`. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`feature_flag.key`](../../trace/semantic_conventions/feature-flags.md) | string | The unique identifier of the feature flag. | `logo-color` | Required | -| [`feature_flag.provider_name`](../../trace/semantic_conventions/feature-flags.md) | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | Recommended | -| [`feature_flag.variant`](../../trace/semantic_conventions/feature-flags.md) | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | Recommended | - -**[1]:** A semantic identifier, commonly referred to as a variant, provides a means -for referring to a value without including the value itself. This can -provide additional context for understanding the meaning behind a value. -For example, the variant `red` maybe be used for the value `#c05543`. - -A stringified version of the value can be used in situations where a -semantic identifier is unavailable. String representation of the value -should be determined by the implementer. - diff --git a/specification/logs/semantic_conventions/general.md b/specification/logs/semantic_conventions/general.md deleted file mode 100644 index 0c125586087..00000000000 --- a/specification/logs/semantic_conventions/general.md +++ /dev/null @@ -1,32 +0,0 @@ -# General attributes - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -The attributes described in this section are rather generic. -They may be used in any Log Record they apply to. - - - - - -- [General log identification attributes](#general-log-identification-attributes) - - - -## General log identification attributes - -These attributes may be used for identifying a Log Record. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `log.record.uid` | string | A unique identifier for the Log Record. [1] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | Opt-In | - -**[1]:** If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values. -The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec), but other identifiers (e.g. UUID) may be used as needed. - diff --git a/specification/logs/semantic_conventions/media.md b/specification/logs/semantic_conventions/media.md deleted file mode 100644 index 031c77a702c..00000000000 --- a/specification/logs/semantic_conventions/media.md +++ /dev/null @@ -1,50 +0,0 @@ -# Semantic Conventions for Log Media - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -This document describes attributes for log media in OpenTelemetry. Log media are mechanisms by which logs are transmitted. Types of media include files, streams, network protocols, and os-specific logging services such as journald and Windows Event Log. - - - -
-Table of Contents - - - -- [Log Media](#log-media) - * [Log File](#log-file) - * [I/O Stream](#io-stream) - - - -
- -## Log Media - -**Note:** The OpenTelemetry specification defines a [Resource](../../resource/sdk.md#resource-sdk) as `an immutable representation of the entity producing telemetry`. -The following attributes do not describe entities that produce telemetry. Rather, they describe mechanisms of log transmission. -As such, these should be recorded as Log Record attributes when applicable. They should not be recorded as Resource attributes. - -### Log File - -**Description:** A file to which log was emitted. - -| Name | Notes and examples | -| ------------------------------- | ---------------------------------------------------------------------------------------- | -| `log.file.name` | The basename of the file. Example: `audit.log` | -| `log.file.path` | The full path to the file. Example: `/var/log/mysql/audit.log` | -| `log.file.name_resolved` | The basename of the file, with symlinks resolved. Example: `uuid.log` | -| `log.file.path_resolved` | The full path to the file, with symlinks resolved. Example: `/var/lib/docker/uuid.log` | - -### I/O Stream - -**Description:** The I/O stream to which the log was emitted. - -| Name | Notes and examples | -| ------------------------------- | ---------------------------------------------------------------------------------------- | -| `log.iostream` | The stream associated with the log. SHOULD be one of: `stdout`, `stderr` | diff --git a/specification/metrics/README.md b/specification/metrics/README.md index 5389370cc33..82b94af96d8 100644 --- a/specification/metrics/README.md +++ b/specification/metrics/README.md @@ -100,7 +100,6 @@ SDK](../overview.md#sdk) concept for more information. * [Metrics SDK](./sdk.md) * [Metrics Data Model and Protocol](./data-model.md) * [Metrics Requirement Levels](./metric-requirement-level.md) -* [Semantic Conventions](./semantic_conventions/README.md) ## References diff --git a/specification/metrics/data-model.md b/specification/metrics/data-model.md index 5acd97e60da..a7d15bfb9cf 100644 --- a/specification/metrics/data-model.md +++ b/specification/metrics/data-model.md @@ -1175,7 +1175,7 @@ When more than one process writes the same metric data stream, OTLP data points may appear to overlap. This condition typically results from misconfiguration, but can also result from running identical processes (indicative of operating system or SDK bugs, like missing -[process attributes](../resource/semantic_conventions/process.md)). When there +[process attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/process.md#process)). When there are overlapping points, receivers SHOULD eliminate points so that there are no overlaps. Which data to select in overlapping cases is not specified. diff --git a/specification/metrics/semantic_conventions/README.md b/specification/metrics/semantic_conventions/README.md deleted file mode 100644 index 1bd0f041437..00000000000 --- a/specification/metrics/semantic_conventions/README.md +++ /dev/null @@ -1,230 +0,0 @@ - - - -# Metrics Semantic Conventions - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Mixed](../../document-status.md) - - - -- [General Guidelines](#general-guidelines) - * [Name Reuse Prohibition](#name-reuse-prohibition) - * [Units](#units) - * [Pluralization](#pluralization) - + [Use `count` Instead of Pluralization](#use-count-instead-of-pluralization) -- [General Metric Semantic Conventions](#general-metric-semantic-conventions) - * [Instrument Naming](#instrument-naming) - * [Instrument Units](#instrument-units) - * [Instrument Types](#instrument-types) - * [Consistent UpDownCounter timeseries](#consistent-updowncounter-timeseries) - - - -The following semantic conventions surrounding metrics are defined: - -* [HTTP](http-metrics.md): For HTTP client and server metrics. -* [RPC](rpc-metrics.md): For RPC client and server metrics. -* [Database](database-metrics.md): For SQL and NoSQL client metrics. -* [System](system-metrics.md): For standard system metrics. -* [Process](process-metrics.md): For standard process metrics. -* [Runtime Environment](runtime-environment-metrics.md): For runtime environment metrics. -* [FaaS](faas-metrics.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) metrics. -* [Hardware](hardware-metrics.md): For hardware-related metrics. - -Apart from semantic conventions for metrics and -[traces](../../trace/semantic_conventions/README.md), OpenTelemetry also -defines the concept of overarching [Resources](../../resource/sdk.md) with -their own [Resource Semantic -Conventions](../../resource/semantic_conventions/README.md). - -## General Guidelines - -**Status**: [Experimental](../../document-status.md) - -Metric names and attributes exist within a single universe and a single -hierarchy. Metric names and attributes MUST be considered within the universe of -all existing metric names. When defining new metric names and attributes, -consider the prior art of existing standard metrics and metrics from -frameworks/libraries. - -Associated metrics SHOULD be nested together in a hierarchy based on their -usage. Define a top-level hierarchy for common metric categories: for OS -metrics, like CPU and network; for app runtimes, like GC internals. Libraries -and frameworks should nest their metrics into a hierarchy as well. This aids -in discovery and adhoc comparison. This allows a user to find similar metrics -given a certain metric. - -The hierarchical structure of metrics defines the namespacing. Supporting -OpenTelemetry artifacts define the metric structures and hierarchies for some -categories of metrics, and these can assist decisions when creating future -metrics. - -Common attributes SHOULD be consistently named. This aids in discoverability and -disambiguates similar attributes to metric names. - -["As a rule of thumb, **aggregations** over all the attributes of a given -metric **SHOULD** be -meaningful,"](https://prometheus.io/docs/practices/naming/#metric-names) as -Prometheus recommends. - -Semantic ambiguity SHOULD be avoided. Use prefixed metric names in cases -where similar metrics have significantly different implementations across the -breadth of all existing metrics. For example, every garbage collected runtime -has slightly different strategies and measures. Using a single set of metric -names for GC, not divided by the runtime, could create dissimilar comparisons -and confusion for end users. (For example, prefer `process.runtime.java.gc*` over -`process.runtime.gc.*`.) Measures of many operating system metrics are similarly -ambiguous. - -### Name Reuse Prohibition - -A new metric MUST NOT be added with the same name as a metric that existed in -the past but was renamed (with a corresponding schema file). - -When introducing a new metric name check all existing schema files to make sure -the name does not appear as a key of any "rename_metrics" section (keys denote -old metric names in rename operations). - -### Units - -Conventional metrics or metrics that have their units included in -OpenTelemetry metadata (e.g. `metric.WithUnit` in Go) SHOULD NOT include the -units in the metric name. Units may be included when it provides additional -meaning to the metric name. Metrics MUST, above all, be understandable and -usable. - -When building components that interoperate between OpenTelemetry and a system -using the OpenMetrics exposition format, use the -[OpenMetrics Guidelines](../../compatibility/prometheus_and_openmetrics.md). - -### Pluralization - -Metric names SHOULD NOT be pluralized, unless the value being recorded -represents discrete instances of a -[countable quantity](https://en.wikipedia.org/wiki/Count_noun). -Generally, the name SHOULD be pluralized only if the unit of the metric in -question is a non-unit (like `{fault}` or `{operation}`). - -Examples: - -* `system.filesystem.utilization`, `http.server.duration`, and `system.cpu.time` -should not be pluralized, even if many data points are recorded. -* `system.paging.faults`, `system.disk.operations`, and `system.network.packets` -should be pluralized, even if only a single data point is recorded. - -#### Use `count` Instead of Pluralization - -If the value being recorded represents the count of concepts signified -by the namespace then the metric should be named `count` (within its namespace). -The pluralization rule does not apply in this case. - -For example if we have a namespace `system.processes` which contains all metrics related -to the processes then to represent the count of the processes we can have a metric named -`system.processes.count`. The suffix `count` here indicates that it is the count of -`system.processes`. - -## General Metric Semantic Conventions - -**Status**: [Mixed](../../document-status.md) - -The following semantic conventions aim to keep naming consistent. They -provide guidelines for most of the cases in this specification and should be -followed for other instruments not explicitly defined in this document. - -### Instrument Naming - -**Status**: [Experimental](../../document-status.md) - -- **limit** - an instrument that measures the constant, known total amount of -something should be called `entity.limit`. For example, `system.memory.limit` -for the total amount of memory on a system. - -- **usage** - an instrument that measures an amount used out of a known total -(**limit**) amount should be called `entity.usage`. For example, -`system.memory.usage` with attribute `state = used | cached | free | ...` for the -amount of memory in a each state. Where appropriate, the sum of **usage** -over all attribute values SHOULD be equal to the **limit**. - - A measure of the amount consumed of an unlimited resource, or of a resource - whose limit is unknowable, is differentiated from **usage**. For example, the - maximum possible amount of virtual memory that a process may consume may - fluctuate over time and is not typically known. - -- **utilization** - an instrument that measures the *fraction* of **usage** -out of its **limit** should be called `entity.utilization`. For example, -`system.memory.utilization` for the fraction of memory in use. Utilization -values are in the range `[0, 1]`. - -- **time** - an instrument that measures passage of time should be called -`entity.time`. For example, `system.cpu.time` with attribute `state = idle | user -| system | ...`. **time** measurements are not necessarily wall time and can -be less than or greater than the real wall time between measurements. - - **time** instruments are a special case of **usage** metrics, where the - **limit** can usually be calculated as the sum of **time** over all attribute - values. **utilization** for time instruments can be derived automatically - using metric event timestamps. For example, `system.cpu.utilization` is - defined as the difference in `system.cpu.time` measurements divided by the - elapsed time and number of CPUs. - -- **io** - an instrument that measures bidirectional data flow should be -called `entity.io` and have attributes for direction. For example, -`system.network.io`. - -- Other instruments that do not fit the above descriptions may be named more -freely. For example, `system.paging.faults` and `system.network.packets`. -Units do not need to be specified in the names since they are included during -instrument creation, but can be added if there is ambiguity. - -### Instrument Units - -**Status**: [Stable](../../document-status.md) - -Units should follow the -[Unified Code for Units of Measure](http://unitsofmeasure.org/ucum.html). - -- Instruments for **utilization** metrics (that measure the fraction out of a -total) are dimensionless and SHOULD use the default unit `1` (the unity). -- All non-units that use curly braces to annotate a quantity need to match the - grammatical number of the quantity it represent. For example if measuring the - number of individual requests to a process the unit would be `{request}`, not - `{requests}`. -- Instruments that measure an integer count of something SHOULD only use -[annotations](https://ucum.org/ucum.html#para-curly) with curly braces to -give additional meaning *without* the leading default unit (`1`). For example, -use `{packet}`, `{error}`, `{fault}`, etc. -- Instrument units other than `1` and those that use - [annotations](https://ucum.org/ucum.html#para-curly) SHOULD be specified using - the UCUM case sensitive ("c/s") variant. - For example, "Cel" for the unit with full name "degree Celsius". -- Instruments SHOULD use non-prefixed units (i.e. `By` instead of `MiBy`) - unless there is good technical reason to not do so. -- When instruments are measuring durations, seconds (i.e. `s`) SHOULD be used. - -### Instrument Types - -**Status**: [Stable](../../document-status.md) - -The semantic metric conventions specification is written to use the names of the synchronous instrument types, -like `Counter` or `UpDownCounter`. However, compliant implementations MAY use the asynchronous equivalent instead, -like `Asynchronous Counter` or `Asynchronous UpDownCounter`. -Whether implementations choose the synchronous type or the asynchronous equivalent is considered to be an -implementation detail. Both choices are compliant with this specification. - -### Consistent UpDownCounter timeseries - -**Status**: [Experimental](../../document-status.md) - -When recording `UpDownCounter` metrics, the same attribute values used to record an increment SHOULD be used to record -any associated decrement, otherwise those increments and decrements will end up as different timeseries. - -For example, if you are tracking `active_requests` with an `UpDownCounter`, and you are incrementing it each time a -request starts and decrementing it each time a request ends, then any attributes which are not yet available when -incrementing the counter at request start should not be used when decrementing the counter at request end. diff --git a/specification/metrics/semantic_conventions/database-metrics.md b/specification/metrics/semantic_conventions/database-metrics.md deleted file mode 100644 index 8ab20830575..00000000000 --- a/specification/metrics/semantic_conventions/database-metrics.md +++ /dev/null @@ -1,66 +0,0 @@ - - -# Semantic Conventions for Database Metrics - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -The conventions described in this section are specific to SQL and NoSQL clients. - -**Disclaimer:** These are initial database client metric instruments and attributes but more may be added in the future. - - - - - -- [Metric Instruments](#metric-instruments) - * [Connection pools](#connection-pools) - - - -## Metric Instruments - -The following metric instruments MUST be used to describe database client operations. They MUST be of the specified type -and units. - -### Connection pools - -Below is a table of database client connection pool metric instruments that MUST be used by connection pool -instrumentations: - -| Name | Instrument | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | -|-------------------------------|----------------------------|-------------|-------------------------------------------|-------------------------------------------------------------------------------------------| -| `db.client.connections.usage` | UpDownCounter | connections | `{connection}` | The number of connections that are currently in state described by the `state` attribute. | - -All `db.client.connections.usage` measurements MUST include the following attribute: - -| Name | Type | Description | Examples | Requirement Level | -|---------|--------|------------------------------------------------------------------------------|----------|-------------------| -| `state` | string | The state of a connection in the pool. Valid values include: `idle`, `used`. | `idle` | Required | - -Instrumentation libraries for database client connection pools that collect data for the following data MUST use the -following metric instruments. Otherwise, if the instrumentation library does not collect this data, these instruments -MUST NOT be used. - -| Name | Instrument ([*](README.md#instrument-types)) | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | -|------------------------------------------|----------------------------------------------|--------------|-------------------------------------------|---------------------------------------------------------------------------------------------------| -| `db.client.connections.idle.max` | UpDownCounter | connections | `{connection}` | The maximum number of idle open connections allowed. | -| `db.client.connections.idle.min` | UpDownCounter | connections | `{connection}` | The minimum number of idle open connections allowed. | -| `db.client.connections.max` | UpDownCounter | connections | `{connection}` | The maximum number of open connections allowed. | -| `db.client.connections.pending_requests` | UpDownCounter | requests | `{request}` | The number of pending requests for an open connection, cumulative for the entire pool. | -| `db.client.connections.timeouts` | Counter | timeouts | `{timeout}` | The number of connection timeouts that have occurred trying to obtain a connection from the pool. | -| `db.client.connections.create_time` | Histogram | milliseconds | `ms` | The time it took to create a new connection. | -| `db.client.connections.wait_time` | Histogram | milliseconds | `ms` | The time it took to obtain an open connection from the pool. | -| `db.client.connections.use_time` | Histogram | milliseconds | `ms` | The time between borrowing a connection and returning it to the pool. | - -Below is a table of the attributes that MUST be included on all connection pool measurements: - -| Name | Type | Description | Examples | Requirement Level | -|-------------|--------|------------------------------------------------------------------------------|----------------|-------------------| -| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation does not provide a name, then the [db.connection_string](/specification/trace/semantic_conventions/database.md#connection-level-attributes) should be used. | `myDataSource` | Required | diff --git a/specification/metrics/semantic_conventions/faas-metrics.md b/specification/metrics/semantic_conventions/faas-metrics.md deleted file mode 100644 index 99a94b3002f..00000000000 --- a/specification/metrics/semantic_conventions/faas-metrics.md +++ /dev/null @@ -1,88 +0,0 @@ - - -# Semantic Conventions for FaaS Metrics - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -This document defines how to describe an instance of a function that runs without provisioning -or managing of servers (also known as serverless functions or Function as a Service (FaaS)) with metrics. - -The conventions described in this section are FaaS (function as a service) specific. When FaaS operations occur, -metric events about those operations will be generated and reported to provide insights into the -operations. By adding FaaS attributes to metric events it allows for finely tuned filtering. - -**Disclaimer:** These are initial FaaS metric instruments and attributes but more may be added in the future. - - - - - -- [Metric Instruments](#metric-instruments) - * [FaaS Invocations](#faas-invocations) -- [Attributes](#attributes) -- [References](#references) - * [Metric References](#metric-references) - - - -## Metric Instruments - -The following metric instruments MUST be used to describe FaaS operations. They MUST be of the specified -type and units. - -### FaaS Invocations - -Below is a table of FaaS invocation metric instruments. - -| Name | Instrument Type ([*](README.md#instrument-types)) | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | -|------------------------|---------------------------------------------------|--------------|-------------------------------------------|------------------------------------------------------------------------------| -| `faas.invoke_duration` | Histogram | milliseconds | `ms` | Measures the duration of the invocation | -| `faas.init_duration` | Histogram | milliseconds | `ms` | Measures the duration of the function's initialization, such as a cold start | -| `faas.coldstarts` | Counter | default unit | `{coldstart}` | Number of invocation cold starts. | -| `faas.errors` | Counter | default unit | `{error}` | Number of invocation errors. | -| `faas.invocations` | Counter | default unit | `{invocation}` | Number of successful invocations. | -| `faas.timeouts` | Counter | default unit | `{timeout}` | Number of invocation timeouts. | - -Optionally, when applicable: - -| Name | Instrument Type ([*](README.md#instrument-types)) | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | -|------------------|---------------------------------------------------|--------------|-------------------------------------------|-------------------------------------------------| -| `faas.mem_usage` | Histogram | Bytes | `By` | Distribution of max memory usage per invocation | -| `faas.cpu_usage` | Histogram | milliseconds | `ms` | Distribution of CPU usage per invocation | -| `faas.net_io` | Histogram | Bytes | `By` | Distribution of net I/O usage per invocation | - -## Attributes - -Below is a table of the attributes to be included on FaaS metric events. - -| Name | Requirement Level | Notes and examples | -|-------------------------|-------------------|--------------------------------------------------------------------------------------------------------------------------| -| `faas.trigger` | Required | Type of the trigger on which the function is invoked. SHOULD be one of: `datasource`, `http`, `pubsub`, `timer`, `other` | -| `faas.invoked_name` | Required | Name of the invoked function. Example: `my-function` | -| `faas.invoked_provider` | Required | Cloud provider of the invoked function. Corresponds to the resource `cloud.provider`. Example: `aws` | -| `faas.invoked_region` | Required | Cloud provider region of invoked function. Corresponds to resource `cloud.region`. Example: `us-east-1` | - -More details on these attributes, the function name and the difference compared to the faas.invoked_name can be found at the related [FaaS tracing specification](../../trace/semantic_conventions/faas.md). -For incoming FaaS invocations, the function for which metrics are reported is already described by its [FaaS resource attributes](../../resource/semantic_conventions/faas.md). -Outgoing FaaS invocations are identified using the `faas.invoked_*` attributes above. -`faas.trigger` SHOULD be included in all metric events while `faas.invoked_*` attributes apply on outgoing FaaS invocation events only. - -## References - -### Metric References - -Below are links to documentation regarding metrics that are available with different -FaaS providers. This list is not exhaustive. - -* [AWS Lambda Metrics](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-metrics.html) -* [AWS Lambda Insight Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights-metrics.html) -* [Azure Functions Metrics](https://docs.microsoft.com/azure/azure-monitor/platform/metrics-supported) -* [Google CloudFunctions Metrics](https://cloud.google.com/monitoring/api/metrics_gcp#gcp-cloudfunctions) -* [OpenFaas Metrics](https://docs.openfaas.com/architecture/metrics/) diff --git a/specification/metrics/semantic_conventions/hardware-metrics.md b/specification/metrics/semantic_conventions/hardware-metrics.md deleted file mode 100644 index 709347558fc..00000000000 --- a/specification/metrics/semantic_conventions/hardware-metrics.md +++ /dev/null @@ -1,394 +0,0 @@ - - -# Semantic Conventions for Hardware Metrics - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -This document describes instruments and attributes for common hardware level -metrics in OpenTelemetry. Consider the [general metric semantic conventions](README.md#general-metric-semantic-conventions) -when creating instruments not explicitly defined in the specification. - - - -- [Common hardware attributes](#common-hardware-attributes) -- [Metric Instruments](#metric-instruments) - * [`hw.` - Common hardware metrics](#hw---common-hardware-metrics) - * [`hw.host.` - Physical host metrics](#hwhost---physical-host-metrics) - * [`hw.battery.` - Battery metrics](#hwbattery---battery-metrics) - * [`hw.cpu.` - Physical processor metrics](#hwcpu---physical-processor-metrics) - * [`hw.disk_controller.` - Disk controller metrics](#hwdisk_controller---disk-controller-metrics) - * [`hw.enclosure.` - Enclosure metrics](#hwenclosure---enclosure-metrics) - * [`hw.fan.` - Fan metrics](#hwfan---fan-metrics) - * [`hw.gpu.` - GPU metrics](#hwgpu---gpu-metrics) - * [`hw.logical_disk.`- Logical disk metrics](#hwlogical_disk--logical-disk-metrics) - * [`hw.memory.` - Memory module metrics](#hwmemory---memory-module-metrics) - * [`hw.network.` - Network adapter metrics](#hwnetwork---network-adapter-metrics) - * [`hw.physical_disk.`- Physical disk metrics](#hwphysical_disk--physical-disk-metrics) - * [`hw.power_supply.` - Power supply metrics](#hwpower_supply---power-supply-metrics) - * [`hw.tape_drive.` - Tape drive metrics](#hwtape_drive---tape-drive-metrics) - * [`hw.temperature.` - Temperature sensor metrics](#hwtemperature---temperature-sensor-metrics) - * [`hw.voltage.` - Voltage sensor metrics](#hwvoltage---voltage-sensor-metrics) - - - -## Common hardware attributes - -All metrics in `hw.` instruments should be attached to a [Host Resource](../../resource/semantic_conventions/host.md) -and therefore inherit its attributes, like `host.id` and `host.name`. - -Additionally, all metrics in `hw.` instruments have the following attributes: - -| Attribute Key | Description | Example | Requirement Level | -| ------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ----------------- | -| `id` | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | **Required** | -| `name` | An easily-recognizable name for the hardware component | `eth0` | Recommended | -| `parent` | Unique identifier of the parent component (typically the `id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | Recommended | - -## Metric Instruments - -### `hw.` - Common hardware metrics - -The below metrics apply to any type of hardware component. - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | -| ----------- | ---------------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ----------------------------- | -------------------------- | -| `hw.energy` | Energy consumed by the component, in joules | J | Counter | Int64 | | | -| `hw.errors` | Number of errors encountered by the component | {error} | Counter | Int64 | `hw.error.type` (Recommended) | | -| `hw.power` | Instantaneous power consumed by the component, in Watts (`hw.energy` is preferred) | W | Gauge | Double | | | -| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` | - -These common `hw.` metrics must include the below attributes to describe the -monitored component: - -| Attribute Key | Description | Example | Requirement Level | -| ------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | -| `hw.type` | Type of the component | `battery`, `cpu`, `disk_controller`, `enclosure`, `fan`, `gpu`, `logical_disk`, `memory`, `network`, `physical_disk`, `power_supply`, `tape_drive`, `temperature`, `voltage` | **Required** | - -> **Warning** -> -> `hw.status` is currently specified as an *UpDownCounter* but would ideally be represented using a [*StateSet* as defined in OpenMetrics](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#stateset). This semantic convention will be updated once *StateSet* is specified in OpenTelemetry. This planned change is not expected to have any consequence on the way users query their timeseries backend to retrieve the values of `hw.status` over time. - -### `hw.host.` - Physical host metrics - -**Description:** Physical system as opposed to a virtual system or a container. -Examples: physical server, switch or disk array. - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | -| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ---------------- | ---------------- | -| `hw.host.ambient_temperature` | Ambient (external) temperature of the physical host | Cel | Gauge | Double | | | -| `hw.host.energy` | Total energy consumed by the entire physical host, in joules | J | Counter | Int64 | | | -| `hw.host.heating_margin` | By how many degrees Celsius the temperature of the physical host can be increased, before reaching a warning threshold on one of the internal sensors | Cel | Gauge | Double | | | -| `hw.host.power` | Instantaneous power consumed by the entire physical host in Watts (`hw.host.energy` is preferred) | W | Gauge | Double | | | - -> **Note** -> The overall energy usage of a host MUST be reported using the specific -> `hw.host.energy` and `hw.host.power` metrics **only**, instead of the generic -> `hw.energy` and `hw.power` described in the previous section, to prevent -> summing up overlapping values. - -### `hw.battery.` - Battery metrics - -**Description:** A battery in a computer system or an UPS. - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | -| ------------------------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | --------------------------------------------------------------------------- | ----------------------------------------------------- | -| `hw.battery.charge` | Remaining fraction of battery charge | 1 | Gauge | Double | | | -| `hw.battery.charge.limit` | Lower limit of battery charge fraction to ensure proper operation | 1 | Gauge | Double | `limit_type` (Recommended) | `critical`, `throttled`, `degraded` | -| `hw.battery.time_left` | Time left before battery is completely charged or discharged | s | Gauge | Int | `state` (Conditionally Required, if the battery is charging or discharging) | `charging`, `discharging` | -| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `charging`, `discharging` | -| | | | | | `hw.type` | `battery` | - -All `hw.battery.` metrics may include the below **Recommended** attributes to -describe the characteristics of the monitored battery: - -| Attribute Key | Description | Example | -| ------------- | --------------------------------------------- | --------------------------- | -| `chemistry` | Chemistry of the battery | Nickel-Cadmium, Lithium-ion | -| `capacity` | Design capacity in Watts-hours or Amper-hours | 9.3Ah | -| `model` | Descriptive model name | | -| `vendor` | Vendor name | | - -### `hw.cpu.` - Physical processor metrics - -**Description:** Physical processor (as opposed to the logical processor seen by -the operating system for multi-core systems). A physical processor may include -many individual cores. - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| -------------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | -------------------------- | ----------------------------------------------- | -| `hw.errors` | Total number of errors encountered and corrected by the CPU | {error} | Counter | Int64 | `hw.type` (**Required**) | `cpu` | -| `hw.cpu.speed` | CPU current frequency | Hz | Gauge | Int64 | | | -| `hw.cpu.speed.limit` | CPU maximum frequency | Hz | Gauge | Int64 | `limit_type` (Recommended) | `throttled`, `max`, `turbo` | -| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `predicted_failure` | -| | | | | | `hw.type` (**Required**) | `cpu` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| ------------- | ---------------------- | ------- | -| `model` | Descriptive model name | | -| `vendor` | Vendor name | | - -### `hw.disk_controller.` - Disk controller metrics - -**Description:** Controller that controls the physical disks and organize -them in RAID sets and logical disks that are exposed to the operating system. - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ----------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ------------------------ | -------------------------- | -| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` | -| | | | | | `hw.type` (**Required**) | `disk_controller` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| ------------------ | ------------------------- | ------- | -| `bios_version` | BIOS version | | -| `driver_version` | Driver for the controller | | -| `firmware_version` | Firmware version | | -| `model` | Descriptive model name | | -| `serial_number` | Serial number | | -| `vendor` | Vendor name | | - -### `hw.enclosure.` - Enclosure metrics - -**Description:** Computer chassis (can be an expansion enclosure) - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ----------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ------------------------ | ---------------------------------- | -| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `open` | -| | | | | | `hw.type` (**Required**) | `enclosure` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| --------------- | -------------------------------------------------- | ------------------------- | -| `bios_version` | BIOS version | | -| `model` | Descriptive model name | | -| `serial_number` | Serial number | | -| `type` | Type of the enclosure (useful for modular systems) | Computer, Storage, Switch | -| `vendor` | Vendor name | | - -### `hw.fan.` - Fan metrics - -**Description:** Fan that keeps the air flowing to maintain the internal -temperature of a computer - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| -------------------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ------------------------------ | ------------------------------------- | -| `hw.fan.speed` | Fan speed in revolutions per minute | rpm | Gauge | Int | | | -| `hw.fan.speed.limit` | Speed limit in rpm | rpm | Gauge | Int | `limit_type` (**Recommended**) | `low.critical`, `low.degraded`, `max` | -| `hw.fan.speed_ratio` | Fan speed expressed as a fraction of its maximum speed | 1 | Gauge | Double | | | -| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` | -| | | | | | `hw.type` (**Required**) | `fan` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| ----------------- | --------------------------------------------- | ---------------- | -| `sensor_location` | Location of the fan in the computer enclosure | cpu0, ps1, INLET | - -### `hw.gpu.` - GPU metrics - -**Description:** Graphics Processing Unit (discrete) - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| --------------------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ----------------------------- | ----------------------------------------------- | -| `hw.errors` | Number of errors encountered by the GPU | {error} | Counter | Int64 | `hw.error.type` (Recommended) | `corrected`, `uncorrected` | -| | | | | | `hw.type` (**Required**) | `gpu` | -| `hw.gpu.io` | Received and transmitted bytes by the GPU | By | Counter | Int64 | `direction` (**Required**) | `receive`, `transmit` | -| `hw.gpu.memory.limit` | Size of the GPU memory | By | UpDownCounter | Int64 | | | -| `hw.gpu.memory.utilization` | Fraction of GPU memory used | 1 | Gauge | Double | | | -| `hw.gpu.memory.usage` | GPU memory used | By | UpDownCounter | Int64 | | | -| `hw.gpu.power` | GPU instantaneous power consumption in Watts | W | Gauge | Double | | | -| `hw.gpu.utilization` | Fraction of time spent in a specific task | 1 | Gauge | Double | `task` (Recommended) | `decoder`, `encoder`, `general` | -| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `predicted_failure` | -| | | | | | `hw.type` (**Required**) | `gpu` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| ------------------ | ------------------------- | ------- | -| `driver_version` | Driver for the controller | | -| `firmware_version` | Firmware version | | -| `model` | Descriptive model name | | -| `serial_number` | Serial number | | -| `vendor` | Vendor name | | - -### `hw.logical_disk.`- Logical disk metrics - -**Description:** Storage extent presented as a physical disk by a disk -controller to the operating system (e.g. a RAID 1 set made of 2 disks, and exposed -as /dev/hdd0 by the controller). - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ----------------------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ------------------------ | -------------------------- | -| `hw.errors` | Number of errors encountered on this logical disk | {error} | Counter | Int64 | `hw.type` (**Required**) | `logical_disk` | -| `hw.logical_disk.limit` | Size of the logical disk | By | UpDownCounter | Int64 | | | -| `hw.logical_disk.usage` | Logical disk space usage | By | UpDownCounter | Int64 | `state` (**Required**) | `used`, `free` | -| `hw.logical_disk.utilization` | Logical disk space utilization as a fraction | 1 | Gauge | Double | `state` (**Required**) | `used`, `free` | -| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` | -| | | | | | `hw.type` (**Required**) | `logical_disk` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| ------------- | ----------- | --------- | -| `raid_level` | RAID Level | `RAID0+1` | - -### `hw.memory.` - Memory module metrics - -**Description:** A memory module in a computer system. - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ---------------- | ----------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ------------------------ | ----------------------------------------------- | -| `hw.errors` | Number of errors encountered on this memory module | {error} | Counter | Int64 | `hw.type` (**Required**) | `memory` | -| `hw.memory.size` | Size of the memory module | By | UpDownCounter | Int64 | | | -| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `predicted_failure` | -| | | | | | `hw.type` (**Required**) | `memory` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| --------------- | ------------------------- | ------- | -| `model` | Descriptive model name | | -| `serial_number` | Serial number | | -| `type` | Type of the memory module | `DDR5` | -| `vendor` | Vendor name | | - -### `hw.network.` - Network adapter metrics - -**Description:** A physical network interface, or a network interface controller -(NIC), excluding software-based virtual adapters and loopbacks. For example, a -physical network interface on a server, switch, router or firewall, an HBA, a -fiber channel port or a Wi-Fi adapter. - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ---------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------- | ---------- | ----------------------------- | --------------------------------- | -| `hw.errors` | Number of errors encountered by the network adapter | {error} | Counter | Int64 | `hw.error.type` (Recommended) | `zero_buffer_credit`, `crc`, etc. | -| | | | | | `hw.type` (**Required**) | `network` | -| | | | | | `direction` (Recommended) | `receive`, `transmit` | -| `hw.network.bandwidth.limit` | Link speed | By | UpDownCounter | Int64 | | | -| `hw.network.bandwidth.utilization` | Utilization of the network bandwidth as a fraction | 1 | Gauge | Double | | | -| `hw.network.io` | Received and transmitted network traffic in bytes | By | Counter | Int64 | `direction` (**Required**) | `receive`, `transmit` | -| `hw.network.packets` | Received and transmitted network traffic in packets (or frames) | {packet} | Counter | Int64 | `direction` (**Required**) | `receive`, `transmit` | -| `hw.network.up` | Link status: `1` (up) or `0` (down) | | UpDownCounter | Int | | | -| `hw.status` | Operational status, regardless of the link status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` | -| | | | | | `hw.type` (**Required**) | `network` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| ------------------- | ----------------------------------------------------------- | --------------------------- | -| `model` | Descriptive model name | | -| `logical_addresses` | Logical addresses of the adapter (e.g. IP address, or WWPN) | `172.16.8.21, 57.11.193.42` | -| `physical_address` | Physical address of the adapter (e.g. MAC address, or WWNN) | `00-90-F5-E9-7B-36` | -| `serial_number` | Serial number | | -| `vendor` | Vendor name | | - -### `hw.physical_disk.`- Physical disk metrics - -**Description:** Physical hard drive (HDD or SDD) - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ---------------------------------------- | ------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------- | ---------- | ------------------------------- | ----------------------------------------------- | -| `hw.errors` | Number of errors encountered on this disk | {error} | Counter | Int64 | `hw.error.type` (Recommended) | `bad_sector`, `write`, etc. | -| | | | | | `hw.type` (**Required**) | `physical_disk` | -| `hw.physical_disk.endurance_utilization` | Endurance remaining for this SSD disk | 1 | Gauge | Double | `state` (**Required**) | `remaining` | -| `hw.physical_disk.size` | Size of the disk | By | UpDownCounter | Int64 | | | -| `hw.physical_disk.smart` | Value of the corresponding [S.M.A.R.T.](https://en.wikipedia.org/wiki/S.M.A.R.T.) attribute | 1 | Gauge | Int | `smart_attribute` (Recommended) | `Seek Error Rate`, `Spin Retry Count`, etc. | -| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `predicted_failure` | -| | | | | | `hw.type` (**Required**) | `physical_disk` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| ------------------ | ---------------------- | ------------------- | -| `firmware_version` | Firmware version | | -| `model` | Descriptive model name | | -| `serial_number` | Serial number | | -| `type` | Type of the disk | `HDD`, `SSD`, `10K` | -| `vendor` | Vendor name | | - -### `hw.power_supply.` - Power supply metrics - -**Description:** Power supply converting AC current to DC used by the -motherboard and the GPUs - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ----------------------------- | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | -------------------------- | ------------------------------ | -| `hw.power_supply.limit` | Maximum power output of the power supply | W | UpDownCounter | Int64 | `limit_type` (Recommended) | `max`, `critical`, `throttled` | -| `hw.power_supply.utilization` | Utilization of the power supply as a fraction of its maximum output | 1 | Gauge | Double | | | -| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` | -| | | | | | `hw.type` (**Required**) | `power_supply` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| --------------- | ---------------------- | ------- | -| `model` | Descriptive model name | | -| `serial_number` | Serial number | | -| `vendor` | Vendor name | | - -### `hw.tape_drive.` - Tape drive metrics - -**Description:** A tape drive in a computer or in a tape library (excluding -virtual tape libraries) - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| -------------------------- | ----------------------------------------------------------------------------- | ----------- | ------------------------------------------------- | ---------- | ------------------------ | -------------------------------------------- | -| `hw.errors` | Number of errors encountered by the tape drive | {error} | Counter | Int64 | `hw.error.type` | `read`, `write`, `mount`, etc. | -| | | | | | `hw.type` (**Required**) | `tape_drive` | -| `hw.tape_drive.operations` | Operations performed by the tape drive | {operation} | Counter | Int64 | `type` (Recommended) | `mount`, `unmount`, `clean` | -| `hw.status` | Operational status: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed`, `needs_cleaning` | -| | | | | | `hw.type` (**Required**) | `tape_drive` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| --------------- | ---------------------- | ------- | -| `model` | Descriptive model name | | -| `serial_number` | Serial number | | -| `vendor` | Vendor name | | - -### `hw.temperature.` - Temperature sensor metrics - -**Description:** A temperature sensor, either numeric or discrete - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ---------------------- | --------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | -------------------------- | ---------------------------------------------------------------- | -| `hw.temperature` | Temperature in degrees Celsius | Cel | Gauge | Double | | | -| `hw.temperature.limit` | Temperature limit in degrees Celsius | Cel | Gauge | Double | `limit_type` (Recommended) | `low.critical`, `low.degraded`, `high.degraded`, `high.critical` | -| `hw.status` | Whether the temperature is within normal range: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` | -| | | | | | `hw.type` (**Required**) | `temperature` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| ----------------- | ---------------------- | ---------- | -| `sensor_location` | Location of the sensor | `CPU0_DIE` | - -### `hw.voltage.` - Voltage sensor metrics - -**Description:** A voltage sensor, either numeric or discrete - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| -------------------- | ----------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | -------------------------- | ---------------------------------------------------------------- | -| `hw.voltage.limit` | Voltage limit in Volts | V | Gauge | Double | `limit_type` (Recommended) | `low.critical`, `low.degraded`, `high.degraded`, `high.critical` | -| `hw.voltage.nominal` | Nominal (expected) voltage | V | Gauge | Double | | | -| `hw.voltage` | Voltage measured by the sensor | V | Gauge | Double | | | -| `hw.status` | Whether the voltage is within normal range: `1` (true) or `0` (false) for each of the possible states | | UpDownCounter | Int | `state` (**Required**) | `ok`, `degraded`, `failed` | -| | | | | | `hw.type` (**Required**) | `voltage` | - -Additional **Recommended** attributes: - -| Attribute Key | Description | Example | -| ----------------- | ---------------------- | ---------- | -| `sensor_location` | Location of the sensor | `PS0 V3_3` | diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md deleted file mode 100644 index e56b5de8d4f..00000000000 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ /dev/null @@ -1,355 +0,0 @@ - - -# Semantic Conventions for HTTP Metrics - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -The conventions described in this section are HTTP specific. When HTTP operations occur, -metric events about those operations will be generated and reported to provide insight into the -operations. By adding HTTP attributes to metric events it allows for finely tuned filtering. - -**Disclaimer:** These are initial HTTP metric instruments and attributes but more may be added in the future. - - - -- [HTTP Server](#http-server) - * [Metric: `http.server.duration`](#metric-httpserverduration) - * [Metric: `http.server.active_requests`](#metric-httpserveractive_requests) - * [Metric: `http.server.request.size`](#metric-httpserverrequestsize) - * [Metric: `http.server.response.size`](#metric-httpserverresponsesize) -- [HTTP Client](#http-client) - * [Metric: `http.client.duration`](#metric-httpclientduration) - * [Metric: `http.client.request.size`](#metric-httpclientrequestsize) - * [Metric: `http.client.response.size`](#metric-httpclientresponsesize) - - - -> **Warning** -> Existing HTTP instrumentations that are using -> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md) -> (or prior): -> -> * SHOULD NOT change the version of the HTTP or networking attributes that they emit -> until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in HTTP instrumentations). -> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` -> in the existing major version which supports the following values: -> * `none` - continue emitting whatever version of the old experimental -> HTTP and networking attributes the instrumentation was emitting previously. -> This is the default value. -> * `http` - emit the new, stable HTTP and networking attributes, -> and stop emitting the old experimental HTTP and networking attributes -> that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable HTTP and networking attributes, -> allowing for a seamless transition. -> * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). - -## HTTP Server - -### Metric: `http.server.duration` - -This metric is required. - -This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-advisory-parameters) -of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `http.server.duration` | Histogram | `s` | Measures the duration of inbound HTTP requests. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | -| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required | -| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`url.scheme`](../../common/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | - -**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. -SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. - -**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. - -**[3]:** Determined by using the first of the following that applies - -- The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only - include host identifier. -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Host identifier of the `Host` header - -SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. - -**[4]:** Determined by using the first of the following that applies - -- Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. -- Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Port identifier of the `Host` header - -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). - - -### Metric: `http.server.active_requests` - -This metric is optional. - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `http.server.active_requests` | UpDownCounter | `{request}` | Measures the number of concurrent HTTP requests that are currently in-flight. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [1] | `example.com` | Required | -| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [2] | `80`; `8080`; `443` | Conditionally Required: [3] | -| [`url.scheme`](../../common/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | - -**[1]:** Determined by using the first of the following that applies - -- The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only - include host identifier. -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Host identifier of the `Host` header - -SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. - -**[2]:** Determined by using the first of the following that applies - -- Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. -- Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Port identifier of the `Host` header - -**[3]:** If not default (`80` for `http` scheme, `443` for `https`). - - -### Metric: `http.server.request.size` - -This metric is optional. - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `http.server.request.size` | Histogram | `By` | Measures the size of HTTP request messages (compressed). | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | -| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required | -| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`url.scheme`](../../common/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | - -**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. -SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. - -**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. - -**[3]:** Determined by using the first of the following that applies - -- The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only - include host identifier. -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Host identifier of the `Host` header - -SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. - -**[4]:** Determined by using the first of the following that applies - -- Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. -- Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Port identifier of the `Host` header - -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). - - -### Metric: `http.server.response.size` - -This metric is optional. - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `http.server.response.size` | Histogram | `By` | Measures the size of HTTP response messages (compressed). | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | -| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required | -| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`url.scheme`](../../common/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | - -**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. -SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. - -**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. - -**[3]:** Determined by using the first of the following that applies - -- The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only - include host identifier. -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Host identifier of the `Host` header - -SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. - -**[4]:** Determined by using the first of the following that applies - -- Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. -- Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Port identifier of the `Host` header - -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). - - -## HTTP Client - -### Metric: `http.client.duration` - -This metric is required. - -This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-advisory-parameters) -of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `http.client.duration` | Histogram | `s` | Measures the duration of outbound HTTP requests. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | -| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | -| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | -| [`server.socket.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. | - -**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. - -**[2]:** Determined by using the first of the following that applies - -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form -- Host identifier of the `Host` header - -SHOULD NOT be set if capturing it would require an extra DNS lookup. - -**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. - -**[4]:** If not default (`80` for `http` scheme, `443` for `https`). - - -### Metric: `http.client.request.size` - -This metric is optional. - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `http.client.request.size` | Histogram | `By` | Measures the size of HTTP request messages (compressed). | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | -| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | -| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | -| [`server.socket.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. | - -**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. - -**[2]:** Determined by using the first of the following that applies - -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form -- Host identifier of the `Host` header - -SHOULD NOT be set if capturing it would require an extra DNS lookup. - -**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. - -**[4]:** If not default (`80` for `http` scheme, `443` for `https`). - - -### Metric: `http.client.response.size` - -This metric is optional. - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `http.client.response.size` | Histogram | `By` | Measures the size of HTTP response messages (compressed). | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | -| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | -| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | -| [`server.socket.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. | - -**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. - -**[2]:** Determined by using the first of the following that applies - -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form -- Host identifier of the `Host` header - -SHOULD NOT be set if capturing it would require an extra DNS lookup. - -**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. - -**[4]:** If not default (`80` for `http` scheme, `443` for `https`). - diff --git a/specification/metrics/semantic_conventions/instrumentation/README.md b/specification/metrics/semantic_conventions/instrumentation/README.md deleted file mode 100644 index 2b46ff92c3e..00000000000 --- a/specification/metrics/semantic_conventions/instrumentation/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# Instrumentation - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. diff --git a/specification/metrics/semantic_conventions/instrumentation/kafka.md b/specification/metrics/semantic_conventions/instrumentation/kafka.md deleted file mode 100644 index c9e24f94c78..00000000000 --- a/specification/metrics/semantic_conventions/instrumentation/kafka.md +++ /dev/null @@ -1,89 +0,0 @@ - - -# Instrumenting Kafka - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../../document-status.md) - -This document defines how to apply semantic conventions when instrumenting Kafka. - - - -- [Kafka Metrics](#kafka-metrics) -- [Kafka Producer Metrics](#kafka-producer-metrics) -- [Kafka Consumer Metrics](#kafka-consumer-metrics) - - - -## Kafka Metrics - -**Description:** General Kafka metrics. - -| Name | Instrument | Value type | Unit | Unit ([UCUM](../README.md#instrument-units)) | Description | Attribute Key | Attribute Values | -| ---------------------------------------------| ------------- | ---------- | ------ | -------------------------------------------- | -------------- | ------------- | ---------------- | -| messaging.kafka.messages | Counter | Int64 | messages | `{message}` | The number of messages received by the broker. | | | -| messaging.kafka.requests.failed | Counter | Int64 | requests | `{request}` | The number of requests to the broker resulting in a failure. | `type` | `produce`, `fetch` | -| messaging.kafka.requests.queue | UpDownCounter | Int64 | requests | `{request}` | The number of requests in the request queue. | | | -| messaging.kafka.network.io | Counter | Int64 | bytes | `By` | The bytes received or sent by the broker. | `state` | `in`, `out` | -| messaging.kafka.purgatory.size | UpDownCounter | Int64 | requests | `{request}` | The number of requests waiting in the purgatory. | `type` | `produce`, `fetch` | -| messaging.kafka.partitions.all | UpDownCounter | Int64 | partitions | `{partition}` | The number of partitions in the broker. | | | -| messaging.kafka.partitions.offline | UpDownCounter | Int64 | partitions | `{partition}` | The number of offline partitions. | | | -| messaging.kafka.partitions.under-replicated | UpDownCounter | Int64 | partition | `{partition}` | The number of under replicated partitions. | | | -| messaging.kafka.isr.operations | Counter | Int64 | operations | `{operation}` | The number of in-sync replica shrink and expand operations. | `operation` | `shrink`, `expand` | -| messaging.kafka.lag_max | Gauge | Int64 | lag max | `{message}` | Max lag in messages between follower and leader replicas. | | | -| messaging.kafka.controllers.active | UpDownCounter | Int64 | controllers | `{controller}` | The number of active controllers in the broker. | | | -| messaging.kafka.leader.elections | Counter | Int64 | elections | `{election}` | Leader election rate (increasing values indicates broker failures). | | | -| messaging.kafka.leader.unclean-elections | Counter | Int64 | elections | `{election}` | Unclean leader election rate (increasing values indicates broker failures). | | | -| messaging.kafka.brokers | UpDownCounter | Int64 | brokers | `{broker}` | Number of brokers in the cluster. | | | -| messaging.kafka.topic.partitions | UpDownCounter | Int64 | partitions | `{partition}` | Number of partitions in topic. | `topic` | The ID (integer) of a topic | -| messaging.kafka.partition.current_offset | Gauge | Int64 | partition offset | `{partition offset}` | Current offset of partition of topic. | `topic` | The ID (integer) of a topic | -| | | | | | | `partition` | The number (integer) of the partition | -| messaging.kafka.partition.oldest_offset | Gauge | Int64 | partition offset | `{partition offset}` | Oldest offset of partition of topic | `topic` | The ID (integer) of a topic | -| | | | | | | `partition` | The number (integer) of the partition | -| messaging.kafka.partition.replicas.all | UpDownCounter | Int64 | replicas | `{replica}` | Number of replicas for partition of topic | `topic` | The ID (integer) of a topic | -| | | | | | | `partition` | The number (integer) of the partition | -| messaging.kafka.partition.replicas.in_sync | UpDownCounter | Int64 | replicas | `{replica}` | Number of synchronized replicas of partition | `topic` | The ID (integer) of a topic | -| | | | | | | `partition` | The number (integer) of the partition| - -## Kafka Producer Metrics - -**Description:** Kafka Producer level metrics. - -| Name | Instrument | Value type | Unit | Unit ([UCUM](../README.md#instrument-units)) | Description | Attribute Key | Attribute Values | -| --------------------------------------------- | ------------- | ---------- | ------ | -------------------------------------------- | -------------- | ------------- | ---------------- | -| messaging.kafka.producer.outgoing-bytes.rate | Gauge | Double | bytes per second | `By/s` | The average number of outgoing bytes sent per second to all servers. | `client-id` | `client-id` value | -| messaging.kafka.producer.responses.rate | Gauge | Double | responses per second | `{response}/s` | The average number of responses received per second. | `client-id` | `client-id` value | -| messaging.kafka.producer.bytes.rate | Gauge | Double | bytes per second | `By/s` | The average number of bytes sent per second for a specific topic. | `client-id` | `client-id` value | -| | | | | | | `topic` | topic name | -| messaging.kafka.producer.compression-ratio | Gauge | Double | compression ratio | `{compression}` | The average compression ratio of record batches for a specific topic. | `client-id` | `client-id` value | -| | | | | | | `topic` | topic name | -| messaging.kafka.producer.record-error.rate | Gauge | Double | error rate | `{error}/s` | The average per-second number of record sends that resulted in errors for a specific topic. | `client-id` | `client-id` value | -| | | | | | | `topic` | topic name | -| messaging.kafka.producer.record-retry.rate | Gauge | Double | retry rate | `{retry}/s` | The average per-second number of retried record sends for a specific topic. | `client-id` | `client-id` value | -| | | | | | | `topic` | topic name | -| messaging.kafka.producer.record-sent.rate | Gauge | Double | records sent rate | `{record_sent}/s` | The average number of records sent per second for a specific topic. | `client-id` | `client-id` value | -| | | | | | | `topic` | topic name | - -## Kafka Consumer Metrics - -**Description:** Kafka Consumer level metrics. - -| Name | Instrument | Value type | Unit | Unit ([UCUM](../README.md#instrument-units)) | Description | Attribute Key | Attribute Values | -| --------------------------------------------- | ------------- | ---------- | ------ | -------------------------------------------- | -------------- | ------------- | ---------------- | -| messaging.kafka.consumer.members | UpDownCounter | Int64 | members | `{member}` | Count of members in the consumer group | `group` | The ID (string) of a consumer group | -| messaging.kafka.consumer.offset | Gauge | Int64 | offset | `{offset}` | Current offset of the consumer group at partition of topic | `group` | The ID (string) of a consumer group | -| | | | | | | `topic` | The ID (integer) of a topic | -| | | | | | | `partition` | The number (integer) of the partition | -| messaging.kafka.consumer.offset_sum | Gauge | Int64 | offset sum | `{offset sum}` | Sum of consumer group offset across partitions of topic | `group` | The ID (string) of a consumer group | -| | | | | | | `topic` | The ID (integer) of a topic | -| messaging.kafka.consumer.lag | Gauge | Int64 | lag | `{lag}` | Current approximate lag of consumer group at partition of topic | `group` | The ID (string) of a consumer group | -| | | | | | | `topic` | The ID (integer) of a topic | -| | | | | | | `partition` | The number (integer) of the partition | -| messaging.kafka.consumer.lag_sum | Gauge | Int64 | lag sum | `{lag sum}` | Current approximate sum of consumer group lag across all partitions of topic | `group` | The ID (string) of a consumer group | -| | | | | | | `topic` | The ID (integer) of a topic | diff --git a/specification/metrics/semantic_conventions/process-metrics.md b/specification/metrics/semantic_conventions/process-metrics.md deleted file mode 100644 index a53f0e9f1ee..00000000000 --- a/specification/metrics/semantic_conventions/process-metrics.md +++ /dev/null @@ -1,54 +0,0 @@ - - -# Semantic Conventions for OS Process Metrics - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -This document describes instruments and attributes for common OS process level -metrics in OpenTelemetry. Also consider the [general metric semantic -conventions](README.md#general-metric-semantic-conventions) when creating -instruments not explicitly defined in this document. OS process metrics are -not related to the runtime environment of the program, and should take -measurements from the operating system. For runtime environment metrics see -[semantic conventions for runtime environment -metrics](runtime-environment-metrics.md). - - - - - -- [Metric Instruments](#metric-instruments) - * [Process](#process) -- [Attributes](#attributes) - - - -## Metric Instruments - -### Process - -Below is a table of Process metric instruments. - -| Name | Instrument Type ([\*](README.md#instrument-types)) | Unit | Description | Labels | -|---------------------------------|----------------------------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `process.cpu.time` | Counter | s | Total CPU seconds broken down by different states. | `state`, if specified, SHOULD be one of: `system`, `user`, `wait`. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | -| `process.cpu.utilization` | Gauge | 1 | Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process. | `state`, if specified, SHOULD be one of: `system`, `user`, `wait`. A process SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | -| `process.memory.usage` | UpDownCounter | By | The amount of physical memory in use. | | -| `process.memory.virtual` | UpDownCounter | By | The amount of committed virtual memory. | | -| `process.disk.io` | Counter | By | Disk bytes transferred. | `direction` SHOULD be one of: `read`, `write` | -| `process.network.io` | Counter | By | Network bytes transferred. | `direction` SHOULD be one of: `receive`, `transmit` | -| `process.threads` | UpDownCounter | {thread} | Process threads count. | | -| `process.open_file_descriptors` | UpDownCounter | {count} | Number of file descriptors in use by the process. | | -| `process.context_switches` | Counter | {count} | Number of times the process has been context switched. | `type` SHOULD be one of: `involuntary`, `voluntary` | -| `process.paging.faults` | Counter | {fault} | Number of page faults the process has made. | `type`, if specified, SHOULD be one of: `major` (for major, or hard, page faults), `minor` (for minor, or soft, page faults). | - -## Attributes - -Process metrics SHOULD be associated with a [`process`](../../resource/semantic_conventions/process.md#process) resource whose attributes provide additional context about the process. diff --git a/specification/metrics/semantic_conventions/rpc-metrics.md b/specification/metrics/semantic_conventions/rpc-metrics.md deleted file mode 100644 index 007fea85aff..00000000000 --- a/specification/metrics/semantic_conventions/rpc-metrics.md +++ /dev/null @@ -1,227 +0,0 @@ - - -# General RPC conventions - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -The conventions described in this section are RPC specific. When RPC operations -occur, measurements about those operations are recorded to instruments. The -measurements are aggregated and exported as metrics, which provide insight into -those operations. By including RPC properties as attributes on measurements, the -metrics can be filtered for finer grain analysis. - - - - - -- [Metric instruments](#metric-instruments) - * [RPC Server](#rpc-server) - * [RPC Client](#rpc-client) -- [Attributes](#attributes) - * [Service name](#service-name) -- [gRPC conventions](#grpc-conventions) - * [gRPC Attributes](#grpc-attributes) -- [Connect RPC conventions](#connect-rpc-conventions) - * [Connect RPC Attributes](#connect-rpc-attributes) - - - -> **Warning** -> Existing RPC instrumentations that are using -> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/rpc-metrics.md) -> (or prior): -> -> * SHOULD NOT change the version of the networking attributes that they emit -> until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in RPC instrumentations). -> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` -> in the existing major version which supports the following values: -> * `none` - continue emitting whatever version of the old experimental -> networking attributes the instrumentation was emitting previously. -> This is the default value. -> * `http` - emit the new, stable networking attributes, -> and stop emitting the old experimental networking attributes -> that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable networking attributes, -> allowing for a seamless transition. -> * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). - -## Metric instruments - -The following metric instruments MUST be used to describe RPC operations. They -MUST be of the specified type and units. - -*Note: RPC server and client metrics are split to allow correlation across client/server boundaries, e.g. Lining up an RPC method latency to determine if the server is responsible for latency the client is seeing.* - -### RPC Server - -Below is a table of RPC server metric instruments. - -| Name | Instrument Type ([*](README.md#instrument-types)) | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | Status | Streaming | -|------|------------|------|-------------------------------------------|-------------|--------|-----------| -| `rpc.server.duration` | Histogram | milliseconds | `ms` | measures duration of inbound RPC | Recommended | N/A. While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. | -| `rpc.server.request.size` | Histogram | Bytes | `By` | measures size of RPC request messages (uncompressed) | Optional | Recorded per message in a streaming batch | -| `rpc.server.response.size` | Histogram | Bytes | `By` | measures size of RPC response messages (uncompressed) | Optional | Recorded per response in a streaming batch | -| `rpc.server.requests_per_rpc` | Histogram | count | `{count}` | measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs | Optional | Required | -| `rpc.server.responses_per_rpc` | Histogram | count | `{count}` | measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs | Optional | Required | - -### RPC Client - -Below is a table of RPC client metric instruments. These apply to traditional -RPC usage, not streaming RPCs. - -| Name | Instrument Type ([*](README.md#instrument-types)) | Unit | Unit ([UCUM](README.md#instrument-units)) | Description | Status | Streaming | -|------|------------|------|-------------------------------------------|-------------|--------|-----------| -| `rpc.client.duration` | Histogram | milliseconds | `ms` | measures duration of outbound RPC | Recommended | N/A. While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. | -| `rpc.client.request.size` | Histogram | Bytes | `By` | measures size of RPC request messages (uncompressed) | Optional | Recorded per message in a streaming batch | -| `rpc.client.response.size` | Histogram | Bytes | `By` | measures size of RPC response messages (uncompressed) | Optional | Recorded per message in a streaming batch | -| `rpc.client.requests_per_rpc` | Histogram | count | `{count}` | measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs | Optional | Required | -| `rpc.client.responses_per_rpc` | Histogram | count | `{count}` | measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs | Optional | Required | - -## Attributes - -Below is a table of attributes that SHOULD be included on client and server RPC -measurements. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`rpc.system`](../../trace/semantic_conventions/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | -| [`rpc.service`](../../trace/semantic_conventions/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended | -| [`rpc.method`](../../trace/semantic_conventions/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended | -| [`network.transport`](../../trace/semantic_conventions/span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | -| [`network.type`](../../trace/semantic_conventions/span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | -| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: See below | -| [`server.socket.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | See below | -| [`server.socket.port`](../../trace/semantic_conventions/span-general.md) | int | Physical server port. | `16456` | Recommended: [4] | - -**[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). - -**[2]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). - -**[3]:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. - -**[4]:** If different than `server.port` and if `server.socket.address` is set. - -**Additional attribute requirements:** At least one of the following sets of attributes is required: - -* [`server.socket.address`](../../trace/semantic_conventions/span-general.md) -* [`server.address`](../../trace/semantic_conventions/span-general.md) - -`rpc.system` 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 | -|---|---| -| `grpc` | gRPC | -| `java_rmi` | Java RMI | -| `dotnet_wcf` | .NET WCF | -| `apache_dubbo` | Apache Dubbo | -| `connect_rpc` | Connect RPC | - - -To avoid high cardinality, implementations should prefer the most stable of `server.address` or -`server.socket.address`, depending on expected deployment profile. For many cloud applications, this is likely -`server.address` as names can be recycled even across re-instantiation of a server with a different `ip`. - -For client-side metrics `server.port` is required if the connection is IP-based and the port is available (it describes the server port they are connecting to). -For server-side spans `server.port` is optional (it describes the port the client is connecting from). - -[network.transport]: ../../trace/semantic_conventions/span-general.md#network-attributes - -### Service name - -On the server process receiving and handling the remote procedure call, the service name provided in `rpc.service` does not necessarily have to match the [`service.name`][] resource attribute. -One process can expose multiple RPC endpoints and thus have multiple RPC service names. From a deployment perspective, as expressed by the `service.*` resource attributes, it will be treated as one deployed service with one `service.name`. - -[`service.name`]: ../../resource/semantic_conventions/README.md#service - -## gRPC conventions - -For remote procedure calls via [gRPC][], additional conventions are described in this section. - -`rpc.system` MUST be set to `"grpc"`. - -### gRPC Attributes - -Below is a table of attributes that SHOULD be included on client and server RPC measurements when `rpc.system` is `"grpc"`. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`rpc.grpc.status_code`](../../trace/semantic_conventions/rpc.md) | int | The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. | `0` | Required | - -`rpc.grpc.status_code` MUST be one of the following: - -| Value | Description | -|---|---| -| `0` | OK | -| `1` | CANCELLED | -| `2` | UNKNOWN | -| `3` | INVALID_ARGUMENT | -| `4` | DEADLINE_EXCEEDED | -| `5` | NOT_FOUND | -| `6` | ALREADY_EXISTS | -| `7` | PERMISSION_DENIED | -| `8` | RESOURCE_EXHAUSTED | -| `9` | FAILED_PRECONDITION | -| `10` | ABORTED | -| `11` | OUT_OF_RANGE | -| `12` | UNIMPLEMENTED | -| `13` | INTERNAL | -| `14` | UNAVAILABLE | -| `15` | DATA_LOSS | -| `16` | UNAUTHENTICATED | - - -[gRPC]: https://grpc.io/ - -## Connect RPC conventions - -For remote procedure calls via [connect](http://connect.build), additional conventions are described in this section. - -`rpc.system` MUST be set to `"connect_rpc"`. - -### Connect RPC Attributes - -Below is a table of attributes that SHOULD be included on client and server RPC measurements when `rpc.system` is `"connect_rpc"`. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`rpc.connect_rpc.error_code`](../../trace/semantic_conventions/rpc.md) | string | The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values. | `cancelled` | Conditionally Required: [1] | - -**[1]:** If response is not successful and if error code available. - -`rpc.connect_rpc.error_code` MUST be one of the following: - -| Value | Description | -|---|---| -| `cancelled` | cancelled | -| `unknown` | unknown | -| `invalid_argument` | invalid_argument | -| `deadline_exceeded` | deadline_exceeded | -| `not_found` | not_found | -| `already_exists` | already_exists | -| `permission_denied` | permission_denied | -| `resource_exhausted` | resource_exhausted | -| `failed_precondition` | failed_precondition | -| `aborted` | aborted | -| `out_of_range` | out_of_range | -| `unimplemented` | unimplemented | -| `internal` | internal | -| `unavailable` | unavailable | -| `data_loss` | data_loss | -| `unauthenticated` | unauthenticated | - diff --git a/specification/metrics/semantic_conventions/runtime-environment-metrics.md b/specification/metrics/semantic_conventions/runtime-environment-metrics.md deleted file mode 100644 index 127d9daacfd..00000000000 --- a/specification/metrics/semantic_conventions/runtime-environment-metrics.md +++ /dev/null @@ -1,404 +0,0 @@ - - -# Semantic Conventions for Runtime Environment Metrics - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -This document includes semantic conventions for runtime environment level -metrics in OpenTelemetry. Also consider the [general -metric](README.md#general-metric-semantic-conventions), [system -metrics](system-metrics.md) and [OS Process metrics](process-metrics.md) -semantic conventions when instrumenting runtime environments. - - - - - -- [Metric Instruments](#metric-instruments) - * [Runtime Environment Specific Metrics - `process.runtime.{environment}.`](#runtime-environment-specific-metrics---processruntimeenvironment) -- [Attributes](#attributes) -- [JVM Metrics](#jvm-metrics) - * [Metric: `process.runtime.jvm.memory.usage`](#metric-processruntimejvmmemoryusage) - * [Metric: `process.runtime.jvm.memory.init`](#metric-processruntimejvmmemoryinit) - * [Metric: `process.runtime.jvm.memory.committed`](#metric-processruntimejvmmemorycommitted) - * [Metric: `process.runtime.jvm.memory.limit`](#metric-processruntimejvmmemorylimit) - * [Metric: `process.runtime.jvm.memory.usage_after_last_gc`](#metric-processruntimejvmmemoryusage_after_last_gc) - * [Metric: `process.runtime.jvm.gc.duration`](#metric-processruntimejvmgcduration) - * [Metric: `process.runtime.jvm.threads.count`](#metric-processruntimejvmthreadscount) - * [Metric: `process.runtime.jvm.classes.loaded`](#metric-processruntimejvmclassesloaded) - * [Metric: `process.runtime.jvm.classes.unloaded`](#metric-processruntimejvmclassesunloaded) - * [Metric: `process.runtime.jvm.classes.current_loaded`](#metric-processruntimejvmclassescurrent_loaded) - * [Metric: `process.runtime.jvm.cpu.utilization`](#metric-processruntimejvmcpuutilization) - * [Metric: `process.runtime.jvm.system.cpu.utilization`](#metric-processruntimejvmsystemcpuutilization) - * [Metric: `process.runtime.jvm.system.cpu.load_1m`](#metric-processruntimejvmsystemcpuload_1m) - * [Metric: `process.runtime.jvm.buffer.usage`](#metric-processruntimejvmbufferusage) - * [Metric: `process.runtime.jvm.buffer.limit`](#metric-processruntimejvmbufferlimit) - * [Metric: `process.runtime.jvm.buffer.count`](#metric-processruntimejvmbuffercount) - - - -## Metric Instruments - -Runtime environments vary widely in their terminology, implementation, and -relative values for a given metric. For example, Go and Python are both -garbage collected languages, but comparing heap usage between the Go and -CPython runtimes directly is not meaningful. For this reason, this document -does not propose any standard top-level runtime metric instruments. See [OTEP -108](https://github.com/open-telemetry/oteps/pull/108/files) for additional -discussion. - -### Runtime Environment Specific Metrics - `process.runtime.{environment}.` - -Metrics specific to a certain runtime environment should be prefixed with -`process.runtime.{environment}.` and follow the semantic conventions outlined in -[general metric semantic -conventions](README.md#general-metric-semantic-conventions). Authors of -runtime instrumentations are responsible for the choice of `{environment}` to -avoid ambiguity when interpreting a metric's name or values. - -For example, some programming languages have multiple runtime environments -that vary significantly in their implementation, like [Python which has many -implementations](https://wiki.python.org/moin/PythonImplementations). For -such languages, consider using specific `{environment}` prefixes to avoid -ambiguity, like `process.runtime.cpython.` and `process.runtime.pypy.`. - -There are other dimensions even within a given runtime environment to -consider, for example pthreads vs green thread implementations. - -## Attributes - -[`process.runtime`](../../resource/semantic_conventions/process.md#process-runtimes) resource attributes SHOULD be included on runtime metric events as appropriate. - -## JVM Metrics - -**Description:** Java Virtual Machine (JVM) metrics captured under `process.runtime.jvm.` - -### Metric: `process.runtime.jvm.memory.usage` - -This metric is [recommended](../metric-requirement-level.md#recommended). -This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.memory.usage` | UpDownCounter | `By` | Measure of memory used. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `pool` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `process.runtime.jvm.memory.init` - -This metric is [recommended](../metric-requirement-level.md#recommended). -This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.memory.init` | UpDownCounter | `By` | Measure of initial memory requested. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `pool` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `process.runtime.jvm.memory.committed` - -This metric is [recommended](../metric-requirement-level.md#recommended). -This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.memory.committed` | UpDownCounter | `By` | Measure of memory committed. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `pool` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `process.runtime.jvm.memory.limit` - -This metric is [recommended](../metric-requirement-level.md#recommended). -This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.memory.limit` | UpDownCounter | `By` | Measure of max obtainable memory. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `pool` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `process.runtime.jvm.memory.usage_after_last_gc` - -This metric is [recommended](../metric-requirement-level.md#recommended). -This metric is obtained from [`MemoryPoolMXBean#getCollectionUsage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryPoolMXBean.html#getCollectionUsage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.memory.usage_after_last_gc` | UpDownCounter | `By` | Measure of memory used, as measured after the most recent garbage collection event on this pool. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `type` | string | The type of memory. | `heap`; `non_heap` | Recommended | -| `pool` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | - -**[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). - -`type` MUST be one of the following: - -| Value | Description | -|---|---| -| `heap` | Heap memory. | -| `non_heap` | Non-heap memory | - - -### Metric: `process.runtime.jvm.gc.duration` - -This metric is [recommended](../metric-requirement-level.md#recommended). -This metric is obtained by subscribing to -[`GarbageCollectionNotificationInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GarbageCollectionNotificationInfo.html) events provided by [`GarbageCollectorMXBean`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/GarbageCollectorMXBean.html). The duration value is obtained from [`GcInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GcInfo.html#getDuration--) - -This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](../../metrics/api.md#instrument-advisory-parameters) -of `[]` (single bucket histogram capturing count, sum, min, max). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.gc.duration` | Histogram | `s` | Duration of JVM garbage collection actions. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `gc` | string | Name of the garbage collector. [1] | `G1 Young Generation`; `G1 Old Generation` | Recommended | -| `action` | string | Name of the garbage collector action. [2] | `end of minor GC`; `end of major GC` | Recommended | - -**[1]:** Garbage collector name is generally obtained via [GarbageCollectionNotificationInfo#getGcName()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcName()). - -**[2]:** Garbage collector action is generally obtained via [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()). - - -### Metric: `process.runtime.jvm.threads.count` - -This metric is [recommended](../metric-requirement-level.md#recommended). -This metric is obtained from [`ThreadMXBean#getDaemonThreadCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getDaemonThreadCount--) and -[`ThreadMXBean#getThreadCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getThreadCount--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.threads.count` | UpDownCounter | `{thread}` | Number of executing threads. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `daemon` | boolean | Whether the thread is daemon or not. | | Recommended | - - -### Metric: `process.runtime.jvm.classes.loaded` - -This metric is [recommended](../metric-requirement-level.md#recommended). -This metric is obtained from [`ClassLoadingMXBean#getTotalLoadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getTotalLoadedClassCount--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.classes.loaded` | Counter | `{class}` | Number of classes loaded since JVM start. | - - - - - -### Metric: `process.runtime.jvm.classes.unloaded` - -This metric is [recommended](../metric-requirement-level.md#recommended). -This metric is obtained from [`ClassLoadingMXBean#getUnloadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getUnloadedClassCount--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.classes.unloaded` | Counter | `{class}` | Number of classes unloaded since JVM start. | - - - - - -### Metric: `process.runtime.jvm.classes.current_loaded` - -This metric is [recommended](../metric-requirement-level.md#recommended). -This metric is obtained from [`ClassLoadingMXBean#getLoadedClassCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ClassLoadingMXBean.html#getLoadedClassCount--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.classes.current_loaded` | UpDownCounter | `{class}` | Number of classes currently loaded. | - - - - - -### Metric: `process.runtime.jvm.cpu.utilization` - -This metric is [recommended](../metric-requirement-level.md#recommended). -This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()) on HotSpot -and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getProcessCpuLoad--) on J9. - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the process. | - - - - - -### Metric: `process.runtime.jvm.system.cpu.utilization` - -This metric is [recommended](../metric-requirement-level.md#recommended). -This metric is obtained from [`com.sun.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getSystemCpuLoad()) on Java version 8..13, [`com.sun.management.OperatingSystemMXBean#getCpuLoad()`](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getCpuLoad()) on Java version 14+, -and [`com.ibm.lang.management.OperatingSystemMXBean#getSystemCpuLoad()`](https://www.ibm.com/docs/api/v1/content/SSYKE2_8.0.0/openj9/api/jdk8/jre/management/extension/com/ibm/lang/management/OperatingSystemMXBean.html#getSystemCpuLoad--) on J9. - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.system.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the whole system. | - - - - - -### Metric: `process.runtime.jvm.system.cpu.load_1m` - -This metric is [recommended](../metric-requirement-level.md#recommended). -This metric is obtained from [`OperatingSystemMXBean#getSystemLoadAverage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.system.cpu.load_1m` | Gauge | `1` | Average CPU load of the whole system for the last minute. | - - - - - -### Metric: `process.runtime.jvm.buffer.usage` - -This metric is [recommended](../metric-requirement-level.md#recommended). -This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getMemoryUsed--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.buffer.usage` | UpDownCounter | `By` | Measure of memory used by buffers. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `pool` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | - -**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). - - -### Metric: `process.runtime.jvm.buffer.limit` - -This metric is [recommended](../metric-requirement-level.md#recommended). -This metric is obtained from [`BufferPoolMXBean#getTotalCapacity()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getTotalCapacity--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.buffer.limit` | UpDownCounter | `By` | Measure of total memory capacity of buffers. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `pool` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | - -**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). - - -### Metric: `process.runtime.jvm.buffer.count` - -This metric is [recommended](../metric-requirement-level.md#recommended). -This metric is obtained from [`BufferPoolMXBean#getCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getCount--). - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `process.runtime.jvm.buffer.count` | UpDownCounter | `{buffer}` | Number of buffers in the pool. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `pool` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended | - -**[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()). - diff --git a/specification/metrics/semantic_conventions/system-metrics.md b/specification/metrics/semantic_conventions/system-metrics.md deleted file mode 100644 index fb257eeff15..00000000000 --- a/specification/metrics/semantic_conventions/system-metrics.md +++ /dev/null @@ -1,194 +0,0 @@ - - -# Semantic Conventions for System Metrics - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -This document describes instruments and attributes for common system level -metrics in OpenTelemetry. Consider the [general metric semantic -conventions](README.md#general-metric-semantic-conventions) when creating -instruments not explicitly defined in the specification. - - - - - -- [Metric Instruments](#metric-instruments) - * [`system.cpu.` - Processor metrics](#systemcpu---processor-metrics) - * [`system.memory.` - Memory metrics](#systemmemory---memory-metrics) - * [`system.paging.` - Paging/swap metrics](#systempaging---pagingswap-metrics) - * [`system.disk.` - Disk controller metrics](#systemdisk---disk-controller-metrics) - * [`system.filesystem.` - Filesystem metrics](#systemfilesystem---filesystem-metrics) - * [`system.network.` - Network metrics](#systemnetwork---network-metrics) - * [`system.processes.` - Aggregate system process metrics](#systemprocesses---aggregate-system-process-metrics) - * [`system.{os}.` - OS Specific System Metrics](#systemos---os-specific-system-metrics) - - - -## Metric Instruments - -### `system.cpu.` - Processor metrics - -**Description:** System level processor metrics. - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key(s) | Attribute Values | -| ---------------------- | -------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------- | ---------- | ---------------- | ----------------------------------- | -| system.cpu.time | | s | Counter | Double | state | idle, user, system, interrupt, etc. | -| | | | | | cpu | CPU number [0..n-1] | -| system.cpu.utilization | Difference in system.cpu.time since the last measurement, divided by the elapsed time and number of CPUs | 1 | Gauge | Double | state | idle, user, system, interrupt, etc. | -| | | | | | cpu | CPU number (0..n) | - -### `system.memory.` - Memory metrics - -**Description:** System level memory metrics. This does not include [paging/swap -memory](#systempaging---pagingswap-metrics). - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ------------------------- | ----------- | ----- | ------------------------------------------------- | ---------- | ------------- | ------------------------ | -| system.memory.usage | | By | UpDownCounter | Int64 | state | used, free, cached, etc. | -| system.memory.utilization | | 1 | Gauge | Double | state | used, free, cached, etc. | - -### `system.paging.` - Paging/swap metrics - -**Description:** System level paging/swap memory metrics. - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -|---------------------------|-------------------------------------|--------------|---------------------------------------------------|------------|---------------|------------------| -| system.paging.usage | Unix swap or windows pagefile usage | By | UpDownCounter | Int64 | state | used, free | -| system.paging.utilization | | 1 | Gauge | Double | state | used, free | -| system.paging.faults | | {fault} | Counter | Int64 | type | major, minor | -| system.paging.operations | | {operation} | Counter | Int64 | type | major, minor | -| | | | | | direction | in, out | - -### `system.disk.` - Disk controller metrics - -**Description:** System level disk performance metrics. - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -|--------------------------------------------|-------------------------------------------------|--------------|---------------------------------------------------|------------|---------------|------------------| -| system.disk.io | | By | Counter | Int64 | device | (identifier) | -| | | | | | direction | read, write | -| system.disk.operations | | {operation} | Counter | Int64 | device | (identifier) | -| | | | | | direction | read, write | -| system.disk.io_time\[1\] | Time disk spent activated | s | Counter | Double | device | (identifier) | -| system.disk.operation_time\[2\] | Sum of the time each operation took to complete | s | Counter | Double | device | (identifier) | -| | | | | | direction | read, write | -| system.disk.merged | | {operation} | Counter | Int64 | device | (identifier) | -| | | | | | direction | read, write | - -1 The real elapsed time ("wall clock") -used in the I/O path (time from operations running in parallel are not -counted). Measured as: - -- Linux: Field 13 from -[procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) -- Windows: The complement of ["Disk\% Idle -Time"](https://docs.microsoft.com/en-us/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained:~:text=%25%20Idle%20Time,Idle\)%20to%200%20(meaning%20always%20busy).) -performance counter: `uptime * (100 - "Disk\% Idle Time") / 100` - -2 Because it is the sum of time each -request took, parallel-issued requests each contribute to make the count -grow. Measured as: - -- Linux: Fields 7 & 11 from -[procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) -- Windows: "Avg. Disk sec/Read" perf counter multiplied by "Disk Reads/sec" -perf counter (similar for Writes) - -### `system.filesystem.` - Filesystem metrics - -**Description:** System level filesystem metrics. - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ----------------------------- | ----------- | ----- | ------------------------------------------------- | ---------- | ------------- | -------------------- | -| system.filesystem.usage | | By | UpDownCounter | Int64 | device | (identifier) | -| | | | | | state | used, free, reserved | -| | | | | | type | ext4, tmpfs, etc. | -| | | | | | mode | rw, ro, etc. | -| | | | | | mountpoint | (path) | -| system.filesystem.utilization | | 1 | Gauge | Double | device | (identifier) | -| | | | | | state | used, free, reserved | -| | | | | | type | ext4, tmpfs, etc. | -| | | | | | mode | rw, ro, etc. | -| | | | | | mountpoint | (path) | - -### `system.network.` - Network metrics - -**Description:** System level network metrics. - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -|----------------------------------------|-------------------------------------------------------------------------------|---------------|---------------------------------------------------|------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| system.network.dropped\[1\] | Count of packets that are dropped or discarded even though there was no error | {packet} | Counter | Int64 | device | (identifier) | -| | | | | | direction | transmit, receive | -| system.network.packets | | {packet} | Counter | Int64 | device | (identifier) | -| | | | | | direction | transmit, receive | -| system.network.errors\[2\] | Count of network errors detected | {error} | Counter | Int64 | device | (identifier) | -| | | | | | direction | transmit, receive | -| system.network.io | | By | Counter | Int64 | device | (identifier) | -| | | | | | direction | transmit, receive | -| system.network.connections | | {connection} | UpDownCounter | Int64 | device | (identifier) | -| | | | | | protocol | tcp, udp, [etc.](https://en.wikipedia.org/wiki/Transport_layer#Protocols) | -| | | | | | state | If specified, SHOULD be one of: close, close_wait, closing, delete, established, fin_wait_1, fin_wait_2, last_ack, listen, syn_recv, syn_sent, time_wait. A stateless protocol MUST NOT set this attribute. | - -1 Measured as: - -- Linux: the `drop` column in `/proc/dev/net` -([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)). -- Windows: -[`InDiscards`/`OutDiscards`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) -from -[`GetIfEntry2`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/nf-netioapi-getifentry2). - -2 Measured as: - -- Linux: the `errs` column in `/proc/dev/net` -([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)). -- Windows: -[`InErrors`/`OutErrors`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) -from -[`GetIfEntry2`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/nf-netioapi-getifentry2). - -### `system.processes.` - Aggregate system process metrics - -**Description:** System level aggregate process metrics. For metrics at the -individual process level, see [process metrics](process-metrics.md). - -| Name | Description | Units | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -| ------------------------ | --------------------------------------------------------- | ----------- | ------------------------------------------------- | ---------- | ------------- | ---------------------------------------------------------------------------------------------- | -| system.processes.count | Total number of processes in each state | {process} | UpDownCounter | Int64 | status | running, sleeping, [etc.](https://man7.org/linux/man-pages/man1/ps.1.html#PROCESS_STATE_CODES) | -| system.processes.created | Total number of processes created over uptime of the host | {process} | Counter | Int64 | - | - | - -### `system.{os}.` - OS Specific System Metrics - -Instrument names for system level metrics that have different and conflicting -meaning across multiple OSes should be prefixed with `system.{os}.` and -follow the hierarchies listed above for different entities like CPU, memory, -and network. - -For example, [UNIX load -average](https://en.wikipedia.org/wiki/Load_(computing)) over a given -interval is not well standardized and its value across different UNIX like -OSes may vary despite being under similar load: - -> Without getting into the vagaries of every Unix-like operating system in -existence, the load average more or less represents the average number of -processes that are in the running (using the CPU) or runnable (waiting for -the CPU) states. One notable exception exists: Linux includes processes in -uninterruptible sleep states, typically waiting for some I/O activity to -complete. This can markedly increase the load average on Linux systems. - -([source of -quote](https://github.com/torvalds/linux/blob/e4cbce4d131753eca271d9d67f58c6377f27ad21/kernel/sched/loadavg.c#L11-L18), -[linux source -code](https://github.com/torvalds/linux/blob/e4cbce4d131753eca271d9d67f58c6377f27ad21/kernel/sched/loadavg.c#L11-L18)) - -An instrument for load average over 1 minute on Linux could be named -`system.linux.cpu.load_1m`, reusing the `cpu` name proposed above and having -an `{os}` prefix to split this metric across OSes. diff --git a/specification/performance-benchmark.md b/specification/performance-benchmark.md index 2b651b1d540..c5886e6cca6 100644 --- a/specification/performance-benchmark.md +++ b/specification/performance-benchmark.md @@ -17,7 +17,7 @@ platform. - Associated to a [resource](overview.md#resources) with attributes `service.name`, `service.version` and 10 characters string value for each attribute, and attribute `service.instance.id` with a unique UUID. See - [Service](./resource/semantic_conventions/README.md#service) for details. + [Service](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#service) for details. - 1 [attribute](./common/README.md#attribute) with a signed 64-bit integer value. - 1 [event](./trace/api.md#add-events) without any attributes. diff --git a/specification/protocol/exporter.md b/specification/protocol/exporter.md index 30d601ce65d..495f86727af 100644 --- a/specification/protocol/exporter.md +++ b/specification/protocol/exporter.md @@ -189,7 +189,7 @@ OTel-OTLP-Exporter-Python/1.2.3 The format of the header SHOULD follow [RFC 7231][rfc-7231]. The conventions used for specifying the OpenTelemetry SDK language and version are available in the [Resource semantic conventions][resource-semconv]. -[resource-semconv]: ../resource/semantic_conventions/README.md#telemetry-sdk +[resource-semconv]: https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#telemetry-sdk [otlphttp-req]: https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md#otlphttp-request [rfc-7231]: https://datatracker.ietf.org/doc/html/rfc7231#section-5.5.3 [protocol-spec]: https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md diff --git a/specification/resource/sdk.md b/specification/resource/sdk.md index cc2a4b867f4..86e83ee215f 100644 --- a/specification/resource/sdk.md +++ b/specification/resource/sdk.md @@ -8,7 +8,7 @@ For example, a process producing telemetry that is running in a container on Kubernetes has a Pod name, it is in a namespace and possibly is part of a Deployment which also has a name. All three of these attributes can be included in the `Resource`. Note that there are certain -["standard attributes"](semantic_conventions/README.md) that have prescribed meanings. +["standard attributes"](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md) that have prescribed meanings. The primary purpose of resources as a first-class concept in the SDK is decoupling of discovery of resource information from exporters. This allows for @@ -31,7 +31,7 @@ associated with this `Resource`. ## SDK-provided resource attributes The SDK MUST provide access to a Resource with at least the attributes listed at -[Semantic Attributes with SDK-provided Default Value](semantic_conventions/README.md#semantic-attributes-with-sdk-provided-default-value). +[Semantic Attributes with SDK-provided Default Value](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#semantic-attributes-with-sdk-provided-default-value). This resource MUST be associated with a `TracerProvider` or `MeterProvider` if another resource was not explicitly specified. diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md deleted file mode 100644 index b8e62e84f0f..00000000000 --- a/specification/resource/semantic_conventions/README.md +++ /dev/null @@ -1,231 +0,0 @@ -# Resource Semantic Conventions - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Mixed](../../document-status.md) - -This document defines standard attributes for resources. These attributes are typically used in the [Resource](../sdk.md) and are also recommended to be used anywhere else where there is a need to describe a resource in a consistent manner. The majority of these attributes are inherited from -[OpenCensus Resource standard](https://github.com/census-instrumentation/opencensus-specs/blob/master/resource/StandardResources.md). - - - - - -- [TODOs](#todos) -- [Document Conventions](#document-conventions) -- [Attributes with Special Handling](#attributes-with-special-handling) - * [Semantic Attributes with Dedicated Environment Variable](#semantic-attributes-with-dedicated-environment-variable) -- [Semantic Attributes with SDK-provided Default Value](#semantic-attributes-with-sdk-provided-default-value) -- [Service](#service) -- [Service (Experimental)](#service-experimental) -- [Telemetry SDK](#telemetry-sdk) -- [Telemetry SDK (Experimental)](#telemetry-sdk-experimental) -- [Compute Unit](#compute-unit) -- [Compute Instance](#compute-instance) -- [Environment](#environment) -- [Version attributes](#version-attributes) -- [Cloud-Provider-Specific Attributes](#cloud-provider-specific-attributes) - - - -## TODOs - -* Add more compute units: AppEngine unit, etc. -* Add Web Browser. -* Decide if lower case strings only. -* Consider to add optional/required for each attribute and combination of attributes - (e.g when supplying a k8s resource all k8s may be required). - -## Document Conventions - -**Status**: [Stable](../../document-status.md) - -Attributes are grouped logically by the type of the concept that they described. Attributes in the same group have a common prefix that ends with a dot. For example all attributes that describe Kubernetes properties start with "k8s." - -See [Attribute Requirement Levels](../../common/attribute-requirement-level.md) for details on when attributes -should be included. - -## Attributes with Special Handling - -**Status**: [Stable](../../document-status.md) - -Given their significance some resource attributes are treated specifically as described below. - -### Semantic Attributes with Dedicated Environment Variable - -These are the attributes which MAY be configurable via a dedicated environment variable -as specified in [OpenTelemetry Environment Variable Specification](../../configuration/sdk-environment-variables.md): - -- [`service.name`](#service) - -## Semantic Attributes with SDK-provided Default Value - -These are the attributes which MUST be provided by the SDK -as specified in the [Resource SDK specification](../sdk.md#sdk-provided-resource-attributes): - -- [`service.name`](#service) -- [`telemetry.sdk` group](#telemetry-sdk) - -## Service - -**Status**: [Stable](../../document-status.md) - -**type:** `service` - -**Description:** A service instance. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `service.name` | string | Logical name of the service. [1] | `shoppingcart` | Required | - -**[1]:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md#process), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`. - - -## Service (Experimental) - -**Status**: [Experimental](../../document-status.md) - -**type:** `service` - -**Description:** Additions to service instance. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `service.namespace` | string | A namespace for `service.name`. [1] | `Shop` | Recommended | -| `service.instance.id` | string | The string ID of the service instance. [2] | `my-k8s-pod-deployment-1`; `627cc493-f310-47de-96bd-71410b7dec09` | Recommended | -| `service.version` | string | The version string of the service API or implementation. | `2.0.0` | Recommended | - -**[1]:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. - -**[2]:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words `service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled service). It is preferable for the ID to be persistent and stay the same for the lifetime of the service instance, however it is acceptable that the ID is ephemeral and changes during important lifetime events for the service (e.g. service restarts). If the service has no inherent unique ID that can be used as the value of this attribute it is recommended to generate a random Version 1 or Version 4 RFC 4122 UUID (services aiming for reproducible UUIDs may also use Version 5, see RFC 4122 for more recommendations). - - -Note: `service.namespace` and `service.name` are not intended to be concatenated for the purpose of forming a single globally unique name for the service. For example the following 2 sets of attributes actually describe 2 different services (despite the fact that the concatenation would result in the same string): - -``` -# Resource attributes that describes a service. -namespace = Company.Shop -service.name = shoppingcart -``` - -``` -# Another set of resource attributes that describe a different service. -namespace = Company -service.name = Shop.shoppingcart -``` - -## Telemetry SDK - -**Status**: [Stable](../../document-status.md) - -**type:** `telemetry.sdk` - -**Description:** The telemetry SDK used to capture data recorded by the instrumentation libraries. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. [1] | `opentelemetry` | Required | -| `telemetry.sdk.language` | string | The language of the telemetry SDK. | `cpp` | Required | -| `telemetry.sdk.version` | string | The version string of the telemetry SDK. | `1.2.3` | Required | - -**[1]:** 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. - -`telemetry.sdk.language` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. - -| Value | Description | -|---|---| -| `cpp` | cpp | -| `dotnet` | dotnet | -| `erlang` | erlang | -| `go` | go | -| `java` | java | -| `nodejs` | nodejs | -| `php` | php | -| `python` | python | -| `ruby` | ruby | -| `rust` | rust | -| `swift` | swift | -| `webjs` | webjs | - - -## Telemetry SDK (Experimental) - -**Status**: [Experimental](../../document-status.md) - -**type:** `telemetry.sdk` - -**Description:** Additions to the telemetry SDK. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `telemetry.auto.version` | string | The version string of the auto instrumentation agent, if used. | `1.2.3` | Recommended | - - -## Compute Unit - -**Status**: [Experimental](../../document-status.md) - -Attributes defining a compute unit (e.g. Container, Process, Function as a Service): - -- [Container](./container.md) -- [Function as a Service](./faas.md) -- [Process](./process.md) -- [Web engine](./webengine.md) - -## Compute Instance - -**Status**: [Experimental](../../document-status.md) - -Attributes defining a computing instance (e.g. host): - -- [Host](./host.md) - -## Environment - -**Status**: [Experimental](../../document-status.md) - -Attributes defining a running environment (e.g. Operating System, Cloud, Data Center, Deployment Service): - -- [Operating System](./os.md) -- [Device](./device.md) -- [Cloud](./cloud.md) -- Deployment: - - [Deployment Environment](./deployment_environment.md) - - [Kubernetes](./k8s.md) -- [Browser](./browser.md) - -## Version attributes - -**Status**: [Stable](../../document-status.md) - -Version attributes, such as `service.version`, are values of type `string`. They are -the exact version used to identify an artifact. This may be a semantic version, e.g., `1.2.3`, git hash, e.g., -`8ae73a`, or an arbitrary version string, e.g., `0.1.2.20210101`, whatever was used when building the artifact. - -## Cloud-Provider-Specific Attributes - -**Status**: [Experimental](../../document-status.md) - -Attributes that are only applicable to resources from a specific cloud provider. Currently, these -resources can only be defined for providers listed as a valid `cloud.provider` in -[Cloud](./cloud.md) and below. Provider-specific attributes all reside in the `cloud_provider` directory. -Valid cloud providers are: - -- [Alibaba Cloud](https://www.alibabacloud.com/) (`alibaba_cloud`) -- [Amazon Web Services](https://aws.amazon.com/) ([`aws`](cloud_provider/aws/README.md)) -- [Google Cloud Platform](https://cloud.google.com/) ([`gcp`](cloud_provider/gcp/README.md)) -- [Microsoft Azure](https://azure.microsoft.com/) (`azure`) -- [Tencent Cloud](https://www.tencentcloud.com/) (`tencent_cloud`) -- [Heroku dyno](./cloud_provider/heroku.md) diff --git a/specification/resource/semantic_conventions/browser.md b/specification/resource/semantic_conventions/browser.md deleted file mode 100644 index 0c1b762ba1e..00000000000 --- a/specification/resource/semantic_conventions/browser.md +++ /dev/null @@ -1,35 +0,0 @@ -# Browser - -**Status**: [Experimental](../../document-status.md) - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**type:** `browser` - -**Description**: The web browser in which the application represented by the resource is running. The `browser.*` attributes MUST be used only for resources that represent applications running in a web browser (regardless of whether running on a mobile or desktop device). - -All of these attributes can be provided by the user agent itself in the form of an HTTP header (e.g. Sec-CH-UA, Sec-CH-Platform, User-Agent). However, the headers could be removed by proxy servers, and are tied to calls from individual clients. In order to support batching through services like the Collector and to prevent loss of data (e.g. due to proxy servers removing headers), these attributes should be used when possible. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `browser.brands` | string[] | Array of brand name and version separated by a space [1] | `[ Not A;Brand 99, Chromium 99, Chrome 99]` | Recommended | -| `browser.platform` | string | The platform on which the browser is running [2] | `Windows`; `macOS`; `Android` | Recommended | -| `browser.mobile` | boolean | A boolean that is true if the browser is running on a mobile device [3] | | Recommended | -| `browser.language` | string | Preferred language of the user using the browser [4] | `en`; `en-US`; `fr`; `fr-FR` | Recommended | -| `user_agent.original` | string | Full user-agent string provided by the browser [5] | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36` | Recommended | - -**[1]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.brands`). - -**[2]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent. -The list of possible values is defined in the [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). Note that some (but not all) of these values can overlap with values in the [`os.type` and `os.name` attributes](./os.md). However, for consistency, the values in the `browser.platform` attribute should capture the exact value that the user agent provides. - -**[3]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.mobile`). If unavailable, this attribute SHOULD be left unset. - -**[4]:** This value is intended to be taken from the Navigator API `navigator.language`. - -**[5]:** The user-agent value SHOULD be provided only from browsers that do not have a mechanism to retrieve brands and platform individually from the User-Agent Client Hints API. To retrieve the value, the legacy `navigator.userAgent` API can be used. - diff --git a/specification/resource/semantic_conventions/cloud.md b/specification/resource/semantic_conventions/cloud.md deleted file mode 100644 index a5cca57c723..00000000000 --- a/specification/resource/semantic_conventions/cloud.md +++ /dev/null @@ -1,90 +0,0 @@ -# Cloud - -**Status**: [Experimental](../../document-status.md) - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**type:** `cloud` - -**Description:** A cloud infrastructure (e.g. GCP, Azure, AWS). - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `cloud.provider` | string | Name of the cloud provider. | `alibaba_cloud` | Recommended | -| `cloud.account.id` | string | The cloud account ID the resource is assigned to. | `111111111111`; `opentelemetry` | Recommended | -| `cloud.region` | string | The geographical region the resource is running. [1] | `us-central1`; `us-east-1` | Recommended | -| `cloud.resource_id` | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [2] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | Recommended | -| `cloud.availability_zone` | string | Cloud regions often have multiple, isolated locations known as zones to increase availability. Availability zone represents the zone where the resource is running. [3] | `us-east-1c` | Recommended | -| `cloud.platform` | string | The cloud platform in use. [4] | `alibaba_cloud_ecs` | Recommended | - -**[1]:** Refer to your provider's docs to see the available regions, for example [Alibaba Cloud regions](https://www.alibabacloud.com/help/doc-detail/40654.htm), [AWS regions](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/), [Azure regions](https://azure.microsoft.com/en-us/global-infrastructure/geographies/), [Google Cloud regions](https://cloud.google.com/about/locations), or [Tencent Cloud regions](https://www.tencentcloud.com/document/product/213/6091). - -**[2]:** On some cloud providers, it may not be possible to determine the full ID at startup, -so it may be necessary to set `cloud.resource_id` as a span attribute instead. - -The exact value to use for `cloud.resource_id` depends on the cloud provider. -The following well-known definitions MUST be used if you set this attribute and they apply: - -* **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html). - Take care not to use the "invoked ARN" directly but replace any - [alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) - with the resolved function version, as the same runtime instance may be invokable with - multiple different aliases. -* **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names) -* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/en-us/rest/api/resources/resources/get-by-id) of the invoked function, - *not* the function app, having the form - `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/`. - This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share - a TracerProvider. - -**[3]:** Availability zones are called "zones" on Alibaba Cloud and Google Cloud. - -**[4]:** The prefix of the service SHOULD match the one specified in `cloud.provider`. - -`cloud.provider` 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 | -|---|---| -| `alibaba_cloud` | Alibaba Cloud | -| `aws` | Amazon Web Services | -| `azure` | Microsoft Azure | -| `gcp` | Google Cloud Platform | -| `heroku` | Heroku Platform as a Service | -| `ibm_cloud` | IBM Cloud | -| `tencent_cloud` | Tencent Cloud | - -`cloud.platform` 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 | -|---|---| -| `alibaba_cloud_ecs` | Alibaba Cloud Elastic Compute Service | -| `alibaba_cloud_fc` | Alibaba Cloud Function Compute | -| `alibaba_cloud_openshift` | Red Hat OpenShift on Alibaba Cloud | -| `aws_ec2` | AWS Elastic Compute Cloud | -| `aws_ecs` | AWS Elastic Container Service | -| `aws_eks` | AWS Elastic Kubernetes Service | -| `aws_lambda` | AWS Lambda | -| `aws_elastic_beanstalk` | AWS Elastic Beanstalk | -| `aws_app_runner` | AWS App Runner | -| `aws_openshift` | Red Hat OpenShift on AWS (ROSA) | -| `azure_vm` | Azure Virtual Machines | -| `azure_container_instances` | Azure Container Instances | -| `azure_aks` | Azure Kubernetes Service | -| `azure_functions` | Azure Functions | -| `azure_app_service` | Azure App Service | -| `azure_openshift` | Azure Red Hat OpenShift | -| `gcp_compute_engine` | Google Cloud Compute Engine (GCE) | -| `gcp_cloud_run` | Google Cloud Run | -| `gcp_kubernetes_engine` | Google Cloud Kubernetes Engine (GKE) | -| `gcp_cloud_functions` | Google Cloud Functions (GCF) | -| `gcp_app_engine` | Google Cloud App Engine (GAE) | -| `gcp_openshift` | Red Hat OpenShift on Google Cloud | -| `ibm_cloud_openshift` | Red Hat OpenShift on IBM Cloud | -| `tencent_cloud_cvm` | Tencent Cloud Cloud Virtual Machine (CVM) | -| `tencent_cloud_eks` | Tencent Cloud Elastic Kubernetes Service (EKS) | -| `tencent_cloud_scf` | Tencent Cloud Serverless Cloud Function (SCF) | - diff --git a/specification/resource/semantic_conventions/cloud_provider/aws/README.md b/specification/resource/semantic_conventions/cloud_provider/aws/README.md deleted file mode 100644 index da14c6a472d..00000000000 --- a/specification/resource/semantic_conventions/cloud_provider/aws/README.md +++ /dev/null @@ -1,27 +0,0 @@ -# AWS Semantic Conventions - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../../../document-status.md) - -This directory defines standards for resource attributes that only apply to Amazon -Web Services (AWS) resources. If an attribute could apply to resources from more than one cloud -provider (like account ID, operating system, etc), it belongs in the parent -`semantic_conventions` directory. - -## Generic AWS Attributes - -Attributes that relate to AWS or use AWS-specific terminology, but are used by several -services within AWS or are abstracted away from any particular service: - -- [AWS Logs](./logs.md) - -## Services - -Attributes that relate to an individual AWS service: - -- [Elastic Container Service (ECS)](./ecs.md) -- [Elastic Kubernetes Service (EKS)](./eks.md) diff --git a/specification/resource/semantic_conventions/cloud_provider/aws/ecs.md b/specification/resource/semantic_conventions/cloud_provider/aws/ecs.md deleted file mode 100644 index 19d24731431..00000000000 --- a/specification/resource/semantic_conventions/cloud_provider/aws/ecs.md +++ /dev/null @@ -1,30 +0,0 @@ -# AWS ECS - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../../../document-status.md) - -**type:** `aws.ecs` - -**Description:** Resources used by AWS Elastic Container Service (ECS). - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.ecs.container.arn` | string | The Amazon Resource Name (ARN) of an [ECS container instance](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_instances.html). | `arn:aws:ecs:us-west-1:123456789123:container/32624152-9086-4f0e-acae-1a75b14fe4d9` | Recommended | -| `aws.ecs.cluster.arn` | string | The ARN of an [ECS cluster](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/clusters.html). | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | Recommended | -| `aws.ecs.launchtype` | string | The [launch type](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/launch_types.html) for an ECS task. | `ec2` | Recommended | -| `aws.ecs.task.arn` | string | The ARN of an [ECS task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html). | `arn:aws:ecs:us-west-1:123456789123:task/10838bed-421f-43ef-870a-f43feacbbb5b` | Recommended | -| `aws.ecs.task.family` | string | The task definition family this task definition is a member of. | `opentelemetry-family` | Recommended | -| `aws.ecs.task.revision` | string | The revision for this task definition. | `8`; `26` | Recommended | - -`aws.ecs.launchtype` MUST be one of the following: - -| Value | Description | -|---|---| -| `ec2` | ec2 | -| `fargate` | fargate | - diff --git a/specification/resource/semantic_conventions/cloud_provider/aws/eks.md b/specification/resource/semantic_conventions/cloud_provider/aws/eks.md deleted file mode 100644 index 85ba84e97e0..00000000000 --- a/specification/resource/semantic_conventions/cloud_provider/aws/eks.md +++ /dev/null @@ -1,18 +0,0 @@ -# AWS EKS - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../../../document-status.md) - -**type:** `aws.eks` - -**Description:** Resources used by AWS Elastic Kubernetes Service (EKS). - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.eks.cluster.arn` | string | The ARN of an EKS cluster. | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | Recommended | - diff --git a/specification/resource/semantic_conventions/cloud_provider/aws/logs.md b/specification/resource/semantic_conventions/cloud_provider/aws/logs.md deleted file mode 100644 index bcc36f5cb6b..00000000000 --- a/specification/resource/semantic_conventions/cloud_provider/aws/logs.md +++ /dev/null @@ -1,27 +0,0 @@ -# AWS Logs - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../../../document-status.md) - -**Type:** `aws.log` - -**Description:** Log attributes for Amazon Web Services. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.log.group.names` | string[] | The name(s) of the AWS log group(s) an application is writing to. [1] | `[/aws/lambda/my-function, opentelemetry-service]` | Recommended | -| `aws.log.group.arns` | string[] | The Amazon Resource Name(s) (ARN) of the AWS log group(s). [2] | `[arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:*]` | Recommended | -| `aws.log.stream.names` | string[] | The name(s) of the AWS log stream(s) an application is writing to. | `[logs/main/10838bed-421f-43ef-870a-f43feacbbb5b]` | Recommended | -| `aws.log.stream.arns` | string[] | The ARN(s) of the AWS log stream(s). [3] | `[arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:log-stream:logs/main/10838bed-421f-43ef-870a-f43feacbbb5b]` | Recommended | - -**[1]:** Multiple log groups must be supported for cases like multi-container applications, where a single application has sidecar containers, and each write to their own log group. - -**[2]:** See the [log group ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). - -**[3]:** See the [log stream ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). One log group can contain several log streams, so these ARNs necessarily identify both a log group and a log stream. - diff --git a/specification/resource/semantic_conventions/cloud_provider/gcp/README.md b/specification/resource/semantic_conventions/cloud_provider/gcp/README.md deleted file mode 100644 index 720cb6445d4..00000000000 --- a/specification/resource/semantic_conventions/cloud_provider/gcp/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# GCP Semantic Conventions - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -This directory defines standards for resource attributes that only apply to -Google Cloud Platform (GCP). If an attribute could apply to resources from more than one cloud -provider (like account ID, operating system, etc), it belongs in the parent -`semantic_conventions` directory. - -## Services - -- [Cloud Run](./cloud_run.md) diff --git a/specification/resource/semantic_conventions/cloud_provider/gcp/cloud_run.md b/specification/resource/semantic_conventions/cloud_provider/gcp/cloud_run.md deleted file mode 100644 index f110d7d72e6..00000000000 --- a/specification/resource/semantic_conventions/cloud_provider/gcp/cloud_run.md +++ /dev/null @@ -1,19 +0,0 @@ -# Google Cloud Run - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -These conventions are recommended for resources running on Cloud Run. - -**Type:** `gcp.cloud_run` - -**Description:** Resource attributes for GCE instances. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `gcp.cloud_run.job.execution` | string | The name of the Cloud Run [execution](https://cloud.google.com/run/docs/managing/job-executions) being run for the Job, as set by the [`CLOUD_RUN_EXECUTION`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) environment variable. | `job-name-xxxx`; `sample-job-mdw84` | Recommended | -| `gcp.cloud_run.job.task_index` | int | The index for a task within an execution as provided by the [`CLOUD_RUN_TASK_INDEX`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) environment variable. | `0`; `1` | Recommended | - diff --git a/specification/resource/semantic_conventions/cloud_provider/heroku.md b/specification/resource/semantic_conventions/cloud_provider/heroku.md deleted file mode 100644 index 5f8761d9a18..00000000000 --- a/specification/resource/semantic_conventions/cloud_provider/heroku.md +++ /dev/null @@ -1,35 +0,0 @@ -# Heroku - -**Status**: [Experimental](../../../document-status.md) - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**type:** `heroku` - -**Description:** [Heroku dyno metadata] - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `heroku.release.creation_timestamp` | string | Time and date the release was created | `2022-10-23T18:00:42Z` | Opt-In | -| `heroku.release.commit` | string | Commit hash for the current release | `e6134959463efd8966b20e75b913cafe3f5ec` | Opt-In | -| `heroku.app.id` | string | Unique identifier for the application | `2daa2797-e42b-4624-9322-ec3f968df4da` | Opt-In | - - -**Mapping:** - -| Dyno metadata environment variable | Resource attribute | -|------------------------------------|-------------------------------------| -| `HEROKU_APP_ID` | `heroku.app.id` | -| `HEROKU_APP_NAME` | `service.name` | -| `HEROKU_DYNO_ID` | `service.instance.id` | -| `HEROKU_RELEASE_CREATED_AT` | `heroku.release.creation_timestamp` | -| `HEROKU_RELEASE_VERSION` | `service.version` | -| `HEROKU_SLUG_COMMIT` | `heroku.release.commit` | - -Additionally, [the `cloud.provider` resource attribute MUST be set to `heroku`](../cloud.md). - -[Heroku dyno metadata]: https://devcenter.heroku.com/articles/dyno-metadata diff --git a/specification/resource/semantic_conventions/container.md b/specification/resource/semantic_conventions/container.md deleted file mode 100644 index 1746e63dbb5..00000000000 --- a/specification/resource/semantic_conventions/container.md +++ /dev/null @@ -1,22 +0,0 @@ -# Container - -**Status**: [Experimental](../../document-status.md) - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**type:** `container` - -**Description:** A container instance. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `container.name` | string | Container name used by container runtime. | `opentelemetry-autoconf` | Recommended | -| `container.id` | string | Container ID. Usually a UUID, as for example used to [identify Docker containers](https://docs.docker.com/engine/reference/run/#container-identification). The UUID might be abbreviated. | `a3bf90e006b2` | Recommended | -| `container.runtime` | string | The container runtime managing this container. | `docker`; `containerd`; `rkt` | Recommended | -| `container.image.name` | string | Name of the image the container was built on. | `gcr.io/opentelemetry/operator` | Recommended | -| `container.image.tag` | string | Container image tag. | `0.1` | Recommended | - diff --git a/specification/resource/semantic_conventions/deployment_environment.md b/specification/resource/semantic_conventions/deployment_environment.md deleted file mode 100644 index b7284161f06..00000000000 --- a/specification/resource/semantic_conventions/deployment_environment.md +++ /dev/null @@ -1,18 +0,0 @@ -# Deployment - -**Status**: [Experimental](../../document-status.md) - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**type:** `deployment` - -**Description:** The software deployment. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `deployment.environment` | string | Name of the [deployment environment](https://en.wikipedia.org/wiki/Deployment_environment) (aka deployment tier). | `staging`; `production` | Recommended | - diff --git a/specification/resource/semantic_conventions/device.md b/specification/resource/semantic_conventions/device.md deleted file mode 100644 index c6421fe0684..00000000000 --- a/specification/resource/semantic_conventions/device.md +++ /dev/null @@ -1,29 +0,0 @@ -# Device - -**Status**: [Experimental](../../document-status.md) - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**type:** `device` - -**Description**: The device on which the process represented by this resource is running. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `device.id` | string | A unique identifier representing the device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | Recommended | -| `device.model.identifier` | string | The model identifier for the device [2] | `iPhone3,4`; `SM-G920F` | Recommended | -| `device.model.name` | string | The marketing name for the device model [3] | `iPhone 6s Plus`; `Samsung Galaxy S6` | Recommended | -| `device.manufacturer` | string | The name of the device manufacturer [4] | `Apple`; `Samsung` | Recommended | - -**[1]:** The device identifier MUST only be defined using the values outlined below. This value is not an advertising identifier and MUST NOT be used as such. On iOS (Swift or Objective-C), this value MUST be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor). On Android (Java or Kotlin), this value MUST be equal to the Firebase Installation ID or a globally unique UUID which is persisted across sessions in your application. More information can be found [here](https://developer.android.com/training/articles/user-data-ids) on best practices and exact implementation details. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence. - -**[2]:** It's recommended this value represents a machine readable version of the model identifier rather than the market or consumer-friendly name of the device. - -**[3]:** It's recommended this value represents a human readable version of the device model rather than a machine readable alternative. - -**[4]:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`. - diff --git a/specification/resource/semantic_conventions/faas.md b/specification/resource/semantic_conventions/faas.md deleted file mode 100644 index 90a245074db..00000000000 --- a/specification/resource/semantic_conventions/faas.md +++ /dev/null @@ -1,86 +0,0 @@ -# Function as a Service - -**Status**: [Experimental](../../document-status.md) - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**type:** `faas` - -**Description:** A "function as a service" aka "serverless function" instance. - -See also: - -- The [Trace semantic conventions for FaaS](../../trace/semantic_conventions/faas.md) -- The [Cloud resource conventions](cloud.md) - -## FaaS resource attributes - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `faas.name` | string | The name of the single function that this runtime instance executes. [1] | `my-function`; `myazurefunctionapp/some-function-name` | Required | -| `faas.version` | string | The immutable version of the function being executed. [2] | `26`; `pinkfroid-00002` | Recommended | -| `faas.instance` | string | The execution environment ID as a string, that will be potentially reused for other invocations to the same function/function version. [3] | `2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de` | Recommended | -| `faas.max_memory` | int | The amount of memory available to the serverless function converted to Bytes. [4] | `134217728` | Recommended | -| [`cloud.resource_id`](cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [5] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | Recommended | - -**[1]:** This is the name of the function as configured/deployed on the FaaS -platform and is usually different from the name of the callback -function (which may be stored in the -[`code.namespace`/`code.function`](../../trace/semantic_conventions/span-general.md#source-code-attributes) -span attributes). - -For some cloud providers, the above definition is ambiguous. The following -definition of function name MUST be used for this attribute -(and consequently the span name) for the listed cloud providers/products: - -* **Azure:** The full name `/`, i.e., function app name - followed by a forward slash followed by the function name (this form - can also be seen in the resource JSON for the function). - This means that a span attribute MUST be used, as an Azure function - app can host multiple functions that would usually share - a TracerProvider (see also the `cloud.resource_id` attribute). - -**[2]:** Depending on the cloud provider and platform, use: - -* **AWS Lambda:** The [function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html) - (an integer represented as a decimal string). -* **Google Cloud Run (Services):** The [revision](https://cloud.google.com/run/docs/managing/revisions) - (i.e., the function name plus the revision suffix). -* **Google Cloud Functions:** The value of the - [`K_REVISION` environment variable](https://cloud.google.com/functions/docs/env-var#runtime_environment_variables_set_automatically). -* **Azure Functions:** Not applicable. Do not set this attribute. - -**[3]:** * **AWS Lambda:** Use the (full) log stream name. - -**[4]:** It's recommended to set this attribute since e.g. too little memory can easily stop a Java AWS Lambda function from working correctly. On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` provides this information (which must be multiplied by 1,048,576). - -**[5]:** On some cloud providers, it may not be possible to determine the full ID at startup, -so it may be necessary to set `cloud.resource_id` as a span attribute instead. - -The exact value to use for `cloud.resource_id` depends on the cloud provider. -The following well-known definitions MUST be used if you set this attribute and they apply: - -* **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html). - Take care not to use the "invoked ARN" directly but replace any - [alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) - with the resolved function version, as the same runtime instance may be invokable with - multiple different aliases. -* **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names) -* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/en-us/rest/api/resources/resources/get-by-id) of the invoked function, - *not* the function app, having the form - `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/`. - This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share - a TracerProvider. - - -Note: The resource attribute `faas.instance` differs from the span attribute `faas.invocation_id`. For more information see the [Semantic conventions for FaaS spans](../../trace/semantic_conventions/faas.md#difference-between-invocation-and-instance). - -## Using span attributes instead of resource attributes - -There are cases where a FaaS resource attribute is better applied as a span -attribute instead. -See the [FaaS trace conventions](../../trace/semantic_conventions/faas.md) for more. diff --git a/specification/resource/semantic_conventions/host.md b/specification/resource/semantic_conventions/host.md deleted file mode 100644 index 0bbc2622f04..00000000000 --- a/specification/resource/semantic_conventions/host.md +++ /dev/null @@ -1,63 +0,0 @@ -# Host - -**Status**: [Experimental](../../document-status.md) - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**type:** `host` - -**Description:** A host is defined as a computing instance. For example, physical servers, virtual machines, switches or disk array. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `host.id` | string | Unique host ID. For Cloud, this must be the instance_id assigned by the cloud provider. For non-containerized systems, this should be the `machine-id`. See the table below for the sources to use to determine the `machine-id` based on operating system. | `fdbf79e8af94cb7f9e8df36789187052` | Recommended | -| `host.name` | string | Name of the host. On Unix systems, it may contain what the hostname command returns, or the fully qualified hostname, or another name specified by the user. | `opentelemetry-test` | Recommended | -| `host.type` | string | Type of host. For Cloud, this must be the machine type. | `n1-standard-1` | Recommended | -| `host.arch` | string | The CPU architecture the host system is running on. | `amd64` | Recommended | -| `host.image.name` | string | Name of the VM image or OS install the host was instantiated from. | `infra-ami-eks-worker-node-7d4ec78312`; `CentOS-8-x86_64-1905` | Recommended | -| `host.image.id` | string | VM image ID or host OS image ID. For Cloud, this value is from the provider. | `ami-07b06b442921831e5` | Recommended | -| `host.image.version` | string | The version string of the VM image or host OS as defined in [Version Attributes](README.md#version-attributes). | `0.1` | Recommended | - -`host.arch` 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 | -|---|---| -| `amd64` | AMD64 | -| `arm32` | ARM32 | -| `arm64` | ARM64 | -| `ia64` | Itanium | -| `ppc32` | 32-bit PowerPC | -| `ppc64` | 64-bit PowerPC | -| `s390x` | IBM z/Architecture | -| `x86` | 32-bit x86 | - - -## Collecting host.id from non-containerized systems - -### Non-privileged Machine ID Lookup - -When collecting `host.id` for non-containerized systems non-privileged lookups -of the machine id are preferred. SDK detector implementations MUST use the -sources listed below to obtain the machine id. - -| OS | Primary | Fallback | -|---------|-------------------------------------------------------------------------------------|----------------------------------------| -| Linux | contents of `/etc/machine-id` | contents of `/var/lib/dbus/machine-id` | -| BSD | contents of `/etc/hostid` | output of `kenv -q smbios.system.uuid` | -| MacOS | `IOPlatformUUID` line from the output of `ioreg -rd1 -c "IOPlatformExpertDevice"` | - | -| Windows | `MachineGuid` from registry `HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Cryptography` | - | - -### Privileged Machine ID Lookup - -The `host.id` can be looked up using privileged sources. For example, Linux -systems can use the output of `dmidecode -t system`, `dmidecode -t baseboard`, -`dmidecode -t chassis`, or read the corresponding data from the filesystem -(e.g. `cat /sys/devices/virtual/dmi/id/product_id`, -`cat /sys/devices/virtual/dmi/id/product_uuid`, etc), however, SDK resource -detector implementations MUST not collect `host.id` from privileged sources. If -privileged lookup of `host.id` is required, the value should be injected via the -`OTEL_RESOURCE_ATTRIBUTES` environment variable. diff --git a/specification/resource/semantic_conventions/k8s.md b/specification/resource/semantic_conventions/k8s.md deleted file mode 100644 index 67c346a2f25..00000000000 --- a/specification/resource/semantic_conventions/k8s.md +++ /dev/null @@ -1,216 +0,0 @@ -# Kubernetes - -**Status**: [Experimental](../../document-status.md) - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -Useful resources to understand Kubernetes objects and metadata: - -* [Namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) -* [Names and UIDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/). -* [Pods](https://kubernetes.io/docs/concepts/workloads/pods/) -* [Controllers](https://kubernetes.io/docs/concepts/workloads/controllers/) - -The "name" of a Kubernetes object is unique for that type of object within a -"namespace" and only at a specific moment of time (names can be reused over -time). The "uid" is unique across your whole cluster, and very likely across -time. Because of this it is recommended to always set the UID for every -Kubernetes object, but "name" is usually more user friendly so can be also set. - -## Cluster - -**type:** `k8s.cluster` - -**Description:** A Kubernetes Cluster. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.cluster.name` | string | The name of the cluster. | `opentelemetry-cluster` | Recommended | -| `k8s.cluster.uid` | string | A pseudo-ID for the cluster, set to the UID of the `kube-system` namespace. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | Recommended | - -**[1]:** K8s does not have support for obtaining a cluster ID. If this is ever -added, we will recommend collecting the `k8s.cluster.uid` through the -official APIs. In the meantime, we are able to use the `uid` of the -`kube-system` namespace as a proxy for cluster ID. Read on for the -rationale. - -Every object created in a K8s cluster is assigned a distinct UID. The -`kube-system` namespace is used by Kubernetes itself and will exist -for the lifetime of the cluster. Using the `uid` of the `kube-system` -namespace is a reasonable proxy for the K8s ClusterID as it will only -change if the cluster is rebuilt. Furthermore, Kubernetes UIDs are -UUIDs as standardized by -[ISO/IEC 9834-8 and ITU-T X.667](https://www.itu.int/ITU-T/studygroups/com17/oid.html). -Which states: - -> If generated according to one of the mechanisms defined in Rec. - ITU-T X.667 | ISO/IEC 9834-8, a UUID is either guaranteed to be - different from all other UUIDs generated before 3603 A.D., or is - extremely likely to be different (depending on the mechanism chosen). - -Therefore, UIDs between clusters should be extremely unlikely to -conflict. - - -## Node - -**type:** `k8s.node` - -**Description:** A Kubernetes Node. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.node.name` | string | The name of the Node. | `node-1` | Recommended | -| `k8s.node.uid` | string | The UID of the Node. | `1eb3a0c6-0477-4080-a9cb-0cb7db65c6a2` | Recommended | - - -## Namespace - -Namespaces provide a scope for names. Names of objects need to be unique within -a namespace, but not across namespaces. - -**type:** `k8s.namespace` - -**Description:** A Kubernetes Namespace. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.namespace.name` | string | The name of the namespace that the pod is running in. | `default` | Recommended | - - -## Pod - -The smallest and simplest Kubernetes object. A Pod represents a set of running -containers on your cluster. - -**type:** `k8s.pod` - -**Description:** A Kubernetes Pod object. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.pod.uid` | string | The UID of the Pod. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | -| `k8s.pod.name` | string | The name of the Pod. | `opentelemetry-pod-autoconf` | Recommended | - - -## Container - -A container specification in a Pod template. This type is intended to be used to -capture information such as name of a container in a Pod template which is different -from the name of the running container. - -Note: This type is different from [container](./container.md), which corresponds -to a running container. - -**type:** `k8s.container` - -**Description:** A container in a [PodTemplate](https://kubernetes.io/docs/concepts/workloads/pods/#pod-templates). - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.container.name` | string | The name of the Container from Pod specification, must be unique within a Pod. Container runtime usually uses different globally unique name (`container.name`). | `redis` | Recommended | -| `k8s.container.restart_count` | int | Number of times the container was restarted. This attribute can be used to identify a particular container (running or stopped) within a container spec. | `0`; `2` | Recommended | - - -## ReplicaSet - -A ReplicaSet’s purpose is to maintain a stable set of replica Pods running at -any given time. - -**type:** `k8s.replicaset` - -**Description:** A Kubernetes ReplicaSet object. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.replicaset.uid` | string | The UID of the ReplicaSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | -| `k8s.replicaset.name` | string | The name of the ReplicaSet. | `opentelemetry` | Recommended | - - -## Deployment - -An API object that manages a replicated application, typically by running Pods -with no local state. Each replica is represented by a Pod, and the Pods are -distributed among the nodes of a cluster. - -**type:** `k8s.deployment` - -**Description:** A Kubernetes Deployment object. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.deployment.uid` | string | The UID of the Deployment. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | -| `k8s.deployment.name` | string | The name of the Deployment. | `opentelemetry` | Recommended | - - -## StatefulSet - -Manages the deployment and scaling of a set of Pods, and provides guarantees -about the ordering and uniqueness of these Pods. - -**type:** `k8s.statefulset` - -**Description:** A Kubernetes StatefulSet object. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.statefulset.uid` | string | The UID of the StatefulSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | -| `k8s.statefulset.name` | string | The name of the StatefulSet. | `opentelemetry` | Recommended | - - -## DaemonSet - -A DaemonSet ensures that all (or some) Nodes run a copy of a Pod. - -**type:** `k8s.daemonset` - -**Description:** A Kubernetes DaemonSet object. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.daemonset.uid` | string | The UID of the DaemonSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | -| `k8s.daemonset.name` | string | The name of the DaemonSet. | `opentelemetry` | Recommended | - - -## Job - -A Job creates one or more Pods and ensures that a specified number of them -successfully terminate. - -**type:** `k8s.job` - -**Description:** A Kubernetes Job object. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.job.uid` | string | The UID of the Job. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | -| `k8s.job.name` | string | The name of the Job. | `opentelemetry` | Recommended | - - -## CronJob - -A CronJob creates Jobs on a repeating schedule. - -**type:** `k8s.cronjob` - -**Description:** A Kubernetes CronJob object. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `k8s.cronjob.uid` | string | The UID of the CronJob. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | -| `k8s.cronjob.name` | string | The name of the CronJob. | `opentelemetry` | Recommended | - diff --git a/specification/resource/semantic_conventions/os.md b/specification/resource/semantic_conventions/os.md deleted file mode 100644 index 4ca67cf1dce..00000000000 --- a/specification/resource/semantic_conventions/os.md +++ /dev/null @@ -1,39 +0,0 @@ -# Operating System - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -**type:** `os` - -**Description**: The operating system (OS) on which the process represented by this resource is running. - -In case of virtualized environments, this is the operating system as it is observed by the process, i.e., the virtualized guest rather than the underlying host. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `os.type` | string | The operating system type. | `windows` | Required | -| `os.description` | string | Human readable (not intended to be parsed) OS version information, like e.g. reported by `ver` or `lsb_release -a` commands. | `Microsoft Windows [Version 10.0.18363.778]`; `Ubuntu 18.04.1 LTS` | Recommended | -| `os.name` | string | Human readable operating system name. | `iOS`; `Android`; `Ubuntu` | Recommended | -| `os.version` | string | The version string of the operating system as defined in [Version Attributes](../../resource/semantic_conventions/README.md#version-attributes). | `14.2.1`; `18.04.1` | Recommended | - -`os.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 | -|---|---| -| `windows` | Microsoft Windows | -| `linux` | Linux | -| `darwin` | Apple Darwin | -| `freebsd` | FreeBSD | -| `netbsd` | NetBSD | -| `openbsd` | OpenBSD | -| `dragonflybsd` | DragonFly BSD | -| `hpux` | HP-UX (Hewlett Packard Unix) | -| `aix` | AIX (Advanced Interactive eXecutive) | -| `solaris` | SunOS, Oracle Solaris | -| `z_os` | IBM z/OS | - \ No newline at end of file diff --git a/specification/resource/semantic_conventions/process.md b/specification/resource/semantic_conventions/process.md deleted file mode 100644 index 21e90bc8f93..00000000000 --- a/specification/resource/semantic_conventions/process.md +++ /dev/null @@ -1,226 +0,0 @@ -# Process and process runtime resources - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - - - - - -- [Process](#process) -- [Process runtimes](#process-runtimes) - * [Erlang Runtimes](#erlang-runtimes) - * [Go Runtimes](#go-runtimes) - * [Java runtimes](#java-runtimes) - * [JavaScript runtimes](#javascript-runtimes) - * [.NET Runtimes](#net-runtimes) - * [Python Runtimes](#python-runtimes) - * [Ruby Runtimes](#ruby-runtimes) - - - -## Process - -**type:** `process` - -**Description:** An operating system process. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `process.pid` | int | Process identifier (PID). | `1234` | Recommended | -| `process.parent_pid` | int | Parent Process identifier (PID). | `111` | Recommended | -| `process.executable.name` | string | The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | Conditionally Required: See alternative attributes below. | -| `process.executable.path` | string | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | Conditionally Required: See alternative attributes below. | -| `process.command` | string | The command used to launch the process (i.e. the command name). On Linux based systems, can be set to the zeroth string in `proc/[pid]/cmdline`. On Windows, can be set to the first parameter extracted from `GetCommandLineW`. | `cmd/otelcol` | Conditionally Required: See alternative attributes below. | -| `process.command_line` | string | The full command used to launch the process as a single string representing the full command. On Windows, can be set to the result of `GetCommandLineW`. Do not set this if you have to assemble it just for monitoring; use `process.command_args` instead. | `C:\cmd\otecol --config="my directory\config.yaml"` | Conditionally Required: See alternative attributes below. | -| `process.command_args` | string[] | All the command arguments (including the command/executable itself) as received by the process. On Linux-based systems (and some other Unixoid systems supporting procfs), can be set according to the list of null-delimited strings extracted from `proc/[pid]/cmdline`. For libc-based executables, this would be the full argv vector passed to `main`. | `[cmd/otecol, --config=config.yaml]` | Conditionally Required: See alternative attributes below. | -| `process.owner` | string | The username of the user that owns the process. | `root` | Recommended | - -**Additional attribute requirements:** At least one of the following sets of attributes is required: - -* `process.executable.name` -* `process.executable.path` -* `process.command` -* `process.command_line` -* `process.command_args` - - -Between `process.command_args` and `process.command_line`, usually `process.command_args` should be preferred. -On Windows and other systems where the native format of process commands is a single string, -`process.command_line` can additionally (or instead) be used. - -For backwards compatibility with older versions of this semantic convention, -it is possible but deprecated to use an array as type for `process.command_line`. -In that case it MUST be interpreted as if it was `process.command_args`. - -## Process runtimes - -**type:** `process.runtime` - -**Description:** The single (language) runtime instance which is monitored. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `process.runtime.name` | string | The name of the runtime of this process. For compiled native binaries, this SHOULD be the name of the compiler. | `OpenJDK Runtime Environment` | Recommended | -| `process.runtime.version` | string | The version of the runtime of this process, as returned by the runtime without modification. | `14.0.2` | Recommended | -| `process.runtime.description` | string | An additional description about the runtime of the process, for example a specific vendor customization of the runtime environment. | `Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0` | Recommended | - - -How to set these attributes for particular runtime kinds is described in the following subsections. - -In addition to these attributes, [`telemetry.sdk.language`](README.md#telemetry-sdk) can be used to determine the general kind of runtime used. - -### Erlang Runtimes - -- `process.runtime.name` - The name of the Erlang VM being used, i.e., `erlang:system_info(machine)`. -- `process.runtime.version` - The version of the runtime (ERTS - Erlang Runtime System), i.e., `erlang:system_info(version)`. -- `process.runtime.description` - string | An additional description about the runtime made by combining the OTP version, i.e., `erlang:system_info(otp_release)`, and ERTS version. - -Example: - -| `process.runtime.name` | `process.runtime.version` | `process.runtime.description` | -| --- | --- | --- | -| BEAM | 11.1 | Erlang/OTP 23 erts-11.1 | - -### Go Runtimes - -Go Runtimes should fill in the as follows: - -- `process.runtime.name` - Fill in an interpretation of Go's [`runtime.Compiler`](https://pkg.go.dev/runtime#Compiler) constant, according to the following rule: - If the value is `gc`, fill in `go`. Otherwise, fill in the exact value of `runtime.Compiler`. - - This can be implemented with the following Go snippet: - - ```go - import "runtime" - - func getRuntimeName() string { - if runtime.Compiler == "gc" { - return "go" - } - return runtime.Compiler - } - ``` - -- `process.runtime.version` - Fill in the exact value returned by `runtime.Version()`, i.e. `go1.17`. -- `process.runtime.description` - Use of this field is not recommended. - -Examples for some Go compilers/runtimes: - -| `process.runtime.name` | Description | -| --- | --- | -| `go` | Official Go compiler. Also known as `cmd/compile`. | -| `gccgo` | [gccgo](https://go.dev/doc/install/gccgo) is a Go [front end for GCC](https://gcc.gnu.org/frontends.html). | -| `tinygo` | [TinyGo](https://tinygo.org/) compiler. | - -### Java runtimes - -Java instrumentation should fill in the values by copying from system properties. - -- `process.runtime.name` - Fill in the value of `java.runtime.name` as is -- `process.runtime.version` - Fill in the value of `java.runtime.version` as is -- `process.runtime.description` - Fill in the values of `java.vm.vendor`, `java.vm.name`, `java.vm.version` - in that order, separated by spaces. - -Examples for some Java runtimes - -| Name | `process.runtime.name` | `process.runtime.version` | `process.runtime.description` | -| --- | --- | --- | --- | -| OpenJDK | OpenJDK Runtime Environment | 11.0.8+10 | Oracle Corporation OpenJDK 64-Bit Server VM 11.0.8+10 | -| AdoptOpenJDK Eclipse J9 | OpenJDK Runtime Environment | 11.0.8+10 | Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0 | -| AdoptOpenJDK Hotspot | OpenJDK Runtime Environment | 11.0.8+10 | AdoptOpenJDK OpenJDK 64-Bit Server VM 11.0.8+10 | -| SapMachine | OpenJDK Runtime Environment | 11.0.8+10-LTS-sapmachine | SAP SE OpenJDK 64-Bit Server VM 11.0.8+10-LTS-sapmachine | -| Zulu OpenJDK | OpenJDK Runtime Environment | 11.0.8+10-LTS | Azul Systems, Inc OpenJDK 64-Bit Server VM Zulu11.41+23-CA | -| Oracle Hotspot 8 (32 bit) | Java(TM) SE Runtime Environment | 1.8.0_221-b11 | Oracle Corporation Java HotSpot(TM) Client VM 25.221-b11 | -| IBM J9 8 | Java(TM) SE Runtime Environment | 8.0.5.25 - pwa6480sr5fp25-20181030_01(SR5 FP25) | IBM Corporation IBM J9 VM 2.9 | -| Android 11 | Android Runtime | 0.9 | The Android Project Dalvik 2.1.0 | - -### JavaScript runtimes - -JavaScript instrumentation should fill in the values by copying from built-in runtime constants. - -- `process.runtime.name`: - - When the runtime is Node.js, fill in the constant value `nodejs`. - - When the runtime is Web Browser, fill in the constant value `browser`. -- `process.runtime.version`: - - When the runtime is Node.js, fill in the value of `process.versions.node`. - - When the runtime is Web Browser, fill in the value of `navigator.userAgent`. - -Examples for some JavaScript runtimes - -| Name | `process.runtime.name` | `process.runtime.version` | -| --- | --- | --- | -| Node.js | nodejs | 14.15.4 | -| Web Browser | browser | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.71 Safari/537.36 | - -### .NET Runtimes - -TODO(): Confirm the contents here - -| Value | Description | -| --- | --- | -| `dotnet-core` | .NET Core, .NET 5+ | -| `dotnet-framework` | .NET Framework | -| `mono` | Mono | - -### Python Runtimes - -Python instrumentation should fill in the values as follows: - -- `process.runtime.name` - - Fill in the value of [`sys.implementation.name`][py_impl] -- `process.runtime.version` - - Fill in the [`sys.implementation.version`][py_impl] values separated by dots. - Leave out the release level and serial if the release level - equals `final` and the serial equals zero - (leave out either both or none). - - This can be implemented with the following Python snippet: - - ```python - vinfo = sys.implementation.version - result = ".".join(map( - str, - vinfo[:3] - if vinfo.releaselevel == "final" and not vinfo.serial - else vinfo - )) - ``` - -- `process.runtime.description` - Fill in the value of [`sys.version`](https://docs.python.org/3/library/sys.html#sys.version) as-is. - -[py_impl]: https://docs.python.org/3/library/sys.html#sys.implementation - -Examples for some Python runtimes: - -| Name | `process.runtime.name` | `process.runtime.version` | `process.runtime.description` | -| --- | --- | --- | --- | -| CPython 3.7.3 on Windows | cpython | 3.7.3 | 3.7.3 (v3.7.3:ef4ec6ed12, Mar 25 2019, 22:22:05) [MSC v.1916 64 bit (AMD64)] | -| CPython 3.8.6 on Linux | cpython | 3.8.6 | 3.8.6 (default, Sep 30 2020, 04:00:38)
[GCC 10.2.0] | -| PyPy 3 7.3.2 on Linux | pypy | 3.7.4 | 3.7.4 (?, Sep 27 2020, 15:12:26)
[PyPy 7.3.2-alpha0 with GCC 10.2.0] | - -Note that on Linux, there is an actual newline in the `sys.version` string, -and the CPython string had a trailing space in the first line. - -Pypy provided a CPython-compatible version in `sys.implementation.version` instead of the actual implementation version which is available in `sys.version`. - -### Ruby Runtimes - -Ruby instrumentation should fill in the values by copying from built-in runtime constants. - -- `process.runtime.name` - Fill in the value of `RUBY_ENGINE` as is -- `process.runtime.version` - Fill in the value of `RUBY_VERSION` as is -- `process.runtime.description` - Fill in the value of `RUBY_DESCRIPTION` as is - -Examples for some Ruby runtimes - -| Name | `process.runtime.name` | `process.runtime.version` | `process.runtime.description` | -| --- | --- | --- | --- | -| MRI | ruby | 2.7.1 | ruby 2.7.1p83 (2020-03-31 revision a0c7c23c9c) [x86_64-darwin19] | -| TruffleRuby | truffleruby | 2.6.2 | truffleruby (Shopify) 20.0.0-dev-92ed3059, like ruby 2.6.2, GraalVM CE Native [x86_64-darwin] | diff --git a/specification/resource/semantic_conventions/webengine.md b/specification/resource/semantic_conventions/webengine.md deleted file mode 100644 index 82d2e87dff2..00000000000 --- a/specification/resource/semantic_conventions/webengine.md +++ /dev/null @@ -1,29 +0,0 @@ -# Webengine - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -**type:** `webengine` - -**Description:** Resource describing the packaged software running the application code. Web engines are typically executed using process.runtime. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `webengine.name` | string | The name of the web engine. | `WildFly` | Required | -| `webengine.version` | string | The version of the web engine. | `21.0.0` | Recommended | -| `webengine.description` | string | Additional description of the web engine (e.g. detailed version and edition information). | `WildFly Full 21.0.0.Final (WildFly Core 13.0.1.Final) - 2.2.2.Final` | Recommended | - - -Information describing the web engine SHOULD be captured using the values acquired from the API provided by the web engine, preferably during runtime, to avoid maintenance burden on engine version upgrades. As an example - Java engines are often but not always packaged as application servers. For Java application servers supporting Servlet API the required information MAY be captured by invoking `ServletContext.getServerInfo()` during runtime and parsing the result. - -A resource can be attributed to at most one web engine. - -The situations where there are multiple candidates, it is up to instrumentation library authors to choose the web engine. To illustrate, let's look at a Python application using Apache HTTP Server with mod_wsgi as the server and Django as the web framework. In this situation: - -* Either Apache HTTP Server or `mod_wsgi` MAY be chosen as `webengine`, depending on the decision made by the instrumentation authors. -* Django SHOULD NOT be set as an `webengine` as the required information is already available in instrumentation library and setting this into `webengine` would duplicate the information. diff --git a/specification/trace/api.md b/specification/trace/api.md index 5c8285c2dd2..425eff9d822 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -510,7 +510,7 @@ Setting an attribute with the same key as an existing attribute SHOULD overwrite the existing attribute's value. Note that the OpenTelemetry project documents certain ["standard -attributes"](semantic_conventions/README.md) that have prescribed semantic meanings. +attributes"](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md) that have prescribed semantic meanings. Note that [Samplers](sdk.md#sampler) can only consider information already present during span creation. Any changes done later, including new or changed @@ -551,7 +551,7 @@ The specification does not require any normalization if provided timestamps are out of range. Note that the OpenTelemetry project documents certain ["standard event names and -keys"](semantic_conventions/README.md) which have prescribed semantic meanings. +keys"](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md) which have prescribed semantic meanings. Note that [`RecordException`](#record-exception) is a specialized variant of `AddEvent` for recording exception events. diff --git a/specification/trace/exceptions.md b/specification/trace/exceptions.md index e0d7f2ad890..303f3b04234 100644 --- a/specification/trace/exceptions.md +++ b/specification/trace/exceptions.md @@ -47,4 +47,4 @@ filled out: - `exception.type` The format and semantics of these attributes are -defined in [semantic conventions](semantic_conventions/exceptions.md). +defined in [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/exceptions/exceptions-spans.md). diff --git a/specification/trace/sdk_exporters/jaeger.md b/specification/trace/sdk_exporters/jaeger.md index 10247012ff2..32d11f0ede1 100644 --- a/specification/trace/sdk_exporters/jaeger.md +++ b/specification/trace/sdk_exporters/jaeger.md @@ -57,7 +57,7 @@ single process and exporters need to handle this case accordingly. Critically, Jaeger backend depends on `Span.Process.ServiceName` to identify the service that produced the spans. That field MUST be populated from the `service.name` attribute -of the [`service` resource](../../resource/semantic_conventions/README.md#service). +of the [`service` resource](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#service). If no `service.name` is contained in a Span's Resource, that field MUST be populated from the [default](../../resource/sdk.md#sdk-provided-resource-attributes) `Resource`. diff --git a/specification/trace/sdk_exporters/zipkin.md b/specification/trace/sdk_exporters/zipkin.md index 4d25556b400..f434be08ad2 100644 --- a/specification/trace/sdk_exporters/zipkin.md +++ b/specification/trace/sdk_exporters/zipkin.md @@ -60,7 +60,7 @@ and Zipkin. ### Service name Zipkin service name MUST be set to the value of the -[resource attribute](../../resource/semantic_conventions/README.md): +[resource attribute](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md): `service.name`. If no `service.name` is contained in a Span's Resource, it MUST be populated from the [default](../../resource/sdk.md#sdk-provided-resource-attributes) `Resource`. In Zipkin it is important that the service name is consistent @@ -97,10 +97,10 @@ always available. The following table lists the possible attributes for |Rank|Attribute Name|Reason| |---|---|---| -|1|peer.service|[OpenTelemetry adopted attribute for remote service.](../semantic_conventions/span-general.md#general-remote-service-attributes)| -|2|server.address|[OpenTelemetry adopted attribute for remote hostname, or similar.](../semantic_conventions/span-general.md#server-and-client-attributes)| -|3|server.socket.domain|[OpenTelemetry adopted attribute for remote socket hostname of the peer.](../semantic_conventions/span-general.md#server-and-client-attributes)| -|4|server.socket.address & server.socket.port|[OpenTelemetry adopted attribute for remote socket address of the peer.](../semantic_conventions/span-general.md#server-and-client-attributes)| +|1|peer.service|[OpenTelemetry adopted attribute for remote service.](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md#server-client-and-shared-network-attributes)| +|2|server.address|[OpenTelemetry adopted attribute for remote hostname, or similar.](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md#server-client-and-shared-network-attributes)| +|3|server.socket.domain|[OpenTelemetry adopted attribute for remote socket hostname of the peer.](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md#server-client-and-shared-network-attributes)| +|4|server.socket.address & server.socket.port|[OpenTelemetry adopted attribute for remote socket address of the peer.](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md#server-client-and-shared-network-attributes)| |5|peer.hostname|Remote hostname defined in OpenTracing specification.| |6|peer.address|Remote address defined in OpenTracing specification.| |7|db.name|Commonly used database name attribute for DB Spans.| @@ -121,7 +121,7 @@ OpenTelemetry Span `Attribute`(s) MUST be reported as `tags` to Zipkin. Some attributes defined in [semantic -convention](../semantic_conventions/README.md) +convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md) document maps to the strongly-typed fields of Zipkin spans. Primitive types MUST be converted to string using en-US culture settings. diff --git a/specification/trace/semantic_conventions/README.md b/specification/trace/semantic_conventions/README.md deleted file mode 100644 index 3167a518e2c..00000000000 --- a/specification/trace/semantic_conventions/README.md +++ /dev/null @@ -1,50 +0,0 @@ -# Trace Semantic Conventions - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -In OpenTelemetry spans can be created freely and it’s up to the implementor to -annotate them with attributes specific to the represented operation. Spans -represent specific operations in and between systems. Some of these operations -represent calls that use well-known protocols like HTTP or database calls. -Depending on the protocol and the type of operation, additional information -is needed to represent and analyze a span correctly in monitoring systems. It is -also important to unify how this attribution is made in different languages. -This way, the operator will not need to learn specifics of a language and -telemetry collected from polyglot (multi-language) micro-service environments -can still be easily correlated and cross-analyzed. - -The following semantic conventions for spans are defined: - -* [General](span-general.md): General semantic attributes that may be used in describing different kinds of operations. -* [HTTP](http.md): For HTTP client and server spans. -* [Database](database.md): For SQL and NoSQL client call spans. -* [RPC/RMI](rpc.md): For remote procedure call (e.g., gRPC) spans. -* [Messaging](messaging.md): For messaging systems (queues, publish/subscribe, etc.) spans. -* [FaaS](faas.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) (e.g., AWS Lambda) spans. -* [Exceptions](exceptions.md): For recording exceptions associated with a span. -* [Compatibility](compatibility.md): For spans generated by compatibility components, e.g. OpenTracing Shim layer. -* [Feature Flags](feature-flags.md): For recording feature flag evaluations associated with a span. - -The following library-specific semantic conventions are defined: - -* [AWS Lambda](instrumentation/aws-lambda.md): For AWS Lambda spans. -* [AWS SDK](instrumentation/aws-sdk.md): For AWS SDK spans. -* [GraphQL](instrumentation/graphql.md): For GraphQL spans. - -Apart from semantic conventions for traces and [metrics](../../metrics/semantic_conventions/README.md), -OpenTelemetry also defines the concept of overarching [Resources](../../resource/sdk.md) with their own -[Resource Semantic Conventions](../../resource/semantic_conventions/README.md). - -## Event Name Reuse Prohibition - -A new event MUST NOT be added with the same name as an event that existed in -the past but was renamed (with a corresponding schema file). - -When introducing a new event name check all existing schema files to make sure -the name does not appear as a key of any "rename_events" section (keys denote -old event names in rename operations). diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md deleted file mode 100644 index 37d563afadb..00000000000 --- a/specification/trace/semantic_conventions/cloudevents.md +++ /dev/null @@ -1,209 +0,0 @@ -# CloudEvents - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - - - - - -- [Definitions](#definitions) -- [Overview](#overview) -- [Conventions](#conventions) - * [Spans](#spans) - + [Creation](#creation) - + [Processing](#processing) - * [Attributes](#attributes) - - - -## Definitions - - From the - [CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#overview): - -> CloudEvents is a specification for describing event data in common formats -to provide interoperability across services, platforms and systems. -> - -For more information on the concepts, terminology and background of CloudEvents -consult the -[CloudEvents Primer](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/primer.md) -document. - -## Overview - -A CloudEvent can be sent directly from producer to consumer. -For such a scenario, the traditional parent-child trace model works well. -However, CloudEvents are also used in distributed systems where an event -can go through many [hops](https://en.wikipedia.org/wiki/Hop_(networking)) -until it reaches a consumer. In this scenario, the traditional parent-child -trace model is not sufficient to produce a meaningful trace. - -Consider the following scenario: - -``` -+----------+ +--------------+ -| Producer | ---------------> | Intermediary | -+----------+ +--------------+ - | - | - | - v -+----------+ +----------+ -| Consumer | <----------------- | Queue | -+----------+ +----------+ -``` - -With the traditional parent-child trace model, the above scenario would produce -two traces, completely independent from each other because the consumer -starts receiving (and thus has to specify a parent span) before it receives the event. -It is not possible to correlate a producer with a consumer(s) solely via a parent-child relationship. - -``` -+-------------------------------------------------+ -| Trace 1 | -| | -| +---------------------------------------+ | -| | Send (auto-instr) | | -| +---------------------------------------+ | -| +------------------------------------+ | -| | Intermediary: Received (auto-instr)| | -| +------------------------------------+ | -| +------------------------------------+ | -| | Intermediary: Send (auto-instr) | | -| +------------------------------------+ | -| | -| Trace 2 | -| | -| +---------------------------------------+ | -| | Consumer: Receive (auto-instr) | | -| +---------------------------------------+ | -| | -+-------------------------------------------------+ -``` - -This document defines semantic conventions to model the different stages -a CloudEvent can go through in a system, making it possible to create traces -that are meaningful and consistent. It covers creation, processing, -context propagation between producer and consumer(s) and attributes -to be added to spans. - -With the proposed model, it is possible to have an overview of everything -that happened as the result of an event. One can, for example, answer the -following questions: - -- What components in a system reacted to an event -- What further events were sent due to an incoming event -- Which event caused the exception - -With the conventions in this document, the application scenario above would -produce a trace where it is possible to correlate a producer with a consumer(s): - -``` -+-------------------------------------------------------+ -| Trace 1 | -| | -| +---------------------------------------+ | -| +---> | Create event | | -| | +---------------------------------------+ | -| | +---------------------------------------+ | -| | | Send (auto-instr) | | -| | +---------------------------------------+ | -| | +------------------------------------+ | -| | | Intermediary: Received (auto-instr)| | -| | +------------------------------------+ | -| | +------------------------------------+ | -| | | Intermediary: Send (auto-instr) | | -| |Link +------------------------------------+ | -| | | -| | | -| | | -| | Trace 2 | -| | | -| | +---------------------------------------+ | -| | | Consumer: Receive (auto-instr) | | -| | +---------------------------------------+ | -| | +-------------------------------------+ | -| +------ | Consumer: Process | | -| +-------------------------------------+ | -| | -+-------------------------------------------------------+ -``` - -## Conventions - -To achieve the trace above, it is necessary to capture the context of -the event creation so that when the CloudEvent reaches its destination(s), this -context can be continued. Each CloudEvent acts then as the medium of this -context propagation. - -This document relies on the CloudEvents specification, which defines this -context propagation mechanism via the -[CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/extensions/distributed-tracing.md). -Once the trace context is set on the event -via the Distributed Tracing Extension, it MUST not be modified. - -The remainder of this section describes the semantic conventions for Spans -required to achieve the proposed trace. - -### Spans - -#### Creation - -Instrumentation SHOULD create a new span and populate the -[CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/extensions/distributed-tracing.md) -on the event. This applies when: - -- A CloudEvent is created by the instrumented library. -It may be impossible or impractical to create the Span during event -creation (e.g. inside the constructor or in a factory method), -so instrumentation MAY create the Span later, when passing the event to the transport layer. -- A CloudEvent is created outside of the instrumented library -(e.g. directly constructed by the application owner, without calling a constructor or factory method), -and passed without the Distributed Tracing Extension populated. - -In case a CloudEvent is passed to the instrumented library with the -Distributed Tracing Extension already populated, instrumentation MUST NOT create -a span and MUST NOT modify the Distributed Tracing Extension on the event. - -- Span name: `CloudEvents Create ` - -- Span kind: PRODUCER - -- Span attributes: Instrumentation MUST add the required attributes defined -in the [table below](#attributes). - -#### Processing - -When an instrumented library supports processing of a single CloudEvent, -instrumentation SHOULD create a new span to trace it. - -Instrumentation SHOULD set the remote trace context from the -Distributed Tracing Extension as a link on the processing span. -Instrumentation MAY add attributes to the link to further describe it. - -- Span name: `CloudEvents Process ` - -- Span kind: CONSUMER - -- Span attributes: Instrumentation MUST add the required attributes defined -in the [table below](#attributes). - -### Attributes - -The following attributes are applicable to creation and processing Spans. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event. | `123e4567-e89b-12d3-a456-426614174000`; `0001` | Required | -| `cloudevents.event_source` | string | The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | Required | -| `cloudevents.event_spec_version` | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses. | `1.0` | Recommended | -| `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | Recommended | -| `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | Recommended | - diff --git a/specification/trace/semantic_conventions/compatibility.md b/specification/trace/semantic_conventions/compatibility.md deleted file mode 100644 index fb2c1b2b89d..00000000000 --- a/specification/trace/semantic_conventions/compatibility.md +++ /dev/null @@ -1,41 +0,0 @@ -# Semantic conventions for Compatibility components - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -This document defines trace semantic conventions used by the -compatibility components, e.g. OpenTracing Shim layer. - - - - - -- [OpenTracing](#opentracing) - - - -## OpenTracing - -`Link`s created by the OpenTracing Shim MUST set `opentracing.ref_type` -with one of the accepted values, describing the direct causal relationships -between a child Span and a parent Span, as defined by -[OpenTracing](https://github.com/opentracing/specification/blob/master/specification.md). - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `opentracing.ref_type` | string | Parent-child Reference type [1] | `child_of` | Recommended | - -**[1]:** The causal relationship between a child Span and a parent Span. - -`opentracing.ref_type` MUST be one of the following: - -| Value | Description | -|---|---| -| `child_of` | The parent Span depends on the child Span in some capacity | -| `follows_from` | The parent Span does not depend in any way on the result of the child Span | - diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md deleted file mode 100644 index 5dc4e593bdb..00000000000 --- a/specification/trace/semantic_conventions/database.md +++ /dev/null @@ -1,369 +0,0 @@ -# Semantic conventions for database client calls - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - - - - - -- [Connection-level attributes](#connection-level-attributes) - * [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem) - * [Connection-level attributes for specific technologies](#connection-level-attributes-for-specific-technologies) -- [Call-level attributes](#call-level-attributes) - * [Call-level attributes for specific technologies](#call-level-attributes-for-specific-technologies) - + [Cassandra](#cassandra) - + [Microsoft Azure Cosmos DB Attributes](#microsoft-azure-cosmos-db-attributes) -- [Examples](#examples) - * [MySQL](#mysql) - * [Redis](#redis) - * [MongoDB](#mongodb) - * [Microsoft Azure Cosmos DB](#microsoft-azure-cosmos-db) - - - -> **Warning** -> Existing Database instrumentations that are using -> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/database.md) -> (or prior): -> -> * SHOULD NOT change the version of the networking attributes that they emit -> until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in Database instrumentations). -> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` -> in the existing major version which supports the following values: -> * `none` - continue emitting whatever version of the old experimental -> database attributes the instrumentation was emitting previously. -> This is the default value. -> * `http` - emit the new, stable networking attributes, -> and stop emitting the old experimental networking attributes -> that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable networking attributes, -> allowing for a seamless transition. -> * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). - -**Span kind:** MUST always be `CLIENT`. - -The **span name** SHOULD be set to a low cardinality value representing the statement executed on the database. -It MAY be a stored procedure name (without arguments), DB statement without variable arguments, operation name, etc. -Since SQL statements may have very high cardinality even without arguments, SQL spans SHOULD be named the -following way, unless the statement is known to be of low cardinality: -` .`, provided that `db.operation` and `db.sql.table` are available. -If `db.sql.table` is not available due to its semantics, the span SHOULD be named ` `. -It is not recommended to attempt any client-side parsing of `db.statement` just to get these properties, -they should only be used if the library being instrumented already provides them. -When it's otherwise impossible to get any meaningful span name, `db.name` or the tech-specific database name MAY be used. - -## Connection-level attributes - -These attributes will usually be the same for all operations performed over the same database connection. -Some database systems may allow a connection to switch to a different `db.user`, for example, and other database systems may not even have the concept of a connection at all. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Required | -| `db.connection_string` | string | The connection string used to connect to the database. It is recommended to remove embedded credentials. | `Server=(localdb)\v11.0;Integrated Security=true;` | Recommended | -| `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended | -| [`network.transport`](span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | -| [`network.type`](span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`server.address`](span-general.md) | string | Name of the database host. | `example.com` | Conditionally Required: See alternative attributes below. | -| [`server.port`](span-general.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: [1] | -| [`server.socket.address`](span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | See below | -| [`server.socket.port`](span-general.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | - -**[1]:** If using a port other than the default port for this DBMS and if `server.address` is set. - -**Additional attribute requirements:** At least one of the following sets of attributes is required: - -* [`server.address`](span-general.md) -* [`server.socket.address`](span-general.md) - -`db.system` 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 | -|---|---| -| `other_sql` | Some other SQL database. Fallback only. See notes. | -| `mssql` | Microsoft SQL Server | -| `mssqlcompact` | Microsoft SQL Server Compact | -| `mysql` | MySQL | -| `oracle` | Oracle Database | -| `db2` | IBM Db2 | -| `postgresql` | PostgreSQL | -| `redshift` | Amazon Redshift | -| `hive` | Apache Hive | -| `cloudscape` | Cloudscape | -| `hsqldb` | HyperSQL DataBase | -| `progress` | Progress Database | -| `maxdb` | SAP MaxDB | -| `hanadb` | SAP HANA | -| `ingres` | Ingres | -| `firstsql` | FirstSQL | -| `edb` | EnterpriseDB | -| `cache` | InterSystems Caché | -| `adabas` | Adabas (Adaptable Database System) | -| `firebird` | Firebird | -| `derby` | Apache Derby | -| `filemaker` | FileMaker | -| `informix` | Informix | -| `instantdb` | InstantDB | -| `interbase` | InterBase | -| `mariadb` | MariaDB | -| `netezza` | Netezza | -| `pervasive` | Pervasive PSQL | -| `pointbase` | PointBase | -| `sqlite` | SQLite | -| `sybase` | Sybase | -| `teradata` | Teradata | -| `vertica` | Vertica | -| `h2` | H2 | -| `coldfusion` | ColdFusion IMQ | -| `cassandra` | Apache Cassandra | -| `hbase` | Apache HBase | -| `mongodb` | MongoDB | -| `redis` | Redis | -| `couchbase` | Couchbase | -| `couchdb` | CouchDB | -| `cosmosdb` | Microsoft Azure Cosmos DB | -| `dynamodb` | Amazon DynamoDB | -| `neo4j` | Neo4j | -| `geode` | Apache Geode | -| `elasticsearch` | Elasticsearch | -| `memcached` | Memcached | -| `cockroachdb` | CockroachDB | -| `opensearch` | OpenSearch | -| `clickhouse` | ClickHouse | -| `spanner` | Cloud Spanner | -| `trino` | Trino | - - -### Notes and well-known identifiers for `db.system` - -The list above is a non-exhaustive list of well-known identifiers to be specified for `db.system`. - -If a value defined in this list applies to the DBMS to which the request is sent, this value MUST be used. -If no value defined in this list is suitable, a custom value MUST be provided. -This custom value MUST be the name of the DBMS in lowercase and without a version number to stay consistent with existing identifiers. - -It is encouraged to open a PR towards this specification to add missing values to the list, especially when instrumentations for those missing databases are written. -This allows multiple instrumentations for the same database to be aligned and eases analyzing for backends. - -The value `other_sql` is intended as a fallback and MUST only be used if the DBMS is known to be SQL-compliant but the concrete product is not known to the instrumentation. -If the concrete DBMS is known to the instrumentation, its specific identifier MUST be used. - -Back ends could, for example, use the provided identifier to determine the appropriate SQL dialect for parsing the `db.statement`. - -When additional attributes are added that only apply to a specific DBMS, its identifier SHOULD be used as a namespace in the attribute key as for the attributes in the sections below. - -### Connection-level attributes for specific technologies - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `db.jdbc.driver_classname` | string | The fully-qualified class name of the [Java Database Connectivity (JDBC)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) driver used to connect. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | Recommended | -| `db.mssql.instance_name` | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. [1] | `MSSQLSERVER` | Recommended | - -**[1]:** If setting a `db.mssql.instance_name`, `server.port` is no longer required (but still recommended if non-standard). - - -## Call-level attributes - -These attributes may be different for each operation performed, even if the same connection is used for multiple operations. -Usually only one `db.name` will be used per connection though. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `db.name` | string | This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `main` | Conditionally Required: If applicable. | -| `db.statement` | string | The database statement being executed. | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | Recommended: [2] | -| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. [3] | `findAndModify`; `HMSET`; `SELECT` | Conditionally Required: If `db.statement` is not applicable. | - -**[1]:** In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name). - -**[2]:** Should be collected by default only if there is sanitization that excludes sensitive information. - -**[3]:** When setting this to an SQL keyword, it is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if the operation name is provided by the library being instrumented. If the SQL statement has an ambiguous operation, or performs more than one operation, this value may be omitted. - - -For **Redis**, the value provided for `db.statement` SHOULD correspond to the syntax of the Redis CLI. -If, for example, the [`HMSET` command][] is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.statement`. - -[`HMSET` command]: https://redis.io/commands/hmset - -In **CouchDB**, `db.operation` should be set to the HTTP method + the target REST route according to the API reference documentation. -For example, when retrieving a document, `db.operation` would be set to (literally, i.e., without replacing the placeholders with concrete values): [`GET /{db}/{docid}`][CouchDB get doc]. - -In **Cassandra**, `db.name` SHOULD be set to the keyspace name. - -In **HBase**, `db.name` SHOULD be set to the HBase namespace. - -[CouchDB get doc]: http://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid - -### Call-level attributes for specific technologies - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `db.redis.database_index` | int | The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer. To be used instead of the generic `db.name` attribute. | `0`; `1`; `15` | Conditionally Required: If other than the default database (`0`). | -| `db.mongodb.collection` | string | The collection being accessed within the database stated in `db.name`. | `customers`; `products` | Required | -| `db.sql.table` | string | The name of the primary table that the operation is acting upon, including the database name (if applicable). [1] | `public.users`; `customers` | Recommended | - -**[1]:** It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set. - - -#### Cassandra - -Separated for clarity. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `db.cassandra.page_size` | int | The fetch size used for paging, i.e. how many rows will be returned at once. | `5000` | Recommended | -| `db.cassandra.consistency_level` | string | The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). | `all` | Recommended | -| `db.cassandra.table` | string | The name of the primary table that the operation is acting upon, including the keyspace name (if applicable). [1] | `mytable` | Recommended | -| `db.cassandra.idempotence` | boolean | Whether or not the query is idempotent. | | Recommended | -| `db.cassandra.speculative_execution_count` | int | The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. | `0`; `2` | Recommended | -| `db.cassandra.coordinator.id` | string | The ID of the coordinating node for a query. | `be13faa2-8574-4d71-926d-27f16cf8a7af` | Recommended | -| `db.cassandra.coordinator.dc` | string | The data center of the coordinating node for a query. | `us-west-2` | Recommended | - -**[1]:** This mirrors the db.sql.table attribute but references cassandra rather than sql. It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set. - - -#### Microsoft Azure Cosmos DB Attributes - -Cosmos DB instrumentation includes call-level (public API) surface spans and network spans. Depending on the connection mode (Gateway or Direct), network-level spans may also be created. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `db.cosmosdb.client_id` | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` | Recommended | -| `db.cosmosdb.operation_type` | string | CosmosDB Operation Type. | `Invalid` | Conditionally Required: [1] | -| `db.cosmosdb.connection_mode` | string | Cosmos client connection mode. | `gateway` | Conditionally Required: if not `direct` (or pick gw as default) | -| `db.cosmosdb.container` | string | Cosmos DB container name. | `anystring` | Conditionally Required: if available | -| `db.cosmosdb.request_content_length` | int | Request payload size in bytes | | Recommended | -| `db.cosmosdb.status_code` | int | Cosmos DB status code. | `200`; `201` | Conditionally Required: if response was received | -| `db.cosmosdb.sub_status_code` | int | Cosmos DB sub status code. | `1000`; `1002` | Conditionally Required: [2] | -| `db.cosmosdb.request_charge` | double | RU consumed for that operation | `46.18`; `1.0` | Conditionally Required: when available | -| `user_agent.original` | string | Full user-agent string is generated by Cosmos DB SDK [3] | `cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|` | Recommended | - -**[1]:** when performing one of the operations in this list - -**[2]:** when response was received and contained sub-code. - -**[3]:** The user-agent value is generated by SDK which is a combination of
`sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'
`direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'
`number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'
`type_of_machine_architecture` : Machine architecture. e.g. 'X64'
`operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'
`runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'
`failover_information` : Generated key to determine if region failover enabled. - Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it). - Default value is "NS". - -`db.cosmosdb.operation_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 | -|---|---| -| `Invalid` | invalid | -| `Create` | create | -| `Patch` | patch | -| `Read` | read | -| `ReadFeed` | read_feed | -| `Delete` | delete | -| `Replace` | replace | -| `Execute` | execute | -| `Query` | query | -| `Head` | head | -| `HeadFeed` | head_feed | -| `Upsert` | upsert | -| `Batch` | batch | -| `QueryPlan` | query_plan | -| `ExecuteJavaScript` | execute_javascript | - -`db.cosmosdb.connection_mode` MUST be one of the following: - -| Value | Description | -|---|---| -| `gateway` | Gateway (HTTP) connections mode | -| `direct` | Direct connection. | - - -In addition to Cosmos DB attributes, all spans include -`az.namespace` attribute representing Azure Resource Provider namespace that MUST be equal to `Microsoft.DocumentDB`. - -## Examples - -### MySQL - -| Key | Value | -|:------------------------| :----------------------------------------------------------- | -| Span name | `"SELECT ShopDb.orders"` | -| `db.system` | `"mysql"` | -| `db.connection_string` | `"Server=shopdb.example.com;Database=ShopDb;Uid=billing_user;TableCache=true;UseCompression=True;MinimumPoolSize=10;MaximumPoolSize=50;"` | -| `db.user` | `"billing_user"` | -| `server.address` | `"shopdb.example.com"` | -| `server.socket.address` | `"192.0.2.12"` | -| `server.port` | `3306` | -| `network.transport` | `"IP.TCP"` | -| `db.name` | `"ShopDb"` | -| `db.statement` | `"SELECT * FROM orders WHERE order_id = 'o4711'"` | -| `db.operation` | `"SELECT"` | -| `db.sql.table` | `"orders"` | - -### Redis - -In this example, Redis is connected using a unix domain socket and therefore the connection string and `server.address` are left out. -Furthermore, `db.name` is not specified as there is no database name in Redis and `db.redis.database_index` is set instead. - -| Key | Value | -|:--------------------------| :-------------------------------------------- | -| Span name | `"HMSET myhash"` | -| `db.system` | `"redis"` | -| `db.connection_string` | not set | -| `db.user` | not set | -| `server.socket.address` | `"/tmp/redis.sock"` | -| `network.transport` | `"Unix"` | -| `db.name` | not set | -| `db.statement` | `"HMSET myhash field1 'Hello' field2 'World"` | -| `db.operation` | not set | -| `db.redis.database_index` | `15` | - -### MongoDB - -| Key | Value | -| :---------------------- | :----------------------------------------------------------- | -| Span name | `"products.findAndModify"` | -| `db.system` | `"mongodb"` | -| `db.connection_string` | not set | -| `db.user` | `"the_user"` | -| `server.address` | `"mongodb0.example.com"` | -| `server.socket.address` | `"192.0.2.14"` | -| `server.port` | `27017` | -| `network.transport` | `"IP.TCP"` | -| `db.name` | `"shopDb"` | -| `db.statement` | not set | -| `db.operation` | `"findAndModify"` | -| `db.mongodb.collection` | `"products"` | - -### Microsoft Azure Cosmos DB - -| Key | Value | -|:-------------------------------------| :------------------- | -| Span name | `"ReadItemsAsync"` | -| `kind` | `"internal"` | -| `az.namespace` | `"Microsoft.DocumentDB"` | -| `db.system` | `"cosmosdb"` | -| `db.name` | `"database name"` | -| `db.operation` | `"ReadItemsAsync"` | -| `server.address` | `"account.documents.azure.com"` | -| `db.cosmosdb.client_id` | `3ba4827d-4422-483f-b59f-85b74211c11d` | -| `db.cosmosdb.operation_type` | `Read` | -| `user_agent.original` | `cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|` | -| `db.cosmosdb.connection_mode` | `"Direct"` | -| `db.cosmosdb.container` | `"container name"` | -| `db.cosmosdb.request_content_length` | `20` | -| `db.cosmosdb.status_code` | `201` | -| `db.cosmosdb.sub_status_code` | `0` | -| `db.cosmosdb.request_charge` | `7.43` | diff --git a/specification/trace/semantic_conventions/exceptions.md b/specification/trace/semantic_conventions/exceptions.md deleted file mode 100644 index b6dd674e357..00000000000 --- a/specification/trace/semantic_conventions/exceptions.md +++ /dev/null @@ -1,112 +0,0 @@ -# Semantic Conventions for Exceptions - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -This document defines semantic conventions for recording application -exceptions. - - - -- [Recording an Exception](#recording-an-exception) -- [Attributes](#attributes) - * [Stacktrace Representation](#stacktrace-representation) - - - -## Recording an Exception - -An exception SHOULD be recorded as an `Event` on the span during which it occurred. -The name of the event MUST be `"exception"`. - -A typical template for an auto-instrumentation implementing this semantic convention -using an [API-provided `recordException` method](../api.md#record-exception) -could look like this (pseudo-Java): - -```java -Span span = myTracer.startSpan(/*...*/); -try { - // Code that does the actual work which the Span represents -} catch (Throwable e) { - span.recordException(e, Attributes.of("exception.escaped", true)); - throw e; -} finally { - span.end(); -} -``` - -## Attributes - -The table below indicates which attributes should be added to the `Event` and -their types. - - -The event name MUST be `exception`. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `exception.escaped` | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] | | Recommended | -| `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below | -| `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | Recommended | -| `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | See below | - -**[1]:** An exception is considered to have escaped (or left) the scope of a span, -if that span is ended while the exception is still logically "in flight". -This may be actually "in flight" in some languages (e.g. if the exception -is passed to a Context manager's `__exit__` method in Python) but will -usually be caught at the point of recording the exception in most languages. - -It is usually not possible to determine at the point where an exception is thrown -whether it will escape the scope of a span. -However, it is trivial to know that an exception -will escape, if one checks for an active exception just before ending the span, -as done in the [example above](#recording-an-exception). - -It follows that an exception may still escape the scope of the span -even if the `exception.escaped` attribute was not set or set to false, -since the event might have been recorded at a time where it was not -clear whether the exception will escape. - -**Additional attribute requirements:** At least one of the following sets of attributes is required: - -* `exception.type` -* `exception.message` - - -### Stacktrace Representation - -The table below, adapted from [Google Cloud][gcp-error-reporting], includes -possible representations of stacktraces in various languages. The table is not -meant to be a recommendation for any particular language, although SIGs are free -to adopt them if they see fit. - -| Language | Format | -| ---------- | ------------------------------------------------------------------- | -| C# | the return value of [Exception.ToString()][csharp-stacktrace] | -| Elixir | the return value of [Exception.format/3][elixir-stacktrace] | -| Erlang | the return value of [`erl_error:format`][erlang-stacktrace] | -| Go | the return value of [runtime.Stack][go-stacktrace] | -| Java | the contents of [Throwable.printStackTrace()][java-stacktrace] | -| Javascript | the return value of [error.stack][js-stacktrace] as returned by V8 | -| Python | the return value of [traceback.format_exc()][python-stacktrace] | -| Ruby | the return value of [Exception.full_message][ruby-full-message] | - -Backends can use the language specified methodology for generating a stacktrace -combined with platform information from the -[telemetry sdk resource][telemetry-sdk-resource] in order to extract more fine -grained information from a stacktrace, if necessary. - -[gcp-error-reporting]: https://cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report -[java-stacktrace]: https://docs.oracle.com/javase/7/docs/api/java/lang/Throwable.html#printStackTrace%28%29 -[python-stacktrace]: https://docs.python.org/3/library/traceback.html#traceback.format_exc -[js-stacktrace]: https://v8.dev/docs/stack-trace-api -[ruby-full-message]: https://ruby-doc.org/core-2.7.1/Exception.html#method-i-full_message -[csharp-stacktrace]: https://docs.microsoft.com/en-us/dotnet/api/system.exception.tostring -[go-stacktrace]: https://pkg.go.dev/runtime/debug#Stack -[telemetry-sdk-resource]: ../../resource/semantic_conventions/README.md#telemetry-sdk -[erlang-stacktrace]: https://www.erlang.org/doc/man/erl_error.html#format_exception-3 -[elixir-stacktrace]: https://hexdocs.pm/elixir/1.14.3/Exception.html#format/3 diff --git a/specification/trace/semantic_conventions/faas.md b/specification/trace/semantic_conventions/faas.md deleted file mode 100644 index 719733802e1..00000000000 --- a/specification/trace/semantic_conventions/faas.md +++ /dev/null @@ -1,262 +0,0 @@ -# Semantic conventions for FaaS spans - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -This document defines how to describe an instance of a function that runs without provisioning -or managing of servers (also known as serverless functions or Function as a Service (FaaS)) with spans. - -See also the [additional instructions for instrumenting AWS Lambda](instrumentation/aws-lambda.md). - - - - - -- [General Attributes](#general-attributes) - * [Function Name](#function-name) - * [Difference between invocation and instance](#difference-between-invocation-and-instance) -- [Incoming Invocations](#incoming-invocations) - * [Incoming FaaS Span attributes](#incoming-faas-span-attributes) - * [Resource attributes as incoming FaaS span attributes](#resource-attributes-as-incoming-faas-span-attributes) -- [Outgoing Invocations](#outgoing-invocations) -- [Function Trigger Type](#function-trigger-type) - * [Datasource](#datasource) - * [HTTP](#http) - * [PubSub](#pubsub) - * [Timer](#timer) - * [Other](#other) -- [Example](#example) - - - -## General Attributes - -Span `name` should be set to the function name being executed. Depending on the value of the `faas.trigger` attribute, additional attributes MUST be set. For example, an `http` trigger SHOULD follow the [HTTP Server semantic conventions](http.md#http-server-semantic-conventions). For more information, refer to the [Function Trigger Type](#function-trigger-type) section. - -If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../../resource/semantic_conventions/faas.md#function-as-a-service). - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. [1] | `datasource` | Recommended | -| `faas.invocation_id` | string | The invocation ID of the current function invocation. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | Recommended | -| [`cloud.resource_id`](../../resource/semantic_conventions/cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [2] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | Recommended | - -**[1]:** For the server/consumer span on the incoming side, -`faas.trigger` MUST be set. - -Clients invoking FaaS instances usually cannot set `faas.trigger`, -since they would typically need to look in the payload to determine -the event type. If clients set it, it should be the same as the -trigger that corresponding incoming would have (i.e., this has -nothing to do with the underlying transport used to make the API -call to invoke the lambda, which is often HTTP). - -**[2]:** On some cloud providers, it may not be possible to determine the full ID at startup, -so it may be necessary to set `cloud.resource_id` as a span attribute instead. - -The exact value to use for `cloud.resource_id` depends on the cloud provider. -The following well-known definitions MUST be used if you set this attribute and they apply: - -* **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html). - Take care not to use the "invoked ARN" directly but replace any - [alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) - with the resolved function version, as the same runtime instance may be invokable with - multiple different aliases. -* **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names) -* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/en-us/rest/api/resources/resources/get-by-id) of the invoked function, - *not* the function app, having the form - `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/`. - This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share - a TracerProvider. - -`faas.trigger` MUST be one of the following: - -| Value | Description | -|---|---| -| `datasource` | A response to some data source operation such as a database or filesystem read/write. | -| `http` | To provide an answer to an inbound HTTP request | -| `pubsub` | A function is set to be executed when messages are sent to a messaging system. | -| `timer` | A function is scheduled to be executed regularly. | -| `other` | If none of the others apply | - - -### Function Name - -There are 2 locations where the function's name can be recorded: the span name and the -[`faas.name` Resource attribute](../../resource/semantic_conventions/faas.md#function-as-a-service). - -It is guaranteed that if `faas.name` attribute is present it will contain the -function name, since it is defined in the semantic convention strictly for that -purpose. It is also highly likely that Span name will contain the function name -(e.g. for Span displaying purposes), but it is not guaranteed (since it is a -weaker "SHOULD" requirement). Consumers that needs such guarantee can use -`faas.name` attribute as the source. - -### Difference between invocation and instance - -For performance reasons (e.g. [AWS lambda], or [Azure functions]), FaaS providers allocate an execution environment for a single instance of a function that is used to serve multiple requests. -Developers exploit this fact to solve the **cold start** issue, caching expensive resource computations between different function invocations. -Furthermore, FaaS providers encourage this behavior, e.g. [Google functions]. -The `faas.instance` resource attribute MAY be set to help correlate function invocations that belong to the same execution environment. -The span attribute `faas.invocation_id` differs from the [resource attribute][FaaS resource attributes] `faas.instance` in the following: - -- `faas.invocation_id` refers to the ID of the current invocation of the function; -- `faas.instance` refers to the execution environment ID of the function. - -[AWS lambda]: https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html -[Azure functions]: https://docs.microsoft.com/en-us/azure/azure-functions/manage-connections#static-clients -[Google functions]: https://cloud.google.com/functions/docs/concepts/exec#function_scope_versus_global_scope - -## Incoming Invocations - -This section describes incoming FaaS invocations as they are reported by the FaaS instance itself. - -For incoming FaaS spans, the span kind MUST be `Server`. - -### Incoming FaaS Span attributes - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `faas.coldstart` | boolean | A boolean that is true if the serverless function is executed for the first time (aka cold-start). | | Recommended | -| `faas.trigger` | string | Type of the trigger which caused this function invocation. [1] | `datasource` | Required | - -**[1]:** For the server/consumer span on the incoming side, -`faas.trigger` MUST be set. - -Clients invoking FaaS instances usually cannot set `faas.trigger`, -since they would typically need to look in the payload to determine -the event type. If clients set it, it should be the same as the -trigger that corresponding incoming would have (i.e., this has -nothing to do with the underlying transport used to make the API -call to invoke the lambda, which is often HTTP). - - -### Resource attributes as incoming FaaS span attributes - -In addition to the attributes listed above, any [FaaS](../../resource/semantic_conventions/faas.md) or [cloud](../../resource/semantic_conventions/cloud.md) resource attributes MAY -instead be set as span attributes on incoming FaaS invocation spans: In some -FaaS environments some of the information required for resource -attributes is only readily available in the context of an invocation (e.g. as part of a "request context" argument) -and while a separate API call to look up the resource information is often possible, it -may be prohibitively expensive due to cold start duration concerns. -The `cloud.resource_id` and `cloud.account.id` attributes on AWS are some examples. -In principle, the above considerations apply to any resource attribute that fulfills the criteria above -(not being readily available without some extra effort that could be expensive). - -## Outgoing Invocations - -This section describes outgoing FaaS invocations as they are reported by a client calling a FaaS instance. - -For outgoing FaaS spans, the span kind MUST be `Client`. - -The values reported by the client for the attributes listed below SHOULD be equal to -the corresponding [FaaS resource attributes][] and [Cloud resource attributes][], -which the invoked FaaS instance reports about itself, if it's instrumented. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `faas.invoked_name` | string | The name of the invoked function. [1] | `my-function` | Required | -| `faas.invoked_provider` | string | The cloud provider of the invoked function. [2] | `alibaba_cloud` | Required | -| `faas.invoked_region` | string | The cloud region of the invoked function. [3] | `eu-central-1` | Conditionally Required: [4] | - -**[1]:** SHOULD be equal to the `faas.name` resource attribute of the invoked function. - -**[2]:** SHOULD be equal to the `cloud.provider` resource attribute of the invoked function. - -**[3]:** SHOULD be equal to the `cloud.region` resource attribute of the invoked function. - -**[4]:** For some cloud providers, like AWS or GCP, the region in which a function is hosted is essential to uniquely identify the function and also part of its endpoint. Since it's part of the endpoint being called, the region is always known to clients. In these cases, `faas.invoked_region` MUST be set accordingly. If the region is unknown to the client or not required for identifying the invoked function, setting `faas.invoked_region` is optional. - -`faas.invoked_provider` 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 | -|---|---| -| `alibaba_cloud` | Alibaba Cloud | -| `aws` | Amazon Web Services | -| `azure` | Microsoft Azure | -| `gcp` | Google Cloud Platform | -| `tencent_cloud` | Tencent Cloud | - - -[FaaS resource attributes]: ../../resource/semantic_conventions/faas.md -[Cloud resource attributes]: ../../resource/semantic_conventions/cloud.md - -## Function Trigger Type - -This section describes how to handle the span creation and additional attributes based on the value of the attribute `faas.trigger`. - -### Datasource - -A datasource function is triggered as a response to some data source operation such as a database or filesystem read/write. -FaaS instrumentations that produce `faas` spans with trigger `datasource`, SHOULD use the following set of attributes. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `faas.document.collection` | string | The name of the source on which the triggering operation was performed. For example, in Cloud Storage or S3 corresponds to the bucket name, and in Cosmos DB to the database name. | `myBucketName`; `myDbName` | Required | -| `faas.document.operation` | string | Describes the type of the operation that was performed on the data. | `insert` | Required | -| `faas.document.time` | string | A string containing the time when the data was accessed in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | Recommended | -| `faas.document.name` | string | The document name/table subjected to the operation. For example, in Cloud Storage or S3 is the name of the file, and in Cosmos DB the table name. | `myFile.txt`; `myTableName` | Recommended | - -`faas.document.operation` 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 | -|---|---| -| `insert` | When a new object is created. | -| `edit` | When an object is modified. | -| `delete` | When an object is deleted. | - - -### HTTP - -The function responsibility is to provide an answer to an inbound HTTP request. The `faas` span SHOULD follow the recommendations described in the [HTTP Server semantic conventions](http.md#http-server-semantic-conventions). - -### PubSub - -A function is set to be executed when messages are sent to a messaging system. -In this case, multiple messages could be batch and forwarded at once to the same function invocation. -Therefore, a different root span of type `faas` MUST be created for each message processed by the function, following the [Messaging systems semantic conventions](messaging.md). -This way, it is possible to correlate each individual message with its invocation sender. - -### Timer - -A function is scheduled to be executed regularly. The following additional attributes are recommended. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `faas.time` | string | A string containing the function invocation time in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | Recommended | -| `faas.cron` | string | A string containing the schedule period as [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). | `0/5 * * * ? *` | Recommended | - - -### Other - -Function as a Service offers such flexibility that it is not possible to fully cover with semantic conventions. -When a function does not satisfy any of the aforementioned cases, a span MUST set the attribute `faas.trigger` to `"other"`. -In this case, it is responsibility of the framework or instrumentation library to define the most appropriate attributes. - -## Example - -This example shows the FaaS attributes for a (non-FaaS) process hosted on Google Cloud Platform (Span A with kind `Client`), which invokes a Lambda function called "my-lambda-function" in Amazon Web Services (Span B with kind `Server`). - -| Attribute Kind | Attribute | Span A (Client, GCP) | Span B (Server, AWS Lambda) | -| -------------- | ----------------------- | ---------------------- | -- | -| Resource | `cloud.provider` | `"gcp"` | `"aws"` | -| Resource | `cloud.region` | `"europe-west3"` | `"eu-central-1"` | -| Span | `faas.invoked_name` | `"my-lambda-function"` | n/a | -| Span | `faas.invoked_provider` | `"aws"` | n/a | -| Span | `faas.invoked_region` | `"eu-central-1"` | n/a | -| Span | `faas.trigger` | n/a | `"http"` | -| Span | `faas.invocation_id` | n/a | `"af9d5aa4-a685-4c5f-a22b-444f80b3cc28"` | -| Span | `faas.coldstart` | n/a | `true` | -| Resource | `faas.name` | n/a | `"my-lambda-function"` | -| Resource | `faas.version` | n/a | `"semver:2.0.0"` | -| Resource | `faas.instance` | n/a | `"my-lambda-function:instance-0001"` | -| Resource | `cloud.resource_id` | n/a | `"arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function"` | diff --git a/specification/trace/semantic_conventions/feature-flags.md b/specification/trace/semantic_conventions/feature-flags.md deleted file mode 100644 index b11e6fde55c..00000000000 --- a/specification/trace/semantic_conventions/feature-flags.md +++ /dev/null @@ -1,62 +0,0 @@ -# Semantic conventions for Feature Flags - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -This document defines semantic conventions for recording dynamic feature flag -evaluations within a transaction as span events. -To record an evaluation outside of a transaction context, consider -[recording it as a log record](../../logs/semantic_conventions/feature-flags.md). - - - - - -- [Motivation](#motivation) -- [Overview](#overview) -- [Convention](#convention) - - - -## Motivation - -Features flags are commonly used in modern applications to decouple feature releases from deployments. -Many feature flagging tools support the ability to update flag configurations in near real-time from a remote feature flag management service. -They also commonly allow rulesets to be defined that return values based on contextual information. -For example, a feature could be enabled only for a specific subset of users based on context (e.g. users email domain, membership tier, country). - -Since feature flags are dynamic and affect runtime behavior, it's important to collect relevant feature flag telemetry signals. -This can be used to determine the impact a feature has on a request, enabling enhanced observability use cases, such as A/B testing or progressive feature releases. - -## Overview - -The following semantic convention defines how feature flags can be represented as an `Event` in OpenTelemetry. -The terminology was defined in the [OpenFeature specification](https://docs.openfeature.dev/docs/specification/), which represents an industry consensus. -It's intended to be vendor neutral and provide flexibility for current and future use cases. - -## Convention - -A flag evaluation SHOULD be recorded as an Event on the span during which it occurred. - - -The event name MUST be `feature_flag`. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `feature_flag.key` | string | The unique identifier of the feature flag. | `logo-color` | Required | -| `feature_flag.provider_name` | string | The name of the service provider that performs the flag evaluation. | `Flag Manager` | Recommended | -| `feature_flag.variant` | string | SHOULD be a semantic identifier for a value. If one is unavailable, a stringified version of the value can be used. [1] | `red`; `true`; `on` | Recommended | - -**[1]:** A semantic identifier, commonly referred to as a variant, provides a means -for referring to a value without including the value itself. This can -provide additional context for understanding the meaning behind a value. -For example, the variant `red` maybe be used for the value `#c05543`. - -A stringified version of the value can be used in situations where a -semantic identifier is unavailable. String representation of the value -should be determined by the implementer. - diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md deleted file mode 100644 index 65a4b95befc..00000000000 --- a/specification/trace/semantic_conventions/http.md +++ /dev/null @@ -1,461 +0,0 @@ -# Semantic conventions for HTTP spans - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -This document defines semantic conventions for HTTP client and server Spans. -They can be used for http and https schemes -and various HTTP versions like 1.1, 2 and SPDY. - - - - - -- [Name](#name) -- [Status](#status) -- [Common Attributes](#common-attributes) - * [HTTP request and response headers](#http-request-and-response-headers) -- [HTTP client](#http-client) - * [HTTP request retries and redirects](#http-request-retries-and-redirects) -- [HTTP server](#http-server) - * [HTTP server definitions](#http-server-definitions) - * [HTTP Server semantic conventions](#http-server-semantic-conventions) -- [Examples](#examples) - * [HTTP client-server example](#http-client-server-example) - * [HTTP client retries examples](#http-client-retries-examples) - * [HTTP client authorization retry examples](#http-client-authorization-retry-examples) - * [HTTP client redirects examples](#http-client-redirects-examples) - - - -> **Warning** -> Existing HTTP instrumentations that are using -> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) -> (or prior): -> -> * SHOULD NOT change the version of the HTTP or networking attributes that they emit -> until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in HTTP instrumentations). -> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` -> in the existing major version which supports the following values: -> * `none` - continue emitting whatever version of the old experimental -> HTTP and networking attributes the instrumentation was emitting previously. -> This is the default value. -> * `http` - emit the new, stable HTTP and networking attributes, -> and stop emitting the old experimental HTTP and networking attributes -> that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable HTTP and networking attributes, -> allowing for a seamless transition. -> * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). - -## Name - -HTTP spans MUST follow the overall [guidelines for span names](../api.md#span). -HTTP server span names SHOULD be `{http.request.method} {http.route}` if there is a -(low-cardinality) `http.route` available. -HTTP server span names SHOULD be `{http.method}` if there is no (low-cardinality) -`http.route` available. -HTTP client spans have no `http.route` attribute since client-side instrumentation -is not generally aware of the "route", and therefore HTTP client spans SHOULD use -`{http.method}`. -Instrumentation MUST NOT default to using URI -path as span name, but MAY provide hooks to allow custom logic to override the -default span name. - -## Status - -[Span Status](../api.md#set-status) MUST be left unset if HTTP status code was in the -1xx, 2xx or 3xx ranges, unless there was another error (e.g., network error receiving -the response body; or 3xx codes with max redirects exceeded), in which case status -MUST be set to `Error`. - -For HTTP status codes in the 4xx range span status MUST be left unset in case of `SpanKind.SERVER` -and MUST be set to `Error` in case of `SpanKind.CLIENT`. - -For HTTP status codes in the 5xx range, as well as any other code the client -failed to interpret, span status MUST be set to `Error`. - -Don't set the span status description if the reason can be inferred from `http.response.status_code`. - -## Common Attributes - -The common attributes listed in this section apply to both HTTP clients and servers in addition to -the specific attributes listed in the [HTTP client](#http-client) and [HTTP server](#http-server) -sections below. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| `http.request.body.size` | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | -| `http.response.body.size` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | -| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| [`network.protocol.name`](span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `spdy` | Recommended: if not default (`http`). | -| [`network.protocol.version`](span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `1.0`; `1.1`; `2.0` | Recommended | -| [`network.transport`](span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Conditionally Required: [2] | -| [`network.type`](span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| `user_agent.original` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended | - -**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. - -**[2]:** If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`). - -Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: - -* `http.request.method` - -`network.transport` 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 | -|---|---| -| `tcp` | TCP | -| `udp` | UDP | -| `pipe` | Named or anonymous pipe. See note below. | -| `unix` | Unix domain socket | - -`network.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 | -|---|---| -| `ipv4` | IPv4 | -| `ipv6` | IPv6 | - - -### HTTP request and response headers - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|-------------------| -| `http.request.header.` | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [1] [2] | `http.request.header.content_type=["application/json"]`; `http.request.header.x_forwarded_for=["1.2.3.4", "1.2.3.5"]` | Opt-In | -| `http.response.header.` | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [1] [2] | `http.response.header.content_type=["application/json"]`; `http.response.header.my_custom_header=["abc", "def"]` | Opt-In | - -**[1]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. -Including all request/response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. - -The `User-Agent` header is already captured in the `user_agent.original` attribute. -Users MAY explicitly configure instrumentations to capture them even though it is not recommended. - -**[2]:** The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. - -## HTTP client - -This span type represents an outbound HTTP request. There are two ways this can be achieved in an instrumentation: - -1. Instrumentations SHOULD create an HTTP span for each attempt to send an HTTP request over the wire. - In case the request is resent, the resend attempts MUST follow the [HTTP resend spec](#http-request-retries-and-redirects). - In this case, instrumentations SHOULD NOT (also) emit a logical encompassing HTTP client span. - -2. If for some reason it is not possible to emit a span for each send attempt (because e.g. the instrumented library does not expose hooks that would allow this), - instrumentations MAY create an HTTP span for the top-most operation of the HTTP client. - In this case, the `url.full` MUST be the absolute URL that was originally requested, before any HTTP-redirects that may happen when executing the request. - -For an HTTP client span, `SpanKind` MUST be `Client`. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.resend_count` | int | The ordinal number of request resending attempt (for any reason, including redirects). [1] | `3` | Recommended: if and only if request was retried. | -| [`server.address`](span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | -| [`server.port`](span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | -| [`server.socket.address`](span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. | -| [`server.socket.domain`](span-general.md) | string | The domain name of an immediate peer. [5] | `proxy.example.com` | Recommended | -| [`server.socket.port`](span-general.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | -| [`url.full`](../../common/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [6] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Required | - -**[1]:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other). - -**[2]:** Determined by using the first of the following that applies - -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form -- Host identifier of the `Host` header - -If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then -`server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. - -**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. - -**[4]:** If not default (`80` for `http` scheme, `443` for `https`). - -**[5]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. - -**[6]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. -`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password should be redacted and attribute's value should be `https://REDACTED:REDACTED@www.example.com/`. -`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) and SHOULD NOT be validated or modified except for sanitizing purposes. - -Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: - -* [`server.address`](span-general.md) -* [`server.port`](span-general.md) -* [`url.full`](../../common/url.md) - - -Note that in some cases host and port identifiers in the `Host` header might be different from the `server.address` and `server.port`, in this case instrumentation MAY populate `Host` header on `http.request.header.host` attribute even if it's not enabled by user. - -### HTTP request retries and redirects - -Retries and redirects cause more than one physical HTTP request to be sent. -A request is resent when an HTTP client library sends more than one HTTP request to satisfy the same API call. -This may happen due to following redirects, authorization challenges, 503 Server Unavailable, network issues, or any other. - -Each time an HTTP request is resent, the `http.resend_count` attribute SHOULD be added to each repeated span and set to the ordinal number of the request resend attempt. - -See the examples for more details about: - -* [retrying a server error](#http-client-retries-examples), -* [redirects](#http-client-redirects-examples), -* [authorization](#http-client-authorization-retry-examples). - -## HTTP server - -To understand the attributes defined in this section, it is helpful to read the "Definitions" subsection. - -### HTTP server definitions - -This section gives a short summary of some concepts -in web server configuration and web app deployment -that are relevant to tracing. - -Usually, on a physical host, reachable by one or multiple IP addresses, a single HTTP listener process runs. -If multiple processes are running, they must listen on distinct TCP/UDP ports so that the OS can route incoming TCP/UDP packets to the right one. - -Within a single server process, there can be multiple **virtual hosts**. -The [HTTP host header][] (in combination with a port number) is normally used to determine to which of them to route incoming HTTP requests. - -The host header value that matches some virtual host is called the virtual hosts's **server name**. If there are multiple aliases for the virtual host, one of them (often the first one listed in the configuration) is called the **primary server name**. See for example, the Apache [`ServerName`][ap-sn] or NGINX [`server_name`][nx-sn] directive or the CGI specification on `SERVER_NAME` ([RFC 3875][rfc-servername]). -In practice the HTTP host header is often ignored when just a single virtual host is configured for the IP. - -Within a single virtual host, some servers support the concepts of an **HTTP application** -(for example in Java, the Servlet JSR defines an application as -"a collection of servlets, HTML pages, classes, and other resources that make up a complete application on a Web server" --- SRV.9 in [JSR 53][]; -in a deployment of a Python application to Apache, the application would be the [PEP 3333][] conformant callable that is configured using the -[`WSGIScriptAlias` directive][modwsgisetup] of `mod_wsgi`). - -An application can be "mounted" under an **application root** -(also known as a *[context root][]*, *[context prefix][]*, or *[document base][]*) -which is a fixed path prefix of the URL that determines to which application a request is routed -(e.g., the server could be configured to route all requests that go to an URL path starting with `/webshop/` -at a particular virtual host -to the `com.example.webshop` web application). - -Some servers allow to bind the same HTTP application to multiple `(virtual host, application root)` pairs. - -> TODO: Find way to trace HTTP application and application root ([opentelemetry/opentelementry-specification#335][]) - -[HTTP host header]: https://tools.ietf.org/html/rfc7230#section-5.4 -[PEP 3333]: https://www.python.org/dev/peps/pep-3333/ -[modwsgisetup]: https://modwsgi.readthedocs.io/en/develop/user-guides/quick-configuration-guide.html -[context root]: https://docs.jboss.org/jbossas/guides/webguide/r2/en/html/ch06.html -[context prefix]: https://marc.info/?l=apache-cvs&m=130928191414740 -[document base]: http://tomcat.apache.org/tomcat-5.5-doc/config/context.html -[rfc-servername]: https://tools.ietf.org/html/rfc3875#section-4.1.14 -[ap-sn]: https://httpd.apache.org/docs/2.4/mod/core.html#servername -[nx-sn]: http://nginx.org/en/docs/http/ngx_http_core_module.html#server_name -[JSR 53]: https://jcp.org/aboutJava/communityprocess/maintenance/jsr053/index2.html -[opentelemetry/opentelementry-specification#335]: https://github.com/open-telemetry/opentelemetry-specification/issues/335 - -### HTTP Server semantic conventions - -This span type represents an inbound HTTP request. - -For an HTTP server span, `SpanKind` MUST be `Server`. - -Given an inbound request for a route (e.g. `"/users/:userID?"`) the `name` attribute of the span SHOULD be set to this route. - -If the route cannot be determined, the `name` attribute MUST be set as defined in the general semantic conventions for HTTP. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| [`client.address`](span-general.md) | string | Client address - unix domain socket name, IPv4 or IPv6 address. [2] | `83.164.160.102` | Recommended | -| [`client.port`](span-general.md) | int | The port of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) or a similar header). Otherwise, the immediate client peer port. [3] | `65123` | Recommended | -| [`client.socket.address`](span-general.md) | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | -| [`client.socket.port`](span-general.md) | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. | -| [`server.address`](span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Required | -| [`server.port`](span-general.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | -| [`server.socket.address`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.5.3.2` | Opt-In | -| [`server.socket.port`](span-general.md) | int | Local socket port. Useful in case of a multi-port host. | `16456` | Opt-In | -| [`url.path`](../../common/url.md) | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [7] | `/search` | Required | -| [`url.query`](../../common/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [8] | `q=OpenTelemetry` | Recommended | -| [`url.scheme`](../../common/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | - -**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. -SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. - -**[2]:** The IP address of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded), [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For), or a similar header). Otherwise, the immediate client peer address. - -**[3]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent client port behind any intermediaries (e.g. proxies) if it's available. - -**[4]:** Determined by using the first of the following that applies - -- The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only - include host identifier. -- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Host identifier of the `Host` header - -SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. - -**[5]:** Determined by using the first of the following that applies - -- Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. -- Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. -- Port identifier of the `Host` header - -**[6]:** If not default (`80` for `http` scheme, `443` for `https`). - -**[7]:** When missing, the value is assumed to be `/` - -**[8]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. - -Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: - -* [`server.address`](span-general.md) -* [`server.port`](span-general.md) -* [`url.path`](../../common/url.md) -* [`url.query`](../../common/url.md) -* [`url.scheme`](../../common/url.md) - - -`http.route` MUST be provided at span creation time if and only if it's already available. If it becomes available after span starts, instrumentation MUST populate it anytime before span ends. - -Note that in some cases host and port identifiers in the `Host` header might be different from the `server.address` and `server.port`, in this case instrumentation MAY populate `Host` header on `http.request.header.host` attribute even if it's not enabled by user. - -## Examples - -### HTTP client-server example - -As an example, if a browser request for `https://example.com:8080/webshop/articles/4?s=1` is invoked from a host with IP 192.0.2.4, we may have the following Span on the client side: - -Span name: `GET` - -| Attribute name | Value | -| :------------------- | :-------------------------------------------------------| -| `http.request.method`| `"GET"` | -| `network.protocol.version` | `"1.1"` | -| `url.full` | `"https://example.com:8080/webshop/articles/4?s=1"` | -| `server.address` | `example.com` | -| `server.port` | 8080 | -| `server.socket.address` | `"192.0.2.5"` | -| `http.response.status_code` | `200` | - -The corresponding server Span may look like this: - -Span name: `GET /webshop/articles/:article_id`. - -| Attribute name | Value | -| :------------------- | :---------------------------------------------- | -| `http.request.method`| `"GET"` | -| `network.protocol.version` | `"1.1"` | -| `url.path` | `"/webshop/articles/4"` | -| `url.query` | `"?s=1"` | -| `server.address` | `"example.com"` | -| `server.port` | `8080` | -| `url.scheme` | `"https"` | -| `http.route` | `"/webshop/articles/:article_id"` | -| `http.response.status_code` | `200` | -| `client.address` | `"192.0.2.4"` | -| `client.socket.address` | `"192.0.2.5"` (the client goes through a proxy) | -| `user_agent.original` | `"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:72.0) Gecko/20100101 Firefox/72.0"` | - -### HTTP client retries examples - -Example of retries in the presence of a trace started by an inbound request: - -``` -request (SERVER, trace=t1, span=s1) - | - -- GET / - 500 (CLIENT, trace=t1, span=s2) - | | - | --- server (SERVER, trace=t1, span=s3) - | - -- GET / - 500 (CLIENT, trace=t1, span=s4, http.resend_count=1) - | | - | --- server (SERVER, trace=t1, span=s5) - | - -- GET / - 200 (CLIENT, trace=t1, span=s6, http.resend_count=2) - | - --- server (SERVER, trace=t1, span=s7) -``` - -Example of retries with no trace started upfront: - -``` -GET / - 500 (CLIENT, trace=t1, span=s1) - | - --- server (SERVER, trace=t1, span=s2) - -GET / - 500 (CLIENT, trace=t2, span=s1, http.resend_count=1) - | - --- server (SERVER, trace=t2, span=s2) - -GET / - 200 (CLIENT, trace=t3, span=s1, http.resend_count=2) - | - --- server (SERVER, trace=t3, span=s1) -``` - -### HTTP client authorization retry examples - -Example of retries in the presence of a trace started by an inbound request: - -``` -request (SERVER, trace=t1, span=s1) - | - -- GET /hello - 401 (CLIENT, trace=t1, span=s2) - | | - | --- server (SERVER, trace=t1, span=s3) - | - -- GET /hello - 200 (CLIENT, trace=t1, span=s4, http.resend_count=1) - | - --- server (SERVER, trace=t1, span=s5) -``` - -Example of retries with no trace started upfront: - -``` -GET /hello - 401 (CLIENT, trace=t1, span=s1) - | - --- server (SERVER, trace=t1, span=s2) - -GET /hello - 200 (CLIENT, trace=t2, span=s1, http.resend_count=1) - | - --- server (SERVER, trace=t2, span=s2) -``` - -### HTTP client redirects examples - -Example of redirects in the presence of a trace started by an inbound request: - -``` -request (SERVER, trace=t1, span=s1) - | - -- GET / - 302 (CLIENT, trace=t1, span=s2) - | | - | --- server (SERVER, trace=t1, span=s3) - | - -- GET /hello - 200 (CLIENT, trace=t1, span=s4, http.resend_count=1) - | - --- server (SERVER, trace=t1, span=s5) -``` - -Example of redirects with no trace started upfront: - -``` -GET / - 302 (CLIENT, trace=t1, span=s1) - | - --- server (SERVER, trace=t1, span=s2) - -GET /hello - 200 (CLIENT, trace=t2, span=s1, http.resend_count=1) - | - --- server (SERVER, trace=t2, span=s2) -``` diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md deleted file mode 100644 index fbe60b27c9f..00000000000 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ /dev/null @@ -1,254 +0,0 @@ -# Instrumenting AWS Lambda - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../../document-status.md) - -This document defines how to apply semantic conventions when instrumenting an AWS Lambda request handler. AWS -Lambda largely follows the conventions for [FaaS][faas] while [HTTP](../http.md) conventions are also -applicable when handlers are for HTTP requests. - -There are a variety of triggers for Lambda functions, and this document will grow over time to cover all the -use cases. - - - - - -- [All triggers](#all-triggers) - * [AWS X-Ray Environment Span Link](#aws-x-ray-environment-span-link) -- [API Gateway](#api-gateway) -- [SQS](#sqs) - * [SQS Event](#sqs-event) - * [SQS Message](#sqs-message) -- [Examples](#examples) - * [API Gateway Request Proxy (Lambda tracing passive)](#api-gateway-request-proxy-lambda-tracing-passive) - * [API Gateway Request Proxy (Lambda tracing active)](#api-gateway-request-proxy-lambda-tracing-active) - * [SQS (Lambda tracing passive)](#sqs-lambda-tracing-passive) - * [SQS (Lambda tracing active)](#sqs-lambda-tracing-active) -- [Resource Detector](#resource-detector) - - - -## All triggers - -For all events, a span with kind `SERVER` MUST be created corresponding to the function invocation unless stated -otherwise below. Unless stated otherwise below, the name of the span MUST be set to the function name from the -Lambda `Context`. - -The following attributes SHOULD be set: - -- [`faas.invocation_id`][faas] - The value of the AWS Request ID, which is always available through an accessor on the Lambda `Context`. -- [`cloud.account.id`][cloud] - In some languages, this is available as an accessor on the Lambda `Context`. Otherwise, it can be parsed from the ARN as the fifth item when splitting on `:` - -Also consider setting other attributes of the [`faas` resource][faasres] and [trace][faas] conventions -and the [cloud resource conventions][cloud]. The following AWS Lambda-specific attribute MAY also be set: - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.lambda.invoked_arn` | string | The full invoked ARN as provided on the `Context` passed to the function (`Lambda-Runtime-Invoked-Function-Arn` header on the `/runtime/invocation/next` applicable). [1] | `arn:aws:lambda:us-east-1:123456:function:myfunction:myalias` | Recommended | - -**[1]:** This may be different from `cloud.resource_id` if an alias is involved. - - -[faas]: ../faas.md (FaaS trace conventions) -[faasres]: ../../../resource/semantic_conventions/faas.md (FaaS resource conventions) -[cloud]: ../../../resource/semantic_conventions/cloud.md (Cloud resource conventions) - -### AWS X-Ray Environment Span Link - -If the `_X_AMZN_TRACE_ID` environment variable is set, instrumentation SHOULD try to parse an -OpenTelemetry `Context` out of it using the [AWS X-Ray Propagator](../../../context/api-propagators.md). If the -resulting `Context` is [valid](../../api.md#isvalid) then a [Span Link][] SHOULD be added to the new Span's -[start options](../../api.md#specifying-links) with an associated attribute of `source=x-ray-env` to -indicate the source of the linked span. -Instrumentation MUST check if the context is valid before using it because the `_X_AMZN_TRACE_ID` environment variable can -contain an incomplete trace context which indicates X-Ray isn’t enabled. The environment variable will be set and the -`Context` will be valid and sampled only if AWS X-Ray has been enabled for the Lambda function. A user can -disable AWS X-Ray for the function if the X-Ray Span Link is not desired. - -[Span Link]: https://opentelemetry.io/docs/concepts/signals/traces/#span-links - -## API Gateway - -API Gateway allows a user to trigger a Lambda function in response to HTTP requests. It can be configured to be -a pure proxy, where the information about the original HTTP request is passed to the Lambda function, or as a -configuration for a REST API, in which case only a deserialized body payload is available. In the case the API -gateway is configured to proxy to the Lambda function, the instrumented request handler will have access to all -the information about the HTTP request in the form of an API Gateway Proxy Request Event. - -The Lambda span name and the [`http.route` span attribute](../http.md#http-server-semantic-conventions) SHOULD -be set to the [resource property][] from the proxy request event, which corresponds to the user configured HTTP -route instead of the function name. - -[`faas.trigger`][faas] MUST be set to `http`. [HTTP attributes](../http.md) SHOULD be set based on the -available information in the Lambda event initiated by the proxy request. `http.scheme` is available as the -`x-forwarded-proto` header in the Lambda event. Refer to the [input event format][] for more details. - -[resource property]: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format -[input event format]: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format - -## SQS - -Amazon Simple Queue Service (SQS) is a message queue that triggers a Lambda function with a batch of messages. -So we consider processing both of a batch and of each individual message. The function invocation span MUST -correspond to the SQS event, which is the batch of messages. For each message, an additional span SHOULD be -created to correspond with the handling of the SQS message. Because handling of a message will be inside user -business logic, not the Lambda framework, automatic instrumentation mechanisms without code change will often -not be able to instrument the processing of the individual messages. Instrumentation SHOULD provide utilities -for creating message processing spans within user code. - -The span kind for both types of SQS spans MUST be `CONSUMER`. - -### SQS Event - -For the SQS event span, if all the messages in the event have the same event source, the name of the span MUST -be ` process`. If there are multiple sources in the batch, the name MUST be -`multiple_sources process`. The parent MUST be the `SERVER` span corresponding to the function invocation. - -For every message in the event, the [message system attributes][] (not message attributes, which are provided by -the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be -parsed from the value of the attribute using the [AWS X-Ray Propagator](../../../context/api-propagators.md) and -added as a link to the span. This means the span may have as many links as messages in the batch. -See [compatibility](../../../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info. - -- [`faas.trigger`][faas] MUST be set to `pubsub`. -- [`messaging.operation`](../messaging.md) MUST be set to `process`. -- [`messaging.system`](../messaging.md) MUST be set to `AmazonSQS`. -- [`messaging.destination.kind` or `messaging.source.kind`](../messaging.md#messaging-attributes) MUST be set to `queue`. - -### SQS Message - -For the SQS message span, the name MUST be ` process`. The parent MUST be the `CONSUMER` span -corresponding to the SQS event. The [message system attributes][] (not message attributes, which are provided by -the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be -parsed from the value of the attribute using the [AWS X-Ray Propagator](../../../context/api-propagators.md) and -added as a link to the span. -See [compatibility](../../../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info. - -- [`faas.trigger`][faas] MUST be set to `pubsub`. -- [`messaging.operation`](../messaging.md#messaging-attributes) MUST be set to `process`. -- [`messaging.system`](../messaging.md#messaging-attributes) MUST be set to `AmazonSQS`. - -Other [Messaging attributes](../messaging.md#messaging-attributes) SHOULD be set based on the available information in the SQS message -event. - -Note that `AWSTraceHeader` is the only supported mechanism for propagating `Context` in instrumentation for SQS -to prevent conflicts with other sources. Notably, message attributes (user-provided, not system) are not supported - -the linked contexts are always expected to have been sent as HTTP headers of the `SQS.SendMessage` request that -the message originated from. This is a function of AWS SDK instrumentation, not Lambda instrumentation. - -Using the `AWSTraceHeader` ensures that propagation will work across AWS services that may be integrated to -Lambda via SQS, for example a flow that goes through S3 -> SNS -> SQS -> Lambda. `AWSTraceHeader` is only a means -of propagating context and not tied to any particular observability backend. Notably, using it does not imply -using AWS X-Ray - any observability backend will fully function using this propagation mechanism. - -[message system attributes]: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-message-metadata.html#sqs-message-system-attributes - -## Examples - -### API Gateway Request Proxy (Lambda tracing passive) - -Given a process C that sends an HTTP request to an API Gateway endpoint with path `/pets/{petId}` configured for -a Lambda function F: - -``` -Process C: | Span Client | --- -Function F: | Span Function | -``` - -| Field or Attribute | `Span Client` | `Span Function` | -|-|-|-| -| Span name | `HTTP GET` | `/pets/{petId}` | -| Parent | | Span Client | -| SpanKind | `CLIENT` | `SERVER` | -| Status | `Ok` | `Ok` | -| `faas.invocation_id` | | `79104EXAMPLEB723` | -| `faas.trigger` | | `http` | -| `cloud.account.id` | | `12345678912` | -| `server.address` | `foo.execute-api.us-east-1.amazonaws.com` | | -| `server.port` | `413` | | -| `http.method` | `GET` | `GET` | -| `user_agent.original` | `okhttp 3.0` | `okhttp 3.0` | -| `url.scheme` | | `https` | -| `url.path` | | `/pets/10` | -| `http.route` | | `/pets/{petId}` | -| `http.response.status_code` | `200` | `200` | - -### API Gateway Request Proxy (Lambda tracing active) - -Active tracing in Lambda means an API Gateway span `Span APIGW` and a Lambda runtime invocation span `Span Lambda` -will be exported to AWS X-Ray by the infrastructure (not instrumentation). All attributes above are the same -except that in this case, the parent of `APIGW` is `Span Client` and the parent of `Span Function` is -`Span Lambda`. This means the hierarchy looks like: - -``` -Span Client --> Span APIGW --> Span Lambda --> Span Function -``` - -### SQS (Lambda tracing passive) - -Given a process P, that sends two messages to a queue Q on SQS, and a Lambda function F, which processes both of them in one batch (Span ProcBatch) and -generates a processing span for each message separately (Spans Proc1 and Proc2). - -``` -Process P: | Span Prod1 | Span Prod2 | --- -Function F: | Span ProcBatch | - | Span Proc1 | - | Span Proc2 | -``` - -| Field or Attribute | Span Prod1 | Span Prod2 | Span ProcBatch | Span Proc1 | Span Proc2 | -|-|-|-|-|-|-| -| Span name | `Q send` | `Q send` | `Q process` | `Q process` | `Q process` | -| Parent | | | | Span ProcBatch | Span ProcBatch | -| Links | | | | Span Prod1 | Span Prod2 | -| SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` | `CONSUMER` | `CONSUMER` | -| Status | `Ok` | `Ok` | `Ok` | `Ok` | `Ok` | -| `messaging.system` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | `AmazonSQS` | -| `messaging.destination.name` | `Q` | `Q` | | | | -| `messaging.source.name` | | | `Q` | `Q` | `Q` | -| `messaging.destination.kind` | `queue` | `queue` | | | | -| `messaging.source.kind` | | | `queue` | `queue` | `queue` | -| `messaging.operation` | | | `process` | `process` | `process` | -| `messaging.message.id` | | | | `"a1"` | `"a2"` | - -Note that if Span Prod1 and Span Prod2 were sent to different queues, Span ProcBatch would not have -`messaging.source.name` set as it would correspond to multiple sources. - -The above requires user code change to create `Span Proc1` and `Span Proc2`. In Java, the user would inherit from -[TracingSqsMessageHandler][] instead of Lambda's standard `RequestHandler` to enable them. Otherwise these two spans -would not exist. - -[TracingSqsMessageHandler]: https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/v1.0.1/instrumentation/aws-lambda-1.0/library/src/main/java/io/opentelemetry/instrumentation/awslambda/v1_0/TracingSqsMessageHandler.java - -### SQS (Lambda tracing active) - -Active tracing in Lambda means a Lambda runtime invocation span `Span Lambda` will be exported to X-Ray by the -infrastructure (not instrumentation). In this case, all of the above is the same except `Span ProcBatch` will -have a parent of `Span Lambda`. This means the hierarchy looks like: - -``` -Span Lambda --> Span ProcBatch --> Span Proc1 (links to Span Prod1 and Span Prod2) - \-> Span Proc2 (links to Span Prod1 and Span Prod2) -``` - -## Resource Detector - -AWS Lambda resource information is available as [environment variables][] provided by the runtime. - -- [`cloud.provider`][cloud] MUST be set to `aws` -- [`cloud.region`][cloud] MUST be set to the value of the `AWS_REGION` environment variable -- [`faas.name`][faasres] MUST be set to the value of the `AWS_LAMBDA_FUNCTION_NAME` environment variable -- [`faas.version`][faasres] MUST be set to the value of the `AWS_LAMBDA_FUNCTION_VERSION` environment variable - -Note that [`cloud.resource_id`][cloud] currently cannot be populated as a resource -because it is not available until function invocation. - -[environment variables]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime diff --git a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md deleted file mode 100644 index a5cd1665a35..00000000000 --- a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md +++ /dev/null @@ -1,257 +0,0 @@ -# Semantic conventions for AWS SDK - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../../document-status.md) - -This document defines semantic conventions to apply when instrumenting the AWS SDK. They map request or response -parameters in AWS SDK API calls to attributes on a Span. The conventions have been collected over time based -on feedback from AWS users of tracing and will continue to increase as new interesting conventions -are found. - -Some descriptions are also provided for populating general OpenTelemetry semantic conventions based on these APIs. - -## Context Propagation - -See [compatibility](../../../../supplementary-guidelines/compatibility/aws.md#context-propagation). - -## Common Attributes - -The span name MUST be of the format `Service.Operation` as per the AWS HTTP API, e.g., `DynamoDB.GetItem`, -`S3.ListBuckets`. This is equivalent to concatenating `rpc.service` and `rpc.method` with `.` and consistent -with the naming guidelines for RPC client spans. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.request_id` | string | The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` | Recommended | -| [`rpc.method`](../rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | Recommended | -| [`rpc.service`](../rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | Recommended | -| [`rpc.system`](../rpc.md) | string | The value `aws-api`. | `aws-api` | Required | - -**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). - -**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). - - -## DynamoDB - -### Common Attributes - -These attributes are filled in for all DynamoDB request types. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`db.system`](../database.md) | string | The value `dynamodb`. | `dynamodb` | Required | - - -### DynamoDB.BatchGetItem - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.table_names` | string[] | The keys in the `RequestItems` object field. | `[Users, Cats]` | Recommended | - - -### DynamoDB.BatchWriteItem - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | Recommended | -| `aws.dynamodb.table_names` | string[] | The keys in the `RequestItems` object field. | `[Users, Cats]` | Recommended | - - -### DynamoDB.CreateTable - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.global_secondary_indexes` | string[] | The JSON-serialized value of each item of the `GlobalSecondaryIndexes` request field | `[{ "IndexName": "string", "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" }, "ProvisionedThroughput": { "ReadCapacityUnits": number, "WriteCapacityUnits": number } }]` | Recommended | -| `aws.dynamodb.local_secondary_indexes` | string[] | The JSON-serialized value of each item of the `LocalSecondaryIndexes` request field. | `[{ "IndexArn": "string", "IndexName": "string", "IndexSizeBytes": number, "ItemCount": number, "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" } }]` | Recommended | -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | Recommended | -| `aws.dynamodb.provisioned_read_capacity` | double | The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter. | `1.0`; `2.0` | Recommended | -| `aws.dynamodb.provisioned_write_capacity` | double | The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter. | `1.0`; `2.0` | Recommended | -| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | - - -### DynamoDB.DeleteItem - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | Recommended | -| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | - - -### DynamoDB.DeleteTable - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | - - -### DynamoDB.DescribeTable - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | - - -### DynamoDB.GetItem - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.consistent_read` | boolean | The value of the `ConsistentRead` request parameter. | | Recommended | -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.projection` | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | Recommended | -| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | - - -### DynamoDB.ListTables - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.exclusive_start_table` | string | The value of the `ExclusiveStartTableName` request parameter. | `Users`; `CatsTable` | Recommended | -| `aws.dynamodb.table_count` | int | The the number of items in the `TableNames` response parameter. | `20` | Recommended | -| `aws.dynamodb.limit` | int | The value of the `Limit` request parameter. | `10` | Recommended | - - -### DynamoDB.PutItem - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | Recommended | -| `aws.dynamodb.table_names` | string[] | The keys in the `RequestItems` object field. | `[Users, Cats]` | Recommended | - - -### DynamoDB.Query - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.scan_forward` | boolean | The value of the `ScanIndexForward` request parameter. | | Recommended | -| `aws.dynamodb.attributes_to_get` | string[] | The value of the `AttributesToGet` request parameter. | `[lives, id]` | Recommended | -| `aws.dynamodb.consistent_read` | boolean | The value of the `ConsistentRead` request parameter. | | Recommended | -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.index_name` | string | The value of the `IndexName` request parameter. | `name_to_group` | Recommended | -| `aws.dynamodb.limit` | int | The value of the `Limit` request parameter. | `10` | Recommended | -| `aws.dynamodb.projection` | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | Recommended | -| `aws.dynamodb.select` | string | The value of the `Select` request parameter. | `ALL_ATTRIBUTES`; `COUNT` | Recommended | -| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | - - -### DynamoDB.Scan - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.segment` | int | The value of the `Segment` request parameter. | `10` | Recommended | -| `aws.dynamodb.total_segments` | int | The value of the `TotalSegments` request parameter. | `100` | Recommended | -| `aws.dynamodb.count` | int | The value of the `Count` response parameter. | `10` | Recommended | -| `aws.dynamodb.scanned_count` | int | The value of the `ScannedCount` response parameter. | `50` | Recommended | -| `aws.dynamodb.attributes_to_get` | string[] | The value of the `AttributesToGet` request parameter. | `[lives, id]` | Recommended | -| `aws.dynamodb.consistent_read` | boolean | The value of the `ConsistentRead` request parameter. | | Recommended | -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.index_name` | string | The value of the `IndexName` request parameter. | `name_to_group` | Recommended | -| `aws.dynamodb.limit` | int | The value of the `Limit` request parameter. | `10` | Recommended | -| `aws.dynamodb.projection` | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | Recommended | -| `aws.dynamodb.select` | string | The value of the `Select` request parameter. | `ALL_ATTRIBUTES`; `COUNT` | Recommended | -| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | - - -### DynamoDB.UpdateItem - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | Recommended | -| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | - - -### DynamoDB.UpdateTable - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.dynamodb.attribute_definitions` | string[] | The JSON-serialized value of each item in the `AttributeDefinitions` request field. | `[{ "AttributeName": "string", "AttributeType": "string" }]` | Recommended | -| `aws.dynamodb.global_secondary_index_updates` | string[] | The JSON-serialized value of each item in the the `GlobalSecondaryIndexUpdates` request field. | `[{ "Create": { "IndexName": "string", "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" }, "ProvisionedThroughput": { "ReadCapacityUnits": number, "WriteCapacityUnits": number } }]` | Recommended | -| `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | -| `aws.dynamodb.provisioned_read_capacity` | double | The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter. | `1.0`; `2.0` | Recommended | -| `aws.dynamodb.provisioned_write_capacity` | double | The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter. | `1.0`; `2.0` | Recommended | -| `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | - - -## S3 - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `aws.s3.bucket` | string | The S3 bucket name the request refers to. Corresponds to the `--bucket` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. [1] | `some-bucket-name` | Recommended | -| `aws.s3.key` | string | The S3 object key the request refers to. Corresponds to the `--key` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. [2] | `someFile.yml` | Recommended | -| `aws.s3.copy_source` | string | The source object (in the form `bucket`/`key`) for the copy operation. [3] | `someFile.yml` | Recommended | -| `aws.s3.upload_id` | string | Upload ID that identifies the multipart upload. [4] | `dfRtDYWFbkRONycy.Yxwh66Yjlx.cph0gtNBtJ` | Recommended | -| `aws.s3.delete` | string | The delete request container that specifies the objects to be deleted. [5] | `Objects=[{Key=string,VersionId=string},{Key=string,VersionId=string}],Quiet=boolean` | Recommended | -| `aws.s3.part_number` | int | The part number of the part being uploaded in a multipart-upload operation. This is a positive integer between 1 and 10,000. [6] | `3456` | Recommended | - -**[1]:** The `bucket` attribute is applicable to all S3 operations that reference a bucket, i.e. that require the bucket name as a mandatory parameter. -This applies to almost all S3 operations except `list-buckets`. - -**[2]:** The `key` attribute is applicable to all object-related S3 operations, i.e. that require the object key as a mandatory parameter. -This applies in particular to the following operations: - -- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html) -- [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) -- [get-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-object.html) -- [head-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/head-object.html) -- [put-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-object.html) -- [restore-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/restore-object.html) -- [select-object-content](https://docs.aws.amazon.com/cli/latest/reference/s3api/select-object-content.html) -- [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html) -- [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html) -- [create-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/create-multipart-upload.html) -- [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html) -- [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) -- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) - -**[3]:** The `copy_source` attribute applies to S3 copy operations and corresponds to the `--copy-source` parameter -of the [copy-object operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html). -This applies in particular to the following operations: - -- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html) -- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) - -**[4]:** The `upload_id` attribute applies to S3 multipart-upload operations and corresponds to the `--upload-id` parameter -of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) multipart operations. -This applies in particular to the following operations: - -- [abort-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/abort-multipart-upload.html) -- [complete-multipart-upload](https://docs.aws.amazon.com/cli/latest/reference/s3api/complete-multipart-upload.html) -- [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html) -- [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) -- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) - -**[5]:** The `delete` attribute is only applicable to the [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) operation. -The `delete` attribute corresponds to the `--delete` parameter of the -[delete-objects operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-objects.html). - -**[6]:** The `part_number` attribute is only applicable to the [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) -and [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) operations. -The `part_number` attribute corresponds to the `--part-number` parameter of the -[upload-part operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html). - \ No newline at end of file diff --git a/specification/trace/semantic_conventions/instrumentation/graphql.md b/specification/trace/semantic_conventions/instrumentation/graphql.md deleted file mode 100644 index 8b9c9beb963..00000000000 --- a/specification/trace/semantic_conventions/instrumentation/graphql.md +++ /dev/null @@ -1,34 +0,0 @@ -# Semantic conventions for GraphQL Server - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../../document-status.md) - -This document defines semantic conventions to apply when instrumenting the GraphQL implementation. They map GraphQL -operations to attributes on a Span. - -The **span name** MUST be of the format ` ` provided that -`graphql.operation.type` and `graphql.operation.name` are available. If `graphql.operation.name` is not available, the -span SHOULD be named ``. When `` is not available, `GraphQL Operation` -MAY be used as span name. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `graphql.operation.name` | string | The name of the operation being executed. | `findBookById` | Recommended | -| `graphql.operation.type` | string | The type of the operation being executed. | `query`; `mutation`; `subscription` | Recommended | -| `graphql.document` | string | The GraphQL document being executed. [1] | `query findBookById { bookById(id: ?) { name } }` | Recommended | - -**[1]:** The value may be sanitized to exclude sensitive information. - -`graphql.operation.type` MUST be one of the following: - -| Value | Description | -|---|---| -| `query` | GraphQL query | -| `mutation` | GraphQL mutation | -| `subscription` | GraphQL subscription | - diff --git a/specification/trace/semantic_conventions/messaging.md b/specification/trace/semantic_conventions/messaging.md deleted file mode 100644 index e80b4c9893e..00000000000 --- a/specification/trace/semantic_conventions/messaging.md +++ /dev/null @@ -1,581 +0,0 @@ -# Messaging systems - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - - - - - -- [Definitions](#definitions) - * [Message](#message) - * [Producer](#producer) - * [Consumer](#consumer) - * [Intermediary](#intermediary) - * [Destinations and sources](#destinations-and-sources) - * [Message consumption](#message-consumption) - * [Conversations](#conversations) - * [Temporary and anonymous destinations](#temporary-and-anonymous-destinations) -- [Conventions](#conventions) - * [Context propagation](#context-propagation) - * [Span name](#span-name) - * [Span kind](#span-kind) - * [Operation names](#operation-names) -- [Messaging attributes](#messaging-attributes) - * [Attribute namespaces](#attribute-namespaces) - * [Producer attributes](#producer-attributes) - * [Consumer attributes](#consumer-attributes) - * [Per-message attributes](#per-message-attributes) - * [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems) - + [RabbitMQ](#rabbitmq) - + [Apache Kafka](#apache-kafka) - + [Apache RocketMQ](#apache-rocketmq) -- [Examples](#examples) - * [Topic with multiple consumers](#topic-with-multiple-consumers) - * [Apache Kafka with Quarkus or Spring Boot Example](#apache-kafka-with-quarkus-or-spring-boot-example) - * [Batch receiving](#batch-receiving) - * [Batch processing](#batch-processing) - - - -> **Warning** -> Existing Messaging instrumentations that are using -> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/messaging.md) -> (or prior): -> -> * SHOULD NOT change the version of the networking attributes that they emit -> until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in Messaging instrumentations). -> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` -> in the existing major version which supports the following values: -> * `none` - continue emitting whatever version of the old experimental -> networking attributes the instrumentation was emitting previously. -> This is the default value. -> * `http` - emit the new, stable networking attributes, -> and stop emitting the old experimental networking attributes -> that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable networking attributes, -> allowing for a seamless transition. -> * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). - -## Definitions - -### Message - -Although messaging systems are not as standardized as, e.g., HTTP, it is assumed that the following definitions are applicable to most of them that have similar concepts at all (names borrowed mostly from JMS): - -A *message* is an envelope with a potentially empty payload. -This envelope may offer the possibility to convey additional metadata, often in key/value form. - -A message is sent by a message *producer* to: - -* Physically: some message *broker* (which can be e.g., a single server, or a cluster, or a local process reached via IPC). The broker handles the actual delivery, re-delivery, persistence, etc. In some messaging systems the broker may be identical or co-located with (some) message consumers. -With Apache Kafka, the physical broker a message is written to depends on the number of partitions, and which broker is the *leader* of the partition the record is written to. -* Logically: some particular message *destination*. - -Messages can be delivered to 0, 1, or multiple consumers depending on the dispatching semantic of the protocol. - -### Producer - -The "producer" is a specific instance, process or device that creates and -publishes a message. "Publishing" is the process of sending a message or batch -of messages to the intermediary or consumer. - -### Consumer - -A "consumer" receives the message and acts upon it. It uses the context and -data to execute some logic, which might lead to the occurrence of new events. - -The consumer receives, processes, and settles a message. "Receiving" is the -process of obtaining a message from the intermediary, "processing" is the -process of acting on the information a message contains, "settling" is the -process of notifying an intermediary that a message was processed successfully. - -### Intermediary - -An "intermediary" receives a message to forward it to the next receiver, which -might be another intermediary or a consumer. - -### Destinations and sources - -A destination is usually uniquely identified by name within the messaging system instance. Examples of a destination name would be a URL or a simple one-word identifier. -Sending messages to a destination is called "*publish*" in context of this specification. - -A source represents an entity within messaging system messages are consumed from. Source and destination for specific message may be the same. However, if message is routed within one or multiple brokers, source and destination can be different. - -Typical examples of destinations and sources include Kafka topics, RabbitMQ queues and topics. - -### Message consumption - -The consumption of a message can happen in multiple steps. -First, the lower-level receiving of a message at a consumer, and then the logical processing of the message. -Often, the waiting for a message is not particularly interesting and hidden away in a framework that only invokes some handler function to process a message once one is received -(in the same way that the listening on a TCP port for an incoming HTTP message is not particularly interesting). - -### Conversations - -In some messaging systems, a message can receive one or more reply messages that answers a particular other message that was sent earlier. All messages that are grouped together by such a reply-relationship are called a *conversation*. -The grouping usually happens through some sort of "In-Reply-To:" meta information or an explicit *conversation ID* (sometimes called *correlation ID*). -Sometimes a conversation can span multiple message destinations (e.g. initiated via a topic, continued on a temporary one-to-one queue). - -### Temporary and anonymous destinations - -Some messaging systems support the concept of *temporary destination* (often only temporary queues) that are established just for a particular set of communication partners (often one to one) or conversation. -Often such destinations are also unnamed (anonymous) or have an auto-generated name. - -## Conventions - -Given these definitions, the remainder of this section describes the semantic conventions for Spans describing interactions with messaging systems. - -### Context propagation - -A message may traverse many different components and layers in one or more intermediaries -when it is propagated from the producer to the consumer(s). To be able to correlate -consumer traces with producer traces using the existing context propagation mechanisms, -all components must propagate context down the chain. - -Messaging systems themselves may trace messages as the messages travels from -producers to consumers. Such tracing would cover the transport layer but would -not help in correlating producers with consumers. To be able to directly -correlate producers with consumers, another context that is propagated with -the message is required. - -A message *creation context* allows correlating producers with consumers -of a message and model the dependencies between them, -regardless of the underlying messaging transport mechanism and its instrumentation. - -The message creation context is created by the producer and should be propagated -to the consumer(s). Consumer traces cannot be directly correlated with producer -traces if the message creation context is not attached and propagated with the message. - -A producer SHOULD attach a message creation context to each message. -If possible, the message creation context SHOULD be attached -in such a way that it cannot be changed by intermediaries. - -> This document does not specify the exact mechanisms on how the creation context -> is attached/extracted to/from messages. Future versions of these conventions -> will give clear recommendations, following industry standards including, but not limited to -> [Trace Context: AMQP protocol](https://w3c.github.io/trace-context-amqp/) and -> [Trace Context: MQTT protocol](https://w3c.github.io/trace-context-mqtt/) -> once those standards reach a stable state. - -### Span name - -The span name SHOULD be set to the message destination name and the operation being performed in the following format: - -``` - -``` - -The destination name SHOULD only be used for the span name if it is known to be of low cardinality (cf. [general span name guidelines](../api.md#span)). -This can be assumed if it is statically derived from application code or configuration. -Wherever possible, the real destination names after resolving logical or aliased names SHOULD be used. -If the destination name is dynamic, such as a [conversation ID](#conversations) or a value obtained from a `Reply-To` header, it SHOULD NOT be used for the span name. -In these cases, an artificial destination name that best expresses the destination, or a generic, static fallback like `"(anonymous)"` for [anonymous destinations](#temporary-and-anonymous-destinations) SHOULD be used instead. - -The values allowed for `` are defined in the section [Operation names](#operation-names) below. -If the format above is used, the operation name MUST match the `messaging.operation` attribute defined for message consumer spans below. - -Examples: - -* `shop.orders publish` -* `shop.orders receive` -* `shop.orders process` -* `print_jobs publish` -* `topic with spaces process` -* `AuthenticationRequest-Conversations process` -* `(anonymous) publish` (`(anonymous)` being a stable identifier for an unnamed destination) - -### Span kind - -A producer of a message should set the span kind to `PRODUCER` unless it synchronously waits for a response: then it should use `CLIENT`. -The processor of the message should set the kind to `CONSUMER`, unless it always sends back a reply that is directed to the producer of the message -(as opposed to e.g., a queue on which the producer happens to listen): then it should use `SERVER`. - -### Operation names - -The following operations related to messages are defined for these semantic conventions: - -| Operation name | Description | -| -------------- | ----------- | -| `publish` | A message is sent to a destination by a message producer/client. | -| `receive` | A message is received from a destination by a message consumer/server. | -| `process` | A message that was previously received from a destination is processed by a message consumer/server. | - -## Messaging attributes - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required | -| `messaging.operation` | string | A string identifying the kind of messaging operation as defined in the [Operation names](#operation-names) section above. [1] | `publish` | Required | -| `messaging.batch.message_count` | int | The number of messages sent, received, or processed in the scope of the batching operation. [2] | `0`; `1`; `2` | Conditionally Required: [3] | -| `messaging.client_id` | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | Recommended: If a client id is available | -| `messaging.message.conversation_id` | string | The [conversation ID](#conversations) identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended: [4] | -| `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [5] | -| `messaging.message.payload_compressed_size_bytes` | int | The compressed size of the message payload in bytes. | `2048` | Recommended: [6] | -| `messaging.message.payload_size_bytes` | int | The (uncompressed) size of the message payload in bytes. Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. | `2738` | Recommended: [7] | -| [`network.protocol.name`](span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `mqtt` | Recommended | -| [`network.protocol.version`](span-general.md) | string | Version of the application layer protocol used. See note below. [8] | `3.1.1` | Recommended | -| [`network.transport`](span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | -| [`network.type`](span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`server.address`](span-general.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. [9] | `example.com` | Conditionally Required: If available. | -| [`server.socket.address`](span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. | -| [`server.socket.domain`](span-general.md) | string | The domain name of an immediate peer. [10] | `proxy.example.com` | Recommended: [11] | -| [`server.socket.port`](span-general.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | - -**[1]:** If a custom value is used, it MUST be of low cardinality. - -**[2]:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs. - -**[3]:** If the span describes an operation on a batch of messages. - -**[4]:** Only if span represents operation on a single message. - -**[5]:** Only for spans that represent an operation on a single message. - -**[6]:** Only if span represents operation on a single message. - -**[7]:** Only if span represents operation on a single message. - -**[8]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. - -**[9]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. - -**[10]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. - -**[11]:** If different than `server.address` and if `server.socket.address` is set. - -`messaging.operation` 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 | -|---|---| -| `publish` | publish | -| `receive` | receive | -| `process` | process | - - -Additionally `server.port` from the [network attributes][] is recommended. -Furthermore, it is strongly recommended to add the [`network.transport`][] attribute and follow its guidelines, especially for in-process queueing systems (like [Hangfire][], for example). -These attributes should be set to the broker to which the message is sent/from which it is received. - -### Attribute namespaces - -- `messaging.message`: Contains attributes that describe individual messages -- `messaging.destination`: Contains attributes that describe the logical entity messages are published to. - See [Destinations and sources](#destinations-and-sources) for more details -- `messaging.source`: Contains attributes that describe the logical entity messages are received from -- `messaging.batch`: Contains attributes that describe batch operations -- `messaging.consumer`: Contains attributes that describe application instance that consumes a message. See [consumer](#consumer) for more details - -Communication with broker is described with general [network attributes]. - -Messaging system-specific attributes MUST be defined in the corresponding `messaging.{system}` namespace -as described in [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems). - -[network attributes]: span-general.md#server-and-client-attributes -[`network.transport`]: span-general.md#network-attributes -[Hangfire]: https://www.hangfire.io/ - -### Producer attributes - -The following additional attributes describe message producer operations. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `messaging.destination.anonymous` | boolean | A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name). | | Conditionally Required: [1] | -| `messaging.destination.name` | string | The message destination name [2] | `MyQueue`; `MyTopic` | Conditionally Required: [3] | -| `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [4] | `/customers/{customerId}` | Conditionally Required: [5] | -| `messaging.destination.temporary` | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | Conditionally Required: [6] | - -**[1]:** If value is `true`. When missing, the value is assumed to be `false`. - -**[2]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If -the broker does not have such notion, the destination name SHOULD uniquely identify the broker. - -**[3]:** If one message is being published or if the value applies to all messages in the batch. - -**[4]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. - -**[5]:** If available. Instrumentations MUST NOT use `messaging.destination.name` as template unless low-cardinality of destination name is guaranteed. - -**[6]:** If value is `true`. When missing, the value is assumed to be `false`. - - -### Consumer attributes - -The following additional attributes describe message consumer operations. - -> Note: Consumer spans can have attributes describing source and destination. Since messages could be routed by brokers, source and destination don't always match. If original destination information is available on the consumer, consumer instrumentations SHOULD populate corresponding `messaging.destination` attributes. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `messaging.destination.anonymous` | boolean | A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name). | | Recommended: If known on consumer | -| `messaging.destination.name` | string | The message destination name [1] | `MyQueue`; `MyTopic` | Recommended: If known on consumer | -| `messaging.destination.temporary` | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | Recommended: If known on consumer | -| `messaging.source.anonymous` | boolean | A boolean that is true if the message source is anonymous (could be unnamed or have auto-generated name). | | Recommended: [2] | -| `messaging.source.name` | string | The message source name [3] | `MyQueue`; `MyTopic` | Conditionally Required: [4] | -| `messaging.source.template` | string | Low cardinality representation of the messaging source name [5] | `/customers/{customerId}` | Conditionally Required: [6] | -| `messaging.source.temporary` | boolean | A boolean that is true if the message source is temporary and might not exist anymore after messages are processed. | | Recommended: [7] | - -**[1]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If -the broker does not have such notion, the destination name SHOULD uniquely identify the broker. - -**[2]:** When supported by messaging system and only if the source is anonymous. When missing, the value is assumed to be `false`. - -**[3]:** Source name SHOULD uniquely identify a specific queue, topic, or other entity within the broker. If -the broker does not have such notion, the source name SHOULD uniquely identify the broker. - -**[4]:** If the value applies to all messages in the batch. - -**[5]:** Source names could be constructed from templates. An example would be a source name involving a user name or product id. Although the source name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. - -**[6]:** If available. Instrumentations MUST NOT use `messaging.source.name` as template unless low-cardinality of source name is guaranteed. - -**[7]:** When supported by messaging system and only if the source is temporary. When missing, the value is assumed to be `false`. - - -The *receive* span is be used to track the time used for receiving the message(s), whereas the *process* span(s) track the time for processing the message(s). -Note that one or multiple Spans with `messaging.operation` = `process` may often be the children of a Span with `messaging.operation` = `receive`. -The distinction between receiving and processing of messages is not always of particular interest or sometimes hidden away in a framework (see the [Message consumption](#message-consumption) section above) and therefore the attribute can be left out. -For batch receiving and processing (see the [Batch receiving](#batch-receiving) and [Batch processing](#batch-processing) examples below) in particular, the attribute SHOULD be set. -Even though in that case one might think that the processing span's kind should be `INTERNAL`, that kind MUST NOT be used. -Instead span kind should be set to either `CONSUMER` or `SERVER` according to the rules defined above. - -### Per-message attributes - -All messaging operations (`publish`, `receive`, `process`, or others not covered by this specification) can describe both single and/or batch of messages. -Attributes in the `messaging.message` or `messaging.{system}.message` namespace describe individual messages. For single-message operations they SHOULD be set on corresponding span. - -For batch operations, per-message attributes are usually different and cannot be set on the corresponding span. In such cases the attributes MAY be set on links. See [Batch Receiving](#batch-receiving) and [Batch Processing](#batch-processing) for more information on correlation using links. - -Some messaging systems (e.g., Kafka, Azure EventGrid) allow publishing a single batch of messages to different topics. In such cases, the attributes in `messaging.destination` and `messaging.source` MAY be -set on links. Instrumentations MAY set source and destination attributes on the span if all messages in the batch share the same destination or source. - -### Attributes specific to certain messaging systems - -All attributes that are specific for a messaging system SHOULD be populated in `messaging.{system}` namespace. Attributes that describe a message, a destination, a source, a consumer or a batch of messages SHOULD be populated under the corresponding namespace: - -* `messaging.{system}.message`: Describes attributes for individual messages -* `messaging.{system}.destination` and `messaging.{system}.source`: Describe the destination and source a message (or a batch) are published to and received from respectively. The combination of attributes in these namespaces should uniquely identify the entity and include properties significant for this messaging system. For example, Kafka instrumentations should include partition identifier. -* `messaging.{system}.consumer`: Describes message consumer properties -* `messaging.{system}.batch`: Describes message batch properties - -#### RabbitMQ - -In RabbitMQ, the destination is defined by an *exchange* and a *routing key*. -`messaging.destination.name` MUST be set to the name of the exchange. This will be an empty string if the default exchange is used. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `messaging.rabbitmq.destination.routing_key` | string | RabbitMQ message routing key. | `myKey` | Conditionally Required: If not empty. | - - -#### Apache Kafka - -For Apache Kafka, the following additional attributes are defined: - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `messaging.kafka.message.key` | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message.id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [1] | `myKey` | Recommended | -| `messaging.kafka.consumer.group` | string | Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. | `my-group` | Recommended | -| `messaging.kafka.destination.partition` | int | Partition the message is sent to. | `2` | Recommended | -| `messaging.kafka.source.partition` | int | Partition the message is received from. | `2` | Recommended | -| `messaging.kafka.message.offset` | int | The offset of a record in the corresponding Kafka partition. | `42` | Recommended | -| `messaging.kafka.message.tombstone` | boolean | A boolean that is true if the message is a tombstone. | | Conditionally Required: [2] | - -**[1]:** If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value. - -**[2]:** If value is `true`. When missing, the value is assumed to be `false`. - - -For Apache Kafka producers, [`peer.service`](./span-general.md#general-remote-service-attributes) SHOULD be set to the name of the broker or service the message will be sent to. -The `service.name` of a Consumer's Resource SHOULD match the `peer.service` of the Producer, when the message is directly passed to another service. -If an intermediary broker is present, `service.name` and `peer.service` will not be the same. - -`messaging.client_id` SHOULD be set to the `client-id` of consumers, or to the `client.id` property of producers. - -#### Apache RocketMQ - -Specific attributes for Apache RocketMQ are defined below. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `messaging.rocketmq.namespace` | string | Namespace of RocketMQ resources, resources in different namespaces are individual. | `myNamespace` | Required | -| `messaging.rocketmq.client_group` | string | Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. | `myConsumerGroup` | Required | -| `messaging.rocketmq.message.delivery_timestamp` | int | The timestamp in milliseconds that the delay message is expected to be delivered to consumer. | `1665987217045` | Conditionally Required: [1] | -| `messaging.rocketmq.message.delay_time_level` | int | The delay time level for delay message, which determines the message delay time. | `3` | Conditionally Required: [2] | -| `messaging.rocketmq.message.group` | string | It is essential for FIFO message. Messages that belong to the same message group are always processed one by one within the same consumer group. | `myMessageGroup` | Conditionally Required: If the message type is FIFO. | -| `messaging.rocketmq.message.type` | string | Type of message. | `normal` | Recommended | -| `messaging.rocketmq.message.tag` | string | The secondary classifier of message besides topic. | `tagA` | Recommended | -| `messaging.rocketmq.message.keys` | string[] | Key(s) of message, another way to mark message besides message id. | `[keyA, keyB]` | Recommended | -| `messaging.rocketmq.consumption_model` | string | Model of message consumption. This only applies to consumer spans. | `clustering` | Recommended | - -**[1]:** If the message type is delay and delay time level is not specified. - -**[2]:** If the message type is delay and delivery timestamp is not specified. - -`messaging.rocketmq.message.type` MUST be one of the following: - -| Value | Description | -|---|---| -| `normal` | Normal message | -| `fifo` | FIFO message | -| `delay` | Delay message | -| `transaction` | Transaction message | - -`messaging.rocketmq.consumption_model` MUST be one of the following: - -| Value | Description | -|---|---| -| `clustering` | Clustering consumption model | -| `broadcasting` | Broadcasting consumption model | - - -`messaging.client_id` SHOULD be set to the client ID that is automatically generated by the Apache RocketMQ SDK. - -## Examples - -### Topic with multiple consumers - -Given is a process P, that publishes a message to a topic T on messaging system MS, and two processes CA and CB, which both receive the message and process it. - -``` -Process P: | Span Prod1 | --- -Process CA: | Span CA1 | --- -Process CB: | Span CB1 | -``` - -| Field or Attribute | Span Prod1 | Span CA1 | Span CB1 | -|-|-|-|-| -| Span name | `"T publish"` | `"T process"` | `"T process"` | -| Parent | | Span Prod1 | Span Prod1 | -| Links | | | | -| SpanKind | `PRODUCER` | `CONSUMER` | `CONSUMER` | -| Status | `Ok` | `Ok` | `Ok` | -| `server.address` | `"ms"` | `"ms"` | `"ms"` | -| `server.port` | `1234` | `1234` | `1234` | -| `messaging.system` | `"rabbitmq"` | `"rabbitmq"` | `"rabbitmq"` | -| `messaging.destination.name` | `"T"` | | | -| `messaging.source.name` | | `"T"` | `"T"` | -| `messaging.operation` | | `"process"` | `"process"` | -| `messaging.message.id` | `"a1"` | `"a1"`| `"a1"` | - -### Apache Kafka with Quarkus or Spring Boot Example - -Given is a process P, that publishes a message to a topic T1 on Apache Kafka. -One process, CA, receives the message and publishes a new message to a topic T2 that is then received and processed by CB. - -Frameworks such as Quarkus and Spring Boot separate processing of a received message from producing subsequent messages out. -For this reason, receiving (Span Rcv1) is the parent of both processing (Span Proc1) and producing a new message (Span Prod2). -The span representing message receiving (Span Rcv1) should not set `messaging.operation` to `receive`, -as it does not only receive the message but also converts the input message to something suitable for the processing operation to consume and creates the output message from the result of processing. - -``` -Process P: | Span Prod1 | --- -Process CA: | Span Rcv1 | - | Span Proc1 | - | Span Prod2 | --- -Process CB: | Span Rcv2 | -``` - -| Field or Attribute | Span Prod1 | Span Rcv1 | Span Proc1 | Span Prod2 | Span Rcv2 -|-|-|-|-|-|-| -| Span name | `"T1 publish"` | `"T1 receive"` | `"T1 process"` | `"T2 publish"` | `"T2 receive`" | -| Parent | | Span Prod1 | Span Rcv1 | Span Rcv1 | Span Prod2 | -| Links | | | | | | -| SpanKind | `PRODUCER` | `CONSUMER` | `CONSUMER` | `PRODUCER` | `CONSUMER` | -| Status | `Ok` | `Ok` | `Ok` | `Ok` | `Ok` | -| `peer.service` | `"myKafka"` | | | `"myKafka"` | | -| `service.name` | | `"myConsumer1"` | `"myConsumer1"` | | `"myConsumer2"` | -| `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | -| `messaging.destination.name` | `"T1"` | | | | | -| `messaging.source.name` | | `"T1"` | `"T1"` | `"T2"` | `"T2"` | -| `messaging.operation` | | | `"process"` | | `"receive"` | -| `messaging.client_id` | | `"5"` | `"5"` | `"5"` | `"8"` | -| `messaging.kafka.message.key` | `"myKey"` | `"myKey"` | `"myKey"` | `"anotherKey"` | `"anotherKey"` | -| `messaging.kafka.consumer.group` | | `"my-group"` | `"my-group"` | | `"another-group"` | -| `messaging.kafka.partition` | `"1"` | `"1"` | `"1"` | `"3"` | `"3"` | -| `messaging.kafka.message.offset` | `"12"` | `"12"` | `"12"` | `"32"` | `"32"` | - -### Batch receiving - -Given is a process P, that publishes two messages to a queue Q on messaging system MS, and a process C, which receives both of them in one batch (Span Recv1) and processes each message separately (Spans Proc1 and Proc2). - -Since a span can only have one parent and the propagated trace and span IDs are not known when the receiving span is started, the receiving span will have no parent and the processing spans are correlated with the producing spans using links. - -``` -Process P: | Span Prod1 | Span Prod2 | --- -Process C: | Span Recv1 | - | Span Proc1 | - | Span Proc2 | -``` - -| Field or Attribute | Span Prod1 | Span Prod2 | Span Recv1 | Span Proc1 | Span Proc2 | -|-|-|-|-|-|-| -| Span name | `"Q publish"` | `"Q publish"` | `"Q receive"` | `"Q process"` | `"Q process"` | -| Parent | | | | Span Recv1 | Span Recv1 | -| Links | | | | Span Prod1 | Span Prod2 | -| SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` | `CONSUMER` | `CONSUMER` | -| Status | `Ok` | `Ok` | `Ok` | `Ok` | `Ok` | -| `server.address` | `"ms"` | `"ms"` | `"ms"` | `"ms"` | `"ms"` | -| `server.port` | `1234` | `1234` | `1234` | `1234` | `1234` | -| `messaging.system` | `"rabbitmq"` | `"rabbitmq"` | `"rabbitmq"` | `"rabbitmq"` | `"rabbitmq"` | -| `messaging.destination.name` | `"Q"` | `"Q"` | | | | -| `messaging.source.name` | | | `"Q"` | `"Q"` | `"Q"` | -| `messaging.operation` | | | `"receive"` | `"process"` | `"process"` | -| `messaging.message.id` | `"a1"` | `"a2"` | | `"a1"` | `"a2"` | -| `messaging.batch.message_count` | | | 2 | | | - -### Batch processing - -Given is a process P, that publishes two messages to a queue Q on messaging system MS, and a process C, which receives them separately in two different operations (Span Recv1 and Recv2) and processes both messages in one batch (Span Proc1). - -Since each span can only have one parent, C3 should not choose a random parent out of C1 and C2, but rather rely on the implicitly selected parent as defined by the [tracing API spec](../api.md). -Depending on the implementation, the producing spans might still be available in the meta data of the messages and should be added to C3 as links. -The client library or application could also add the receiver span's SpanContext to the data structure it returns for each message. In this case, C3 could also add links to the receiver spans C1 and C2. - -The status of the batch processing span is selected by the application. Depending on the semantics of the operation. A span status `Ok` could, for example, be set only if all messages or if just at least one were properly processed. - -``` -Process P: | Span Prod1 | Span Prod2 | --- -Process C: | Span Recv1 | Span Recv2 | - | Span Proc1 | -``` - -| Field or Attribute | Span Prod1 | Span Prod2 | Span Recv1 | Span Recv2 | Span Proc1 | -|-|-|-|-|-|-| -| Span name | `"Q publish"` | `"Q publish"` | `"Q receive"` | `"Q receive"` | `"Q process"` | -| Parent | | | Span Prod1 | Span Prod2 | | -| Links | | | | | [Span Prod1, Span Prod2 ] | -| Link attributes | | | | | Span Prod1: `messaging.message.id`: `"a1"` | -| | | | | | Span Prod2: `messaging.message.id`: `"a2"` | -| SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` | `CONSUMER` | `CONSUMER` | -| Status | `Ok` | `Ok` | `Ok` | `Ok` | `Ok` | -| `server.address` | `"ms"` | `"ms"` | `"ms"` | `"ms"` | `"ms"` | -| `server.port` | `1234` | `1234` | `1234` | `1234` | `1234` | -| `messaging.system` | `"rabbitmq"` | `"rabbitmq"` | `"rabbitmq"` | `"rabbitmq"` | `"rabbitmq"` | -| `messaging.destination.name` | `"Q"` | `"Q"` | | | | -| `messaging.source.name` | | | `"Q"` | `"Q"` | `"Q"` | -| `messaging.operation` | | | `"receive"` | `"receive"` | `"process"` | -| `messaging.message.id` | `"a1"` | `"a2"` | `"a1"` | `"a2"` | | -| `messaging.batch.message_count` | | | 1 | 1 | 2 | diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md deleted file mode 100644 index 683c7acfc63..00000000000 --- a/specification/trace/semantic_conventions/rpc.md +++ /dev/null @@ -1,355 +0,0 @@ -# Semantic conventions for RPC spans - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -This document defines how to describe remote procedure calls -(also called "remote method invocations" / "RMI") with spans. - - - - - -- [Common remote procedure call conventions](#common-remote-procedure-call-conventions) - * [Span name](#span-name) - * [Common attributes](#common-attributes) - + [Service name](#service-name) - * [Client attributes](#client-attributes) - * [Server attributes](#server-attributes) - * [Events](#events) - * [Distinction from HTTP spans](#distinction-from-http-spans) -- [gRPC](#grpc) - * [gRPC Attributes](#grpc-attributes) - * [gRPC Status](#grpc-status) - * [gRPC Request and Response Metadata](#grpc-request-and-response-metadata) -- [Connect RPC conventions](#connect-rpc-conventions) - * [Connect RPC Attributes](#connect-rpc-attributes) - * [Connect RPC Status](#connect-rpc-status) - * [Connect RPC Request and Response Metadata](#connect-rpc-request-and-response-metadata) -- [JSON RPC](#json-rpc) - * [JSON RPC Attributes](#json-rpc-attributes) - - - -> **Warning** -> Existing RPC instrumentations that are using -> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/rpc.md) -> (or prior): -> -> * SHOULD NOT change the version of the networking attributes that they emit -> until the HTTP semantic conventions are marked stable (HTTP stabilization will -> include stabilization of a core set of networking attributes which are also used -> in RPC instrumentations). -> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` -> in the existing major version which supports the following values: -> * `none` - continue emitting whatever version of the old experimental -> networking attributes the instrumentation was emitting previously. -> This is the default value. -> * `http` - emit the new, stable networking attributes, -> and stop emitting the old experimental networking attributes -> that the instrumentation emitted previously. -> * `http/dup` - emit both the old and the stable networking attributes, -> allowing for a seamless transition. -> * SHOULD maintain (security patching at a minimum) the existing major version -> for at least six months after it starts emitting both sets of attributes. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). - -## Common remote procedure call conventions - -A remote procedure calls is described by two separate spans, one on the client-side and one on the server-side. - -For outgoing requests, the `SpanKind` MUST be set to `CLIENT` and for incoming requests to `SERVER`. - -Remote procedure calls can only be represented with these semantic conventions, when the names of the called service and method are known and available. - -### Span name - -The _span name_ MUST be the full RPC method name formatted as: - -``` -$package.$service/$method -``` - -(where $service MUST NOT contain dots and $method MUST NOT contain slashes) - -If there is no package name or if it is unknown, the `$package.` part (including the period) is omitted. - -Examples of span names: - -- `grpc.test.EchoService/Echo` -- `com.example.ExampleRmiService/exampleMethod` -- `MyCalcService.Calculator/Add` reported by the server and - `MyServiceReference.ICalculator/Add` reported by the client for .NET WCF calls -- `MyServiceWithNoPackage/theMethod` - -### Common attributes - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | -| `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended | -| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended | -| [`network.transport`](span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | -| [`network.type`](span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`server.address`](span-general.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | -| [`server.port`](span-general.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: See below | -| [`server.socket.address`](span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | See below | -| [`server.socket.port`](span-general.md) | int | Physical server port. | `16456` | Recommended: [4] | - -**[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). - -**[2]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). - -**[3]:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. - -**[4]:** If different than `server.port` and if `server.socket.address` is set. - -**Additional attribute requirements:** At least one of the following sets of attributes is required: - -* [`server.socket.address`](span-general.md) -* [`server.address`](span-general.md) - -`rpc.system` 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 | -|---|---| -| `grpc` | gRPC | -| `java_rmi` | Java RMI | -| `dotnet_wcf` | .NET WCF | -| `apache_dubbo` | Apache Dubbo | -| `connect_rpc` | Connect RPC | - - -For client-side spans `server.port` is required if the connection is IP-based and the port is available (it describes the server port they are connecting to). -For server-side spans `client.socket.port` is optional (it describes the port the client is connecting from). - -#### Service name - -On the server process receiving and handling the remote procedure call, the service name provided in `rpc.service` does not necessarily have to match the [`service.name`][] resource attribute. -One process can expose multiple RPC endpoints and thus have multiple RPC service names. From a deployment perspective, as expressed by the `service.*` resource attributes, it will be treated as one deployed service with one `service.name`. -Likewise, on clients sending RPC requests to a server, the service name provided in `rpc.service` does not have to match the [`peer.service`][] span attribute. - -As an example, given a process deployed as `QuoteService`, this would be the name that goes into the `service.name` resource attribute which applies to the entire process. -This process could expose two RPC endpoints, one called `CurrencyQuotes` (= `rpc.service`) with a method called `getMeanRate` (= `rpc.method`) and the other endpoint called `StockQuotes` (= `rpc.service`) with two methods `getCurrentBid` and `getLastClose` (= `rpc.method`). -In this example, spans representing client request should have their `peer.service` attribute set to `QuoteService` as well to match the server's `service.name` resource attribute. -Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service name. - -[network attributes]: span-general.md#server-and-client-attributes -[`service.name`]: ../../resource/semantic_conventions/README.md#service -[`peer.service`]: span-general.md#general-remote-service-attributes - -### Client attributes - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`server.socket.domain`](span-general.md) | string | The domain name of an immediate peer. [1] | `proxy.example.com` | Recommended: [2] | - -**[1]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. - -**[2]:** If different than `server.address` and if `server.socket.address` is set. - - -### Server attributes - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`client.address`](span-general.md) | string | Client address - unix domain socket name, IPv4 or IPv6 address. [1] | `/tmp/my.sock`; `10.1.2.80` | Recommended | -| [`client.port`](span-general.md) | int | Client port number [2] | `65123` | Recommended | -| [`client.socket.address`](span-general.md) | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | -| [`client.socket.port`](span-general.md) | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. | -| [`network.transport`](span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | -| [`network.type`](span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | - -**[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent client address behind any intermediaries (e.g. proxies) if it's available. - -**[2]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent client port behind any intermediaries (e.g. proxies) if it's available. - - -### Events - -In the lifetime of an RPC stream, an event for each message sent/received on -client and server spans SHOULD be created. In case of unary calls only one sent -and one received message will be recorded for both client and server spans. - - -The event name MUST be `message`. - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `message.type` | string | Whether this is a received or sent message. | `SENT` | Recommended | -| `message.id` | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] | | Recommended | -| `message.compressed_size` | int | Compressed size of the message in bytes. | | Recommended | -| `message.uncompressed_size` | int | Uncompressed size of the message in bytes. | | Recommended | - -**[1]:** This way we guarantee that the values will be consistent between different implementations. - -`message.type` MUST be one of the following: - -| Value | Description | -|---|---| -| `SENT` | sent | -| `RECEIVED` | received | - - -### Distinction from HTTP spans - -HTTP calls can generally be represented using just [HTTP spans](./http.md). -If they address a particular remote service and method known to the caller, i.e., when it is a remote procedure call transported over HTTP, the `rpc.*` attributes might be added additionally on that span, or in a separate RPC span that is a parent of the transporting HTTP call. -Note that _method_ in this context is about the called remote procedure and _not_ the HTTP verb (GET, POST, etc.). - -## gRPC - -For remote procedure calls via [gRPC][], additional conventions are described in this section. - -`rpc.system` MUST be set to `"grpc"`. - -### gRPC Attributes - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `rpc.grpc.status_code` | int | The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. | `0` | Required | - -`rpc.grpc.status_code` MUST be one of the following: - -| Value | Description | -|---|---| -| `0` | OK | -| `1` | CANCELLED | -| `2` | UNKNOWN | -| `3` | INVALID_ARGUMENT | -| `4` | DEADLINE_EXCEEDED | -| `5` | NOT_FOUND | -| `6` | ALREADY_EXISTS | -| `7` | PERMISSION_DENIED | -| `8` | RESOURCE_EXHAUSTED | -| `9` | FAILED_PRECONDITION | -| `10` | ABORTED | -| `11` | OUT_OF_RANGE | -| `12` | UNIMPLEMENTED | -| `13` | INTERNAL | -| `14` | UNAVAILABLE | -| `15` | DATA_LOSS | -| `16` | UNAUTHENTICATED | - - -[gRPC]: https://grpc.io/ - -### gRPC Status - -The table below describes when -the [Span Status](../api.md#set-status) MUST be set -to `Error` or remain unset -depending on the [gRPC status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) -and [Span Kind](../api.md#spankind). - -| gRPC Status Code | `SpanKind.SERVER` Span Status | `SpanKind.CLIENT` Span Status | -|---|---|---| -| OK | unset | unset | -| CANCELLED | unset | `Error` | -| UNKNOWN | `Error` | `Error` | -| INVALID_ARGUMENT | unset | `Error` | -| DEADLINE_EXCEEDED | `Error` | `Error` | -| NOT_FOUND | unset | `Error` | -| ALREADY_EXISTS | unset | `Error` | -| PERMISSION_DENIED | unset | `Error` | -| RESOURCE_EXHAUSTED | unset| `Error` | -| FAILED_PRECONDITION | unset | `Error` | -| ABORTED | unset | `Error` | -| OUT_OF_RANGE | unset | `Error` | -| UNIMPLEMENTED | `Error` | `Error` | -| INTERNAL | `Error` | `Error` | -| UNAVAILABLE | `Error` | `Error` | -| DATA_LOSS | `Error` | `Error` | -| UNAUTHENTICATED | unset | `Error` | - -### gRPC Request and Response Metadata - -| Attribute | Type | Description | Examples | Requirement Level | -|-------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|-------------------| -| `rpc.grpc.request.metadata.` | string[] | gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.grpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]` | Opt-In | -| `rpc.grpc.response.metadata.` | string[] | gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.grpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]` | Opt-In | - -**[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. -Including all request/response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. - -## Connect RPC conventions - -For remote procedure calls via [connect](http://connect.build), additional conventions are described in this section. - -`rpc.system` MUST be set to `"connect_rpc"`. - -### Connect RPC Attributes - -Below is a table of attributes that SHOULD be included on client and server RPC measurements when `rpc.system` is `"connect_rpc"`. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `rpc.connect_rpc.error_code` | string | The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values. | `cancelled` | Conditionally Required: [1] | - -**[1]:** If response is not successful and if error code available. - -`rpc.connect_rpc.error_code` MUST be one of the following: - -| Value | Description | -|---|---| -| `cancelled` | cancelled | -| `unknown` | unknown | -| `invalid_argument` | invalid_argument | -| `deadline_exceeded` | deadline_exceeded | -| `not_found` | not_found | -| `already_exists` | already_exists | -| `permission_denied` | permission_denied | -| `resource_exhausted` | resource_exhausted | -| `failed_precondition` | failed_precondition | -| `aborted` | aborted | -| `out_of_range` | out_of_range | -| `unimplemented` | unimplemented | -| `internal` | internal | -| `unavailable` | unavailable | -| `data_loss` | data_loss | -| `unauthenticated` | unauthenticated | - - -### Connect RPC Status - -If `rpc.connect_rpc.error_code` is set, [Span Status](../api.md#set-status) MUST be set to `Error` and left unset in all other cases. - -### Connect RPC Request and Response Metadata - -| Attribute | Type | Description | Examples | Requirement Level | -|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|-------------------| -| `rpc.connect_rpc.request.metadata.` | string[] | Connect request metadata, `` being the normalized Connect Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]` | Optional | -| `rpc.connect_rpc.response.metadata.` | string[] | Connect response metadata, `` being the normalized Connect Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]` | Optional | - -**[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. -Including all request/response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. - -## JSON RPC - -Conventions specific to [JSON RPC](https://www.jsonrpc.org/). - -`rpc.system` MUST be set to `"jsonrpc"`. - -### JSON RPC Attributes - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `rpc.jsonrpc.version` | string | Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 does not specify this, the value can be omitted. | `2.0`; `1.0` | Conditionally Required: If other than the default version (`1.0`) | -| `rpc.jsonrpc.request_id` | string | `id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. | `10`; `request-7`; `` | Recommended | -| `rpc.jsonrpc.error_code` | int | `error.code` property of response if it is an error response. | `-32700`; `100` | Conditionally Required: If response is not successful. | -| `rpc.jsonrpc.error_message` | string | `error.message` property of response if it is an error response. | `Parse error`; `User already exists` | Recommended | -| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [1] | `exampleMethod` | Required | - -**[1]:** This is always required for jsonrpc. See the note in the general RPC conventions for more information. - diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md deleted file mode 100644 index a812800297e..00000000000 --- a/specification/trace/semantic_conventions/span-general.md +++ /dev/null @@ -1,385 +0,0 @@ -# General attributes - -**NOTICE** Semantic Conventions are moving to a -[new location](http://github.com/open-telemetry/semantic-conventions). - -No changes to this document are allowed. - -**Status**: [Experimental](../../document-status.md) - -The attributes described in this section are not specific to a particular operation but rather generic. -They may be used in any Span they apply to. -Particular operations may refer to or require some of these attributes. - - - - - -- [Server and client attributes](#server-and-client-attributes) - * [Server attributes](#server-attributes) - + [`server.address`](#serveraddress) - + [`server.socket.*` attributes](#serversocket-attributes) - * [Client attributes](#client-attributes) - + [Connecting through intermediary](#connecting-through-intermediary) -- [Network attributes](#network-attributes) - * [Source and destination attributes](#source-and-destination-attributes) - + [Source](#source) - + [Destination](#destination) - * [Network connection and carrier attributes](#network-connection-and-carrier-attributes) -- [General remote service attributes](#general-remote-service-attributes) -- [General identity attributes](#general-identity-attributes) -- [General thread attributes](#general-thread-attributes) -- [Source Code Attributes](#source-code-attributes) - - - -## Server and client attributes - -These attributes may be used to describe the client and server in a connection-based network interaction -where there is one side that initiates the connection (the client is the side that initiates the connection). -This covers all TCP network interactions since TCP is connection-based and one side initiates the -connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the -protocol / API does not expose a clear notion of client and server). -This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS. - -In an ideal situation, not accounting for proxies, multiple IP addresses or host names, -the `server.*` attributes are the same on the client and server. - -### Server attributes - -> **Warning** -> Attributes in this section are in use by the HTTP semantic conventions. -Once the HTTP semantic conventions are declared stable, changes to the attributes in this section will only be allowed -if they do not cause breaking changes to HTTP semantic conventions. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `server.address` | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | Recommended | -| `server.port` | int | Logical server port number | `80`; `8080`; `443` | Recommended | -| `server.socket.domain` | string | The domain name of an immediate peer. [1] | `proxy.example.com` | Recommended | -| `server.socket.address` | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. | -| `server.socket.port` | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | - -**[1]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. - - -`server.address` and `server.port` represent logical server name and port. Semantic conventions that refer to these attributes SHOULD -specify what these attributes mean in their context. - -Semantic conventions and instrumentations that populate both logical (`server.address` and `server.port`) and socket-level (`server.socket.*`) attributes SHOULD set socket-level attributes only when they don't match logical ones. For example, when direct connection to the remote destination is established and `server.address` is populated, `server.socket.domain` SHOULD NOT be set. Check out [Connecting through intermediary](#connecting-through-intermediary) for more information. - -#### `server.address` - -For IP-based communication, the name should be a DNS host name of the service. On client side it matches remote service name, on server side, it represents local service name as seen externally on clients. - -When connecting to an URL `https://example.com/foo`, `server.address` matches `"example.com"` on both client and server side. - -On client side, it's usually passed in form of URL, connection string, host name, etc. Sometimes host name is only available to instrumentation as a string which may contain DNS name or IP address. `server.address` SHOULD be set to the available known hostname (e.g., `"127.0.0.1"` if connecting to an URL `https://127.0.0.1/foo`). - -If only IP address is available, it should be populated on `server.address`. Reverse DNS lookup SHOULD NOT be used to obtain DNS name. - -If `network.transport` is `"pipe"`, the absolute path to the file representing it should be used as `server.address`. -If there is no such file (e.g., anonymous pipe), -the name should explicitly be set to the empty string to distinguish it from the case where the name is just unknown or not covered by the instrumentation. - -For Unix domain socket, `server.address` attribute represents remote endpoint address on the client side and local endpoint address on the server side. - -#### `server.socket.*` attributes - -_Note: this section applies to socket connections visible to instrumentations. Instrumentations have limited knowledge about intermediaries communications goes through such as [transparent proxies](https://www.rfc-editor.org/rfc/rfc3040.html#section-2.5) or VPN servers. Higher-level instrumentations such as HTTP don't always have access to the socket-level information and may not be able to populate socket-level attributes._ - -Socket-level attributes identify peer and host that are directly connected to each other. Since instrumentations may have limited knowledge on network information, instrumentations SHOULD populate such attributes to the best of their knowledge when populate them at all. - -_Note: Specific structures and methods to obtain socket-level attributes are mentioned here only as examples. Instrumentations would usually use Socket API provided by their environment or sockets implementations._ - -For IP-based communication, `server.socket.domain` represents either fully qualified domain name of immediate peer and `server.socket.address` to the IP address (or one specific to network family). - -`server.socket.domain`, `server.socket.address`, and `server.socket.port` describe server side of socket communication. For example, when connecting using `connect(2)` -on [Linux](https://man7.org/linux/man-pages/man2/connect.2.html) or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-connect) -with `AF_INET` address family, they represent `sin_addr` and `sin_port` fields of [`sockaddr_in`](https://man7.org/linux/man-pages/man7/ip.7.html) structure. - -On client side, address and port can be obtained by calling `getpeername` method on [Linux](https://man7.org/linux/man-pages/man2/getpeername.2.html) or -[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getpeername). - -On server side address and port can be obtained by calling `getsockname` method on [Linux](https://man7.org/linux/man-pages/man2/getsockname.2.html) or -[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getsockname). - -`server.socket.port` SHOULD only be populated for families that have notion of port. - -### Client attributes - -> **Warning** -> Attributes in this section are in use by the HTTP semantic conventions. -Once the HTTP semantic conventions are declared stable, changes to the attributes in this section will only be allowed -if they do not cause breaking changes to HTTP semantic conventions. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `client.address` | string | Client address - unix domain socket name, IPv4 or IPv6 address. [1] | `/tmp/my.sock`; `10.1.2.80` | Recommended | -| `client.port` | int | Client port number [2] | `65123` | Recommended | -| `client.socket.address` | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | -| `client.socket.port` | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. | - -**[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent client address behind any intermediaries (e.g. proxies) if it's available. - -**[2]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent client port behind any intermediaries (e.g. proxies) if it's available. - - -`client.socket.address` and `client.socket.port` represent physical client name and port. - -For IP-based communication, the `client.socket.address` should be a IP address, Unix domain name, or another address specific to network type. - -On server side, `client.socket.address` identifies the direct peer endpoint socket address. For example, when using `bind(2)` -on [Linux](https://man7.org/linux/man-pages/man2/bind.2.html) or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-bind) -with `AF_INET` address family, represent `sin_addr` and `sin_port` fields of `sockaddr_in` structure. - -On client side it represents local socket address and port can be obtained by calling `getsockname` method on [Linux](https://man7.org/linux/man-pages/man2/getsockname.2.html), -[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getsockname). - -#### Connecting through intermediary - -When connecting to the remote destination through an intermediary (e.g. proxy), client instrumentations SHOULD set `server.address` and `server.port` to logical remote destination address and `server.socket.name`, `server.socket.address` and `server.socket.port` to the socket peer connection is established with - the intermediary. - -`server.socket.domain` SHOULD be set to the DNS name used to resolve `server.socket.address` if it's readily available. Instrumentations -SHOULD NOT do DNS lookups to obtain `server.socket.address`. If peer information available to instrumentation -can represent DNS name or IP address, instrumentation SHOULD NOT attempt to parse it and SHOULD only set `server.socket.domain`. - -_Note: Telemetry consumers can obtain IP address from telemetry item by first checking `server.socket.address` and if not present, falling back to `server.socket.domain`._ - -For example, [URL Host component](https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2) can contain IP address or DNS name and -instrumentations that don't have access to socket-level communication can only populate `server.socket.domain`. -Instrumentations that have access to socket connection, may be able to populate valid `server.socket.address` instead of or -in addition to DNS name. - -Server instrumentations that leverage `client.address` and `client.port` attributes SHOULD set them to originating client address and port behind all proxies if this information is available. -The `client.socket.address` and `client.socket.port` attributes then SHOULD contain immediate client peer address and port. - -If only immediate peer information is available, it should be set on `client.address` and `client.port` and `client.socket.*` attributes SHOULD NOT be set. - -## Network attributes - -> **Warning** -> Attributes in this section are in use by the HTTP semantic conventions. -Once the HTTP semantic conventions are declared stable, changes to the attributes in this section will only be allowed -if they do not cause breaking changes to HTTP semantic conventions. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `network.transport` | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | -| `network.type` | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| `network.protocol.name` | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| `network.protocol.version` | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | - -**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. - -`network.transport` 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 | -|---|---| -| `tcp` | TCP | -| `udp` | UDP | -| `pipe` | Named or anonymous pipe. See note below. | -| `unix` | Unix domain socket | - -`network.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 | -|---|---| -| `ipv4` | IPv4 | -| `ipv6` | IPv6 | - - -### Source and destination attributes - -These attributes may be used to describe the sender and receiver of a network exchange/packet. These should be used -when there is no client/server relationship between the two sides, or when that relationship is unknown. -This covers low-level network interactions (e.g. packet tracing) where you don't know if -there was a connection or which side initiated it. -This also covers unidirectional UDP flows and peer-to-peer communication where the -"user-facing" surface of the protocol / API does not expose a clear notion of client and server. - -#### Source - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `source.domain` | string | The domain name of the source system. [1] | `foo.example.com` | Recommended | -| `source.address` | string | Source address, for example IP address or Unix socket name. | `10.5.3.2` | Recommended | -| `source.port` | int | Source port number | `3389`; `2888` | Recommended | - -**[1]:** This value may be a host name, a fully qualified domain name, or another host naming format. - - -#### Destination - -Destination fields capture details about the receiver of a network exchange/packet. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `destination.domain` | string | The domain name of the destination system. [1] | `foo.example.com` | Recommended | -| `destination.address` | string | Peer address, for example IP address or UNIX socket name. | `10.5.3.2` | Recommended | -| `destination.port` | int | Peer port number | `3389`; `2888` | Recommended | - -**[1]:** This value may be a host name, a fully qualified domain name, or another host naming format. - - -### Network connection and carrier attributes - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `network.connection.type` | string | The internet connection type. | `wifi` | Recommended | -| `network.connection.subtype` | string | This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. | `LTE` | Recommended | -| `network.carrier.name` | string | The name of the mobile carrier. | `sprint` | Recommended | -| `network.carrier.mcc` | string | The mobile carrier country code. | `310` | Recommended | -| `network.carrier.mnc` | string | The mobile carrier network code. | `001` | Recommended | -| `network.carrier.icc` | string | The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. | `DE` | Recommended | - -`network.connection.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 | -|---|---| -| `wifi` | wifi | -| `wired` | wired | -| `cell` | cell | -| `unavailable` | unavailable | -| `unknown` | unknown | - -`network.connection.subtype` 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 | -|---|---| -| `gprs` | GPRS | -| `edge` | EDGE | -| `umts` | UMTS | -| `cdma` | CDMA | -| `evdo_0` | EVDO Rel. 0 | -| `evdo_a` | EVDO Rev. A | -| `cdma2000_1xrtt` | CDMA2000 1XRTT | -| `hsdpa` | HSDPA | -| `hsupa` | HSUPA | -| `hspa` | HSPA | -| `iden` | IDEN | -| `evdo_b` | EVDO Rev. B | -| `lte` | LTE | -| `ehrpd` | EHRPD | -| `hspap` | HSPAP | -| `gsm` | GSM | -| `td_scdma` | TD-SCDMA | -| `iwlan` | IWLAN | -| `nr` | 5G NR (New Radio) | -| `nrnsa` | 5G NRNSA (New Radio Non-Standalone) | -| `lte_ca` | LTE CA | - - -For `Unix` and `pipe`, since the connection goes over the file system instead of being directly to a known peer, `server.address` is the only attribute that usually makes sense (see description of `server.address` below). - -## General remote service attributes - -This attribute may be used for any operation that accesses some remote service. -Users can define what the name of a service is based on their particular semantics in their distributed system. -Instrumentations SHOULD provide a way for users to configure this name. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `peer.service` | string | The [`service.name`](../../resource/semantic_conventions/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. | `AuthTokenCache` | Recommended | - - -Examples of `peer.service` that users may specify: - -- A Redis cache of auth tokens as `peer.service="AuthTokenCache"`. -- A gRPC service `rpc.service="io.opentelemetry.AuthService"` may be hosted in both a gateway, `peer.service="ExternalApiService"` and a backend, `peer.service="AuthService"`. - -## General identity attributes - -These attributes may be used for any operation with an authenticated and/or authorized enduser. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `enduser.id` | string | Username or client_id extracted from the access token or [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) header in the inbound request from outside the system. | `username` | Recommended | -| `enduser.role` | string | Actual/assumed role the client is making the request under extracted from token or application security context. | `admin` | Recommended | -| `enduser.scope` | string | Scopes or granted authorities the client currently possesses extracted from token or application security context. The value would come from the scope associated with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3) or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). | `read:message, write:files` | Recommended | - - -These attributes describe the authenticated user driving the user agent making requests to the instrumented -system. It is expected this information would be propagated unchanged from node-to-node within the system -using the Baggage mechanism. These attributes should not be used to record system-to-system -authentication attributes. - -Examples of where the `enduser.id` value is extracted from: - -| Authentication protocol | Field or description | -| :---------------------- | :------------------------------ | -| [HTTP Basic/Digest Authentication] | `username` | -| [OAuth 2.0 Bearer Token] | [OAuth 2.0 Client Identifier] value from `client_id` for the [OAuth 2.0 Client Credentials Grant] flow and `subject` or `username` from get token info response for other flows using opaque tokens. | -| [OpenID Connect 1.0 IDToken] | `sub` | -| [SAML 2.0 Assertion] | `urn:oasis:names:tc:SAML:2.0:assertion:Subject` | -| [Kerberos] | `PrincipalName` | - -| Framework | Field or description | -| :---------------------- | :------------------------------ | -| [JavaEE/JakartaEE Servlet] | `javax.servlet.http.HttpServletRequest.getUserPrincipal()` | -| [Windows Communication Foundation] | `ServiceSecurityContext.Current.PrimaryIdentity` | - -[Authorization]: https://tools.ietf.org/html/rfc7235#section-4.2 -[OAuth 2.0 Access Token]: https://tools.ietf.org/html/rfc6749#section-3.3 -[SAML 2.0 Assertion]: http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html -[HTTP Basic/Digest Authentication]: https://tools.ietf.org/html/rfc2617 -[OAuth 2.0 Bearer Token]: https://tools.ietf.org/html/rfc6750 -[OAuth 2.0 Client Identifier]: https://tools.ietf.org/html/rfc6749#section-2.2 -[OAuth 2.0 Client Credentials Grant]: https://tools.ietf.org/html/rfc6749#section-4.4 -[OpenID Connect 1.0 IDToken]: https://openid.net/specs/openid-connect-core-1_0.html#IDToken -[Kerberos]: https://tools.ietf.org/html/rfc4120 -[JavaEE/JakartaEE Servlet]: https://jakarta.ee/specifications/platform/8/apidocs/javax/servlet/http/HttpServletRequest.html -[Windows Communication Foundation]: https://docs.microsoft.com/en-us/dotnet/api/system.servicemodel.servicesecuritycontext?view=netframework-4.8 - -Given the sensitive nature of this information, SDKs and exporters SHOULD drop these attributes by -default and then provide a configuration parameter to turn on retention for use cases where the -information is required and would not violate any policies or regulations. - -## General thread attributes - -These attributes may be used for any operation to store information about -a thread that started a span. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `thread.id` | int | Current "managed" thread ID (as opposed to OS thread ID). | `42` | Recommended | -| `thread.name` | string | Current thread name. | `main` | Recommended | - - -Examples of where `thread.id` and `thread.name` can be extracted from: - -| Language or platform | `thread.id` | `thread.name` | -|-----------------------|----------------------------------------|------------------------------------| -| JVM | `Thread.currentThread().getId()` | `Thread.currentThread().getName()` | -| .NET | `Thread.CurrentThread.ManagedThreadId` | `Thread.CurrentThread.Name` | -| Python | `threading.current_thread().ident` | `threading.current_thread().name` | -| Ruby | `Thread.current.object_id` | `Thread.current.name` | -| C++ | `std::this_thread::get_id()` | | -| Erlang | `erlang:system_info(scheduler_id)` | | - -## Source Code Attributes - -Often a span is closely tied to a certain unit of code that is logically responsible for handling -the operation that the span describes (usually the method that starts the span). -For an HTTP server span, this would be the function that handles the incoming request, for example. -The attributes listed below allow to report this unit of code and therefore to provide more context -about the span. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `code.function` | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `serveRequest` | Recommended | -| `code.namespace` | string | The "namespace" within which `code.function` is defined. Usually the qualified class or module name, such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit. | `com.example.MyHttpService` | Recommended | -| `code.filepath` | string | The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). | `/usr/local/MyApplication/content_root/app/index.php` | Recommended | -| `code.lineno` | int | The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `42` | Recommended | -| `code.column` | int | The column number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `16` | Recommended | - \ No newline at end of file diff --git a/supplementary-guidelines/compatibility/aws.md b/supplementary-guidelines/compatibility/aws.md index c5091435d88..a7a59a37970 100644 --- a/supplementary-guidelines/compatibility/aws.md +++ b/supplementary-guidelines/compatibility/aws.md @@ -38,5 +38,5 @@ The following formats are currently natively supported by AWS services for propa AWS service-supported context propagation is necessary to allow context propagation through AWS managed services, for example: `S3 -> SNS -> SQS -> Lambda`. -(See the [aws-lambda sqs-event semantic convention](../../specification/trace/semantic_conventions/instrumentation/aws-lambda.md#sqs-event) +(See the [aws-lambda sqs-event semantic convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/faas/aws-lambda.md#sqs-event) doc for details on how this context propagation is consumed by Lambda instrumentation.)