diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index f541bc6faa..72eac076ba 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -6,13 +6,13 @@ # # Learn about membership in OpenTelemetry community: # https://github.com/open-telemetry/community/blob/main/community-membership.md -# # -# Learn about CODEOWNERS file format: -# https://help.github.com/en/articles/about-code-owners +# +# Learn about CODEOWNERS file format: +# https://help.github.com/articles/about-code-owners # -# Global owners, will be the owners for everything in the repo. Membership is tracked via https://github.com/open-telemetry/community/blob/main/community-members.md +# Global owners, will be the owners for everything in the repo. Membership is tracked via https://github.com/open-telemetry/community/blob/main/community-members.md * @open-telemetry/specs-semconv-maintainers @open-telemetry/specs-semconv-approvers # Schemas and schema file tooling @@ -34,6 +34,21 @@ # HTTP semantic conventions approvers /model/metrics/http.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers /model/trace/http.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +/model/registry/http.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +/model/registry/server.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +/model/registry/client.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +/model/registry/network.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +/model/registry/error.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +/model/registry/url.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +/model/registry/user-agent.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +/docs/http/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +/docs/attribute-registry/http.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +/docs/attribute-registry/server.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +/docs/attribute-registry/client.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +/docs/attribute-registry/network.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +/docs/attribute-registry/error.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +/docs/attribute-registry/url.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers +/docs/attribute-registry/user-agent.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers # System semantic conventions approvers /docs/system/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers @@ -45,4 +60,17 @@ /docs/mobile/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-mobile-approvers /model/logs/mobile* @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-mobile-approvers -# TODO - Add semconv area experts +# K8s semantic conventions approvers +/docs/resource/k8s.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers +/docs/attributes-registry/k8s.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers +/model/resource/k8s.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers +/model/registry/k8s.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers + +# Container semantic conventions approvers +/docs/resource/container.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers +/docs/attributes-registry/container.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers +/docs/attributes-registry/oci.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers +/model/resource/container.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers +/model/registry/container.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers +/model/registry/oci.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers + diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index 4ae744dcbe..a387a9db22 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -2,9 +2,7 @@ name: Checks on: push: - branches: [ main ] pull_request: - branches: [ main ] jobs: markdownlint: diff --git a/CHANGELOG.md b/CHANGELOG.md index 64d9b2c8ba..bc899cc299 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,8 +9,114 @@ release. ### Breaking +- Update `jvm.gc.duration` histogram buckets to `[ 0.01, 0.1, 1, 10 ]` + ([#317](https://github.com/open-telemetry/semantic-conventions/pull/317)) +- BREAKING: Change type of `host.cpu.model.id` and `host.cpu.model.family` to string. + ([#495](https://github.com/open-telemetry/semantic-conventions/issues/495)) +- Changed `messaging.system` attribute type to an open enum + ([#517](https://github.com/open-telemetry/semantic-conventions/pull/517)) +- Rename metrics `jvm.memory.usage` to `jvm.memory.used` and `jvm.memory.usage_after_last_gc` + to `jvm.memory.used_after_last_gc` + ([#536](https://github.com/open-telemetry/semantic-conventions/pull/536)) +- BREAKING: Change `event.name` definition to include `namespace` and remove `event.domain` from log event attributes. + ([#473](https://github.com/open-telemetry/semantic-conventions/pull/473)) +- BREAKING: Change `system.disk.io.direction` and `system.network.io.direction` + to global attributes `disk.io.direction` and `network.io.direction` + ([#530](https://github.com/open-telemetry/semantic-conventions/pull/530)) + ### Features +- Adds `labels` attribute to `k8s.pod` resource + ([#494](https://github.com/open-telemetry/semantic-conventions/pull/494)) +- Add `code.stacktrace` attribute + ([#435](https://github.com/open-telemetry/semantic-conventions/pull/435)) +- Add `http.flavor` and `http.user_agent` to list of deprecated attributes + ([#503](https://github.com/open-telemetry/semantic-conventions/pull/503)) +- Add Semantic conventions for TLS/SSL encrypted communication. + ([#21](https://github.com/open-telemetry/semantic-conventions/pull/21)) +- Add `messaging.gcp_pubsub.message.ordering_key` attribute. + ([#528](https://github.com/open-telemetry/semantic-conventions/pull/528)) +- Add `db.instance.id` attribute. + ([#345](https://github.com/open-telemetry/semantic-conventions/pull/345)) +- Add messaging metrics + ([#163](https://github.com/open-telemetry/semantic-conventions/pull/163)) + +### Fixes + +- Remove misleading pluralization wording related to count metrics + ([#488](https://github.com/open-telemetry/semantic-conventions/pull/488)) +- Remove no longer relevant Oct 1 mention from `OTEL_SEMCONV_STABILITY_OPT_IN` + ([#541](https://github.com/open-telemetry/semantic-conventions/pull/541)) + +## v1.23.0 (2023-11-03) + +This release marks the first where the core of HTTP semantic conventions have +stabilized. + +### Breaking + +- BREAKING: Rename http.resend_count to http.request.resend_count. + ([#374](https://github.com/open-telemetry/semantic-conventions/pull/374)) +- BREAKING: Change `network.protocol.name` from recommended to opt-in in HTTP semconv. + ([#398](https://github.com/open-telemetry/semantic-conventions/pull/398)) +- BREAKING: Define url.scheme in terms of logical operation in HTTP server semconv. + ([#376](https://github.com/open-telemetry/semantic-conventions/pull/376)) +- BREAKING: Change `network.transport` from recommended to opt-in in HTTP semconv. + ([#402](https://github.com/open-telemetry/semantic-conventions/pull/402)) +- BREAKING: Change `network.type` from recommended to opt-in in HTTP semconv. + ([#410](https://github.com/open-telemetry/semantic-conventions/pull/410)) +- BREAKING: Factor in `X-Forwarded-Host` / `Forwarded` when capturing `server.address` and `server.port`. + ([#411](https://github.com/open-telemetry/semantic-conventions/pull/411)) +- Remove `thread.daemon`, and introduce `jvm.thread.daemon` instead. + Introduce `jvm.thread.state` attribute and add it to `jvm.thread.count` metric. + ([#297](https://github.com/open-telemetry/semantic-conventions/pull/297)) +- Fix `server.port` to be not required when `server.address` is not set. + ([#429](https://github.com/open-telemetry/semantic-conventions/pull/429)) +- Use seconds as default duration for FaaS duration histograms + ([#384](https://github.com/open-telemetry/semantic-conventions/pull/384)) +- BREAKING: Remove `total` from list of well-known values of `system.memory.state` attribute. + ([#409](https://github.com/open-telemetry/semantic-conventions/pull/409)) +- Remove `url.path` default value. + ([#462](https://github.com/open-telemetry/semantic-conventions/pull/462)) +- Remove conditional requirement on `network.peer.address` and `network.peer.port` + ([#449](https://github.com/open-telemetry/semantic-conventions/pull/449)) +- Change `user_agent.original` from recommended to opt-in on HTTP client spans. + ([#468](https://github.com/open-telemetry/semantic-conventions/pull/468)) +- Change `http.request.body.size` and `http.response.body.size` + from recommended to opt-in. + ([#460](https://github.com/open-telemetry/semantic-conventions/pull/460)) +- Clarify that `client.port` is the port of whichever client was captured in `client.address`. + ([#471](https://github.com/open-telemetry/semantic-conventions/pull/471)) +- Change `client.port` from recommended to opt-in on HTTP server spans + ([#472](https://github.com/open-telemetry/semantic-conventions/pull/472)) +- BREAKING: Make `url.scheme` opt_in for HTTP client and remove default value for + `server.port` making it required on the client. + ([#459](https://github.com/open-telemetry/semantic-conventions/pull/459)) +- Make `client.address` sampling relevant on HTTP server spans. + ([#469](https://github.com/open-telemetry/semantic-conventions/pull/469)) +- Change `network.protocol.name` from opt-in to conditionally required. + ([#478](https://github.com/open-telemetry/semantic-conventions/pull/478)) +- Remove outdated `http.request.header.host` guidance + ([#479](https://github.com/open-telemetry/semantic-conventions/pull/479)) +- Change sampling relevant from `MUST` to `SHOULD` + ([#486](https://github.com/open-telemetry/semantic-conventions/pull/486)) +- Make `user_agent.original` and `http.request.header.*` sampling relevant + on HTTP server spans. + ([#467](https://github.com/open-telemetry/semantic-conventions/pull/467)) + +### Features + +- Adds `session.previous_id` to session.md + ([#348](https://github.com/open-telemetry/semantic-conventions/pull/348)) +- Metric namespaces SHOULD NOT be pluralized. + ([#267](https://github.com/open-telemetry/opentelemetry-specification/pull/267)) +- Add opt-in `system.memory.limit` metric. + ([#409](https://github.com/open-telemetry/semantic-conventions/pull/409)) +- Add `host.mac` resource attribute convention. + ([#340](https://github.com/open-telemetry/semantic-conventions/pull/340)) +- Mark HTTP semantic conventions as stable. + ([#377](https://github.com/open-telemetry/semantic-conventions/pull/377)) + ### Fixes - Clarify that `error.type` should be the fully-qualified exception class name @@ -18,12 +124,24 @@ release. ([#387](https://github.com/open-telemetry/semantic-conventions/pull/387)) - Add cardinality warning about two opt-in HTTP metric attributes ([#401](https://github.com/open-telemetry/semantic-conventions/pull/401)) +- Change `server.port` from recommended to conditionally required on HTTP server semconv. + ([#399](https://github.com/open-telemetry/semantic-conventions/pull/399)) +- Add cardinality warning about two opt-in HTTP metric attributes to all HTTP metrics. + ([#412](https://github.com/open-telemetry/semantic-conventions/pull/412)) +- Remove outdated note about not recording HTTP `server.address` when only IP address available. + ([#413](https://github.com/open-telemetry/semantic-conventions/pull/413)) +- Clarify HTTP server definitions and `server.address|port` notes. + ([#423](https://github.com/open-telemetry/semantic-conventions/pull/423)) +- Change the precedence between `:authority` and `Host` headers when populating + `server.address` and `server.port` attributes. + ([#455](https://github.com/open-telemetry/semantic-conventions/pull/455)) +- Explain `deployment.environment` impact on service identity. ([#481](https://github.com/open-telemetry/semantic-conventions/pull/481)) ## v1.22.0 (2023-10-12) - Remove experimental Kafka metrics ([#338](https://github.com/open-telemetry/semantic-conventions/pull/338)) - Adds `session.id` and session.md to general docs and model -([#215](https://github.com/open-telemetry/semantic-conventions/pull/215)) + ([#215](https://github.com/open-telemetry/semantic-conventions/pull/215)) - Add `container.labels.` attributes. ([#125](https://github.com/open-telemetry/semantic-conventions/pull/125)) - Add `cluster.name` and `node.name` attributes to Elasticsearch semantic conventions. @@ -149,10 +267,15 @@ release. - BREAKING: Rename `telemetry.auto.version` resource attribute to `telemetry.distro.version` and add `telemetry.distro.name` resource attribute ([#178](https://github.com/open-telemetry/semantic-conventions/pull/178)) +- Add `system.cpu.frequency` metric. + ([#337](https://github.com/open-telemetry/semantic-conventions/pull/337)) - Improve HTTP metric briefs. ([#366](https://github.com/open-telemetry/semantic-conventions/pull/366)) - Add `host.ip` resource attribute convention. ([#203](https://github.com/open-telemetry/semantic-conventions/pull/203)) +- BREAKING: remove `-` to `_` normalization from http header and rpc metadata + attribute keys. + ([#369](https://github.com/open-telemetry/semantic-conventions/pull/369)) - BREAKING: Rename/replace `(client|server).socket.(address|port)` attributes with `network.(peer|local).(address|port)`. ([#342](https://github.com/open-telemetry/semantic-conventions/pull/342)) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3e4d9addaa..2ab5ce406e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,6 +30,8 @@ key, but non-obvious, aspects: defined in a schema file. As part of any contribution, you should include attribute changes defined in the `schema-next.yaml` file. For details, please read [the schema specification](https://opentelemetry.io/docs/specs/otel/schemas/). +- Links to the specification repository MUST point to a tag and **not** to the `main` branch. + The tag version MUST match with the one defined in [README](README.md). - After creating a pull request, please update the [CHANGELOG](CHANGELOG.md) file with a description of your changes. @@ -161,14 +163,14 @@ make misspell-correction A PR (pull request) is considered to be **ready to merge** when: -* It has received at least two approvals from the [code +- It has received at least two approvals from the [code owners](./.github/CODEOWNERS) (if approvals are from only one company, they won't count). -* There is no `request changes` from the [code owners](./.github/CODEOWNERS). -* It has been at least two working days since the last modification (except for +- There is no `request changes` from the [code owners](./.github/CODEOWNERS). +- It has been at least two working days since the last modification (except for the trivial updates, such like typo, cosmetic, rebase, etc.). This gives people reasonable time to review. -* Trivial changes (typos, cosmetic changes, CI improvements, etc.) don't have to +- Trivial changes (typos, cosmetic changes, CI improvements, etc.) don't have to wait for two days. Any [maintainer](./README.md#contributing) can merge the PR once it is **ready diff --git a/Makefile b/Makefile index c6d956424b..acbb7f7de7 100644 --- a/Makefile +++ b/Makefile @@ -8,7 +8,7 @@ MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY) # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates # Keep links in model/README.md and .vscode/settings.json in sync! -SEMCONVGEN_VERSION=0.22.0 +SEMCONVGEN_VERSION=0.23.0 # TODO: add `yamllint` step to `all` after making sure it works on Mac. .PHONY: all @@ -90,13 +90,13 @@ yamllint: .PHONY: table-generation table-generation: docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec \ - otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec + otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec --md-use-badges --md-stable # Check if current markdown tables differ from the ones that would be generated from YAML definitions .PHONY: table-check table-check: docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec \ - otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec --md-check + otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec --md-check --md-use-badges --md-stable .PHONY: schema-check schema-check: diff --git a/README.md b/README.md index dd38f511dc..4584d9d648 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,16 @@ -# OpenTelemetry Semantic Conventions +# OpenTelemetry Icon OpenTelemetry Semantic Conventions -Welcome to the new repository! +[![Checks](https://github.com/open-telemetry/semantic-conventions/workflows/Checks/badge.svg?branch=main)](https://github.com/open-telemetry/semantic-conventions/actions?query=workflow%3A%22Checks%22+branch%3Amain) +[![GitHub tag (latest SemVer)](https://img.shields.io/github/tag/open-telemetry/semantic-conventions.svg?logo=opentelemetry&&color=f5a800&label=Latest%20release)](https://github.com/open-telemetry/semantic-conventions/releases/latest) +[![Specification Version](https://img.shields.io/badge/OTel_specification_version-v1.26.0-blue?logo=opentelemetry&color=f5a800)](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.26.0) -This is currently a direct copy/filter-branch of the Specification repository -with only semantic conventions included. - -This repository is currently using [this specification version][SpecificationVersion]. +Semantic Conventions define a common set of (semantic) attributes which +provide meaning to data when collecting, producing and consuming it. ## Read the docs -The documentation currently resides in the [docs](docs/README.md) folder. +The human-readable version of the semantic conventions resides in the [docs](docs/README.md) folder. +Major parts of these Markdown documents are generated from the YAML definitions located in the [model](model/README.md) folder. ## Contributing @@ -34,6 +35,4 @@ Maintainers ([@open-telemetry/specs-semconv-maintainers](https://github.com/orgs - [Josh Suereth](https://github.com/jsuereth), Google - [Reiley Yang](https://github.com/reyang), Microsoft -_Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer)._ - -[SpecificationVersion]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0 +_Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer). diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 3cc895fc7a..2e483c4eda 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -14,7 +14,7 @@ The attributes registry is the place where attributes are defined. An attribute Attributes defined in the registry can be used in different semantic conventions. Attributes should be included in this registry before they are used in semantic conventions. Semantic conventions may override all the properties of an attribute except for the `id` and `type` in case it's required for a particular context. In addition, semantic conventions specify the requirement level of an attribute in the corresponding context. -A definition of an attribute in the registry does not necessarily imply that the attribute is used in any of the semantic conventions. +A definition of an attribute in the registry doesn't necessarily imply that the attribute is used in any of the semantic conventions. If applicable, application developers are encouraged to use existing attributes from this registry. See also [these recommendations][developers recommendations] regarding attribute selection and attribute naming for custom use cases. @@ -27,6 +27,28 @@ All registered attributes are listed by namespace in this registry. Currently, the following namespaces exist: +* [Client](client.md) +* [Cloud](cloud.md) +* [Code](code.md) +* [Container](container.md) +* [DB](db.md) (database) +* [Destination](destination.md) +* [Device](device.md) +* [Disk](disk.md) +* [Error](error.md) +* [Host](host.md) * [HTTP](http.md) - -[developers recommendations]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/common/attribute-naming.md#recommendations-for-application-developers +* [K8s](k8s.md) +* [Network](network.md) +* [OCI](oci.md) +* [OS](os.md) +* [Process](process.md) +* [RPC](rpc.md) +* [Server](server.md) +* [Source](source.md) +* [Thread](thread.md) +* [TLS](tls.md) +* [URL](url.md) +* [User agent](user-agent.md) + +[developers recommendations]: ../general/attribute-naming.md#recommendations-for-application-developers diff --git a/docs/attributes-registry/client.md b/docs/attributes-registry/client.md new file mode 100644 index 0000000000..9ed3875a83 --- /dev/null +++ b/docs/attributes-registry/client.md @@ -0,0 +1,23 @@ + + +# Client Attributes + +These attributes may be used to describe the client 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. + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `client.address` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | +| `client.port` | int | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Client port number. [2] | `65123` | + +**[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. + +**[2]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. + diff --git a/docs/attributes-registry/cloud.md b/docs/attributes-registry/cloud.md new file mode 100644 index 0000000000..a51ac490aa --- /dev/null +++ b/docs/attributes-registry/cloud.md @@ -0,0 +1,85 @@ + + +# Cloud + +## Cloud Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `cloud.account.id` | string | The cloud account ID the resource is assigned to. | `111111111111`; `opentelemetry` | +| `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. [1] | `us-east-1c` | +| `cloud.platform` | string | The cloud platform in use. [2] | `alibaba_cloud_ecs` | +| `cloud.provider` | string | Name of the cloud provider. | `alibaba_cloud` | +| `cloud.region` | string | The geographical region the resource is running. [3] | `us-central1`; `us-east-1` | +| `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/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) [4] | `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/` | + +**[1]:** Availability zones are called "zones" on Alibaba Cloud and Google Cloud. + +**[2]:** The prefix of the service SHOULD match the one specified in `cloud.provider`. + +**[3]:** 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/global-infrastructure/geographies/), [Google Cloud regions](https://cloud.google.com/about/locations), or [Tencent Cloud regions](https://www.tencentcloud.com/document/product/213/6091). + +**[4]:** 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/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. + +`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_bare_metal_solution` | Google Bare Metal Solution (BMS) | +| `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) | + +`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 | + \ No newline at end of file diff --git a/docs/attributes-registry/code.md b/docs/attributes-registry/code.md new file mode 100644 index 0000000000..651caa99f5 --- /dev/null +++ b/docs/attributes-registry/code.md @@ -0,0 +1,19 @@ + + +# Code + +These attributes allow to report this unit of code and therefore to provide more context about the telemetry data. + +## Code Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `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` | +| `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` | +| `code.function` | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `serveRequest` | +| `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` | +| `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` | +| `code.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. | `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)` | + \ No newline at end of file diff --git a/docs/attributes-registry/container.md b/docs/attributes-registry/container.md new file mode 100644 index 0000000000..7cc959620b --- /dev/null +++ b/docs/attributes-registry/container.md @@ -0,0 +1,30 @@ + + +# Container + +## Container Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `container.command` | string | The command used to run the container (i.e. the command name). [1] | `otelcontribcol` | +| `container.command_args` | string[] | All the command arguments (including the command/executable itself) run by the container. [2] | `[otelcontribcol, --config, config.yaml]` | +| `container.command_line` | string | The full command run by the container as a single string representing the full command. [2] | `otelcontribcol --config config.yaml` | +| `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` | +| `container.image.id` | string | Runtime specific image identifier. Usually a hash algorithm followed by a UUID. [2] | `sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f` | +| `container.image.name` | string | Name of the image the container was built on. | `gcr.io/opentelemetry/operator` | +| `container.image.repo_digests` | string[] | Repo digests of the container image as provided by the container runtime. [3] | `[example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb, internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578]` | +| `container.image.tags` | string[] | Container image tags. An example can be found in [Docker Image Inspect](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect). Should be only the `` section of the full name for example from `registry.example.com/my-org/my-image:`. | `[v1.27.1, 3.5.7-0]` | +| `container.labels.` | string | Container labels, `` being the label name, the value being the label value. | `container.labels.app=nginx` | +| `container.name` | string | Container name used by container runtime. | `opentelemetry-autoconf` | +| `container.runtime` | string | The container runtime managing this container. | `docker`; `containerd`; `rkt` | + +**[1]:** If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage. + +**[2]:** Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker container inspect [API](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerInspect) endpoint. +K8s defines a link to the container registry repository with digest `"imageID": "registry.azurecr.io /namespace/service/dockerfile@sha256:bdeabd40c3a8a492eaf9e8e44d0ebbb84bac7ee25ac0cf8a7159d25f62555625"`. +The ID is assinged by the container runtime and can vary in different environments. Consider using `oci.manifest.digest` if it is important to identify the same image in different environments/runtimes. + +**[3]:** [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field. + diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md new file mode 100644 index 0000000000..c178bbe971 --- /dev/null +++ b/docs/attributes-registry/db.md @@ -0,0 +1,223 @@ + + +# Database + + + +- [Generic Database Attributes](#generic-database-attributes) +- [Cassandra Attributes](#cassandra-attributes) +- [CosmosDB Attributes](#cosmosdb-attributes) +- [Elasticsearch Attributes](#elasticsearch-attributes) +- [JDBC Attributes](#jdbc-attributes) +- [MongoDB Attributes](#mongodb-attributes) +- [MSSQL Attributes](#mssql-attributes) +- [Redis Attributes](#redis-attributes) +- [SQL Attributes](#sql-attributes) + + + +## Generic Database Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `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;` | +| `db.instance.id` | string | An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. The client may obtain this value in databases like MySQL using queries like `select @@hostname`. | `mysql-e26b99z.example.com` | +| `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` | +| `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. [2] | `findAndModify`; `HMSET`; `SELECT` | +| `db.statement` | string | The database statement being executed. | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | +| `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` | +| `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | + +**[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]:** 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. + +`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 | + + +## Cassandra Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `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` | +| `db.cassandra.coordinator.dc` | string | The data center of the coordinating node for a query. | `us-west-2` | +| `db.cassandra.coordinator.id` | string | The ID of the coordinating node for a query. | `be13faa2-8574-4d71-926d-27f16cf8a7af` | +| `db.cassandra.idempotence` | boolean | Whether or not the query is idempotent. | | +| `db.cassandra.page_size` | int | The fetch size used for paging, i.e. how many rows will be returned at once. | `5000` | +| `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` | +| `db.cassandra.table` | string | The name of the primary Cassandra table that the operation is acting upon, including the keyspace name (if applicable). [1] | `mytable` | + +**[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. + +`db.cassandra.consistency_level` MUST be one of the following: + +| Value | Description | +|---|---| +| `all` | all | +| `each_quorum` | each_quorum | +| `quorum` | quorum | +| `local_quorum` | local_quorum | +| `one` | one | +| `two` | two | +| `three` | three | +| `local_one` | local_one | +| `any` | any | +| `serial` | serial | +| `local_serial` | local_serial | + + +## CosmosDB Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `db.cosmosdb.client_id` | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` | +| `db.cosmosdb.connection_mode` | string | Cosmos client connection mode. | `gateway` | +| `db.cosmosdb.container` | string | Cosmos DB container name. | `anystring` | +| `db.cosmosdb.operation_type` | string | CosmosDB Operation Type. | `Invalid` | +| `db.cosmosdb.request_charge` | double | RU consumed for that operation | `46.18`; `1.0` | +| `db.cosmosdb.request_content_length` | int | Request payload size in bytes | | +| `db.cosmosdb.status_code` | int | Cosmos DB status code. | `200`; `201` | +| `db.cosmosdb.sub_status_code` | int | Cosmos DB sub status code. | `1000`; `1002` | + +`db.cosmosdb.connection_mode` MUST be one of the following: + +| Value | Description | +|---|---| +| `gateway` | Gateway (HTTP) connections mode | +| `direct` | Direct connection. | + +`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 | + + +## Elasticsearch Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `db.elasticsearch.cluster.name` | string | Represents the identifier of an Elasticsearch cluster. | `e9106fc68e3044f0b1475b04bf4ffd5f` | +| `db.elasticsearch.node.name` | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | +| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. [1] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | + +**[1]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names. + + +## JDBC Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `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` | + + +## MongoDB Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `db.mongodb.collection` | string | The MongoDB collection being accessed within the database stated in `db.name`. | `customers`; `products` | + + +## MSSQL Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `db.mssql.instance_name` | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/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` | + +**[1]:** If setting a `db.mssql.instance_name`, `server.port` is no longer required (but still recommended if non-standard). + + +## Redis Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `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` | + + +## SQL Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `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` | + +**[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. + diff --git a/docs/attributes-registry/destination.md b/docs/attributes-registry/destination.md new file mode 100644 index 0000000000..db83cb53b0 --- /dev/null +++ b/docs/attributes-registry/destination.md @@ -0,0 +1,21 @@ + + +# Destination Attributes + +These attributes may be used to describe the 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. + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `destination.address` | string | Destination address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `destination.example.com`; `10.1.2.80`; `/tmp/my.sock` | +| `destination.port` | int | Destination port number | `3389`; `2888` | + +**[1]:** When observed from the source side, and when communicating through an intermediary, `destination.address` SHOULD represent the destination address behind any intermediaries, for example proxies, if it's available. + diff --git a/docs/attributes-registry/device.md b/docs/attributes-registry/device.md new file mode 100644 index 0000000000..3c1f06c4ea --- /dev/null +++ b/docs/attributes-registry/device.md @@ -0,0 +1,23 @@ + + +# Device + +## Device Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `device.id` | string | A unique identifier representing the device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | +| `device.manufacturer` | string | The name of the device manufacturer [2] | `Apple`; `Samsung` | +| `device.model.identifier` | string | The model identifier for the device [3] | `iPhone3,4`; `SM-G920F` | +| `device.model.name` | string | The marketing name for the device model [4] | `iPhone 6s Plus`; `Samsung Galaxy S6` | + +**[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]:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`. + +**[3]:** 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. + +**[4]:** It's recommended this value represents a human-readable version of the device model rather than a machine-readable alternative. + diff --git a/docs/attributes-registry/disk.md b/docs/attributes-registry/disk.md new file mode 100644 index 0000000000..a983873365 --- /dev/null +++ b/docs/attributes-registry/disk.md @@ -0,0 +1,19 @@ + + +# Disk + +## Disk Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `disk.io.direction` | string | The disk IO operation direction. | `read` | + +`disk.io.direction` MUST be one of the following: + +| Value | Description | +|---|---| +| `read` | read | +| `write` | write | + diff --git a/docs/attributes-registry/error.md b/docs/attributes-registry/error.md new file mode 100644 index 0000000000..21e0d2c67d --- /dev/null +++ b/docs/attributes-registry/error.md @@ -0,0 +1,34 @@ + + +# Error + +## Error Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `error.type` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | + +**[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low. +Telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time when no +additional filters are applied. + +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + +If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), +it's RECOMMENDED to: + +* Use a domain-specific attribute +* Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. + +`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | + \ No newline at end of file diff --git a/docs/attributes-registry/host.md b/docs/attributes-registry/host.md new file mode 100644 index 0000000000..005700c2cc --- /dev/null +++ b/docs/attributes-registry/host.md @@ -0,0 +1,44 @@ + +# Host + +## Host Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `host.arch` | string | The CPU architecture the host system is running on. | `amd64` | +| `host.cpu.cache.l2.size` | int | The amount of level 2 memory cache available to the processor (in Bytes). | `12288000` | +| `host.cpu.family` | string | Family or generation of the CPU. | `6`; `PA-RISC 1.1e` | +| `host.cpu.model.id` | string | Model identifier. It provides more granular information about the CPU, distinguishing it from other CPUs within the same family. | `6`; `9000/778/B180L` | +| `host.cpu.model.name` | string | Model designation of the processor. | `11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz` | +| `host.cpu.stepping` | int | Stepping or core revisions. | `1` | +| `host.cpu.vendor.id` | string | Processor manufacturer identifier. A maximum 12-character string. [1] | `GenuineIntel` | +| `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` | +| `host.image.id` | string | VM image ID or host OS image ID. For Cloud, this value is from the provider. | `ami-07b06b442921831e5` | +| `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` | +| `host.image.version` | string | The version string of the VM image or host OS as defined in [Version Attributes](/docs/resource/README.md#version-attributes). | `0.1` | +| `host.ip` | string[] | Available IP addresses of the host, excluding loopback interfaces. [2] | `[192.168.1.140, fe80::abc2:4a28:737a:609e]` | +| `host.mac` | string[] | Available MAC addresses of the host, excluding loopback interfaces. [3] | `[AC-DE-48-23-45-67, AC-DE-48-23-45-67-01-9F]` | +| `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` | +| `host.type` | string | Type of host. For Cloud, this must be the machine type. | `n1-standard-1` | + +**[1]:** [CPUID](https://wiki.osdev.org/CPUID) command returns the vendor ID string in EBX, EDX and ECX registers. Writing these to memory in this order results in a 12-character string. + +**[2]:** IPv4 Addresses MUST be specified in dotted-quad notation. IPv6 addresses MUST be specified in the [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952.html) format. + +**[3]:** MAC Addresses MUST be represented in [IEEE RA hexadecimal form](https://standards.ieee.org/wp-content/uploads/import/documents/tutorials/eui.pdf): as hyphen-separated octets in uppercase hexadecimal form from most to least significant. + +`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 | + \ No newline at end of file diff --git a/docs/attributes-registry/http.md b/docs/attributes-registry/http.md index 7a62cc8498..2f9481a64c 100644 --- a/docs/attributes-registry/http.md +++ b/docs/attributes-registry/http.md @@ -9,14 +9,14 @@ | Attribute | Type | Description | Examples | |---|---|---|---| | `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` | -| `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] | `http.request.header.content_type=["application/json"]`; `http.request.header.x_forwarded_for=["1.2.3.4", "1.2.3.5"]` | -| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | -| `http.request.method_original` | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | -| `http.resend_count` | int | The ordinal number of request resending attempt (for any reason, including redirects). [3] | `3` | +| `http.request.header.` | string[] | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [1] | `http.request.header.content-type=["application/json"]`; `http.request.header.x-forwarded-for=["1.2.3.4", "1.2.3.5"]` | +| `http.request.method` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
HTTP request method. [2] | `GET`; `POST`; `HEAD` | +| `http.request.method_original` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | +| `http.request.resend_count` | int | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
The ordinal number of request resending attempt (for any reason, including redirects). [3] | `3` | | `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` | -| `http.response.header.` | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [4] | `http.response.header.content_type=["application/json"]`; `http.response.header.my_custom_header=["abc", "def"]` | -| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | -| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [5] | `/users/:userID?`; `{controller}/{action}/{id?}` | +| `http.response.header.` | string[] | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [4] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | +| `http.response.status_code` | int | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | +| `http.route` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
The matched route, that is, the path template in the format used by the respective server framework. [5] | `/users/:userID?`; `{controller}/{action}/{id?}` | **[1]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request 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. @@ -67,11 +67,24 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin | Attribute | Type | Description | Examples | |---|---|---|---| +| `http.flavor` | string | Deprecated, use `network.protocol.name` instead. | `1.0` | | `http.method` | string | Deprecated, use `http.request.method` instead. | `GET`; `POST`; `HEAD` | -| `http.request_content_length` | int | Deprecated, use `http.request.body.size` instead. | `3495` | -| `http.response_content_length` | int | Deprecated, use `http.response.body.size` instead. | `3495` | +| `http.request_content_length` | int | Deprecated, use `http.request.header.content-length` instead. | `3495` | +| `http.response_content_length` | int | Deprecated, use `http.response.header.content-length` instead. | `3495` | | `http.scheme` | string | Deprecated, use `url.scheme` instead. | `http`; `https` | | `http.status_code` | int | Deprecated, use `http.response.status_code` instead. | `200` | | `http.target` | string | Deprecated, use `url.path` and `url.query` instead. | `/search?q=OpenTelemetry#SemConv` | | `http.url` | string | Deprecated, use `url.full` instead. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | +| `http.user_agent` | string | Deprecated, use `user_agent.original` instead. | `CERN-LineMode/2.15 libwww/2.17b3`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1` | + +`http.flavor` 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 | +|---|---| +| `1.0` | HTTP/1.0 | +| `1.1` | HTTP/1.1 | +| `2.0` | HTTP/2 | +| `3.0` | HTTP/3 | +| `SPDY` | SPDY protocol. | +| `QUIC` | QUIC protocol. | diff --git a/docs/attributes-registry/k8s.md b/docs/attributes-registry/k8s.md new file mode 100644 index 0000000000..9becbbf729 --- /dev/null +++ b/docs/attributes-registry/k8s.md @@ -0,0 +1,53 @@ +# Kubernetes + +## Kubernetes Resource Attributes + + +| 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 | +| `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 | +| `k8s.cronjob.name` | string | The name of the CronJob. | `opentelemetry` | Recommended | +| `k8s.cronjob.uid` | string | The UID of the CronJob. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | +| `k8s.daemonset.name` | string | The name of the DaemonSet. | `opentelemetry` | Recommended | +| `k8s.daemonset.uid` | string | The UID of the DaemonSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | +| `k8s.deployment.name` | string | The name of the Deployment. | `opentelemetry` | Recommended | +| `k8s.deployment.uid` | string | The UID of the Deployment. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | +| `k8s.job.name` | string | The name of the Job. | `opentelemetry` | Recommended | +| `k8s.job.uid` | string | The UID of the Job. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | +| `k8s.namespace.name` | string | The name of the namespace that the pod is running in. | `default` | Recommended | +| `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 | +| `k8s.pod.labels.` | string | The labels placed on the Pod, the `` being the label name, the value being the label value. | `k8s.pod.labels.app=my-app`; `k8s.pod.labels.mycompany.io/arch=x64`; `k8s.pod.labels.data=` | Recommended | +| `k8s.pod.name` | string | The name of the Pod. | `opentelemetry-pod-autoconf` | Recommended | +| `k8s.pod.uid` | string | The UID of the Pod. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | +| `k8s.replicaset.name` | string | The name of the ReplicaSet. | `opentelemetry` | Recommended | +| `k8s.replicaset.uid` | string | The UID of the ReplicaSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | +| `k8s.statefulset.name` | string | The name of the StatefulSet. | `opentelemetry` | Recommended | +| `k8s.statefulset.uid` | string | The UID of the StatefulSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | + +**[1]:** K8s doesn't 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. + diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md new file mode 100644 index 0000000000..626d8cc59f --- /dev/null +++ b/docs/attributes-registry/messaging.md @@ -0,0 +1,101 @@ + + +# Messaging + +## Messaging Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `messaging.batch.message_count` | int | The number of messages sent, received, or processed in the scope of the batching operation. [1] | `0`; `1`; `2` | +| `messaging.client_id` | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | +| `messaging.destination.anonymous` | boolean | A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name). | | +| `messaging.destination.name` | string | The message destination name [2] | `MyQueue`; `MyTopic` | +| `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [3] | `/customers/{customerId}` | +| `messaging.destination.temporary` | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | +| `messaging.destination_publish.anonymous` | boolean | A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name). | | +| `messaging.destination_publish.name` | string | The name of the original destination the message was published to [4] | `MyQueue`; `MyTopic` | +| `messaging.gcp_pubsub.message.ordering_key` | string | The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. | `ordering_key` | +| `messaging.kafka.consumer.group` | string | Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. | `my-group` | +| `messaging.kafka.destination.partition` | int | Partition the message is sent to. | `2` | +| `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. [5] | `myKey` | +| `messaging.kafka.message.offset` | int | The offset of a record in the corresponding Kafka partition. | `42` | +| `messaging.kafka.message.tombstone` | boolean | A boolean that is true if the message is a tombstone. | | +| `messaging.message.body.size` | int | The size of the message body in bytes. [6] | `1439` | +| `messaging.message.conversation_id` | string | The conversation ID identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | +| `messaging.message.envelope.size` | int | The size of the message body and metadata in bytes. [7] | `2738` | +| `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | +| `messaging.operation` | string | A string identifying the kind of messaging operation. [8] | `publish` | +| `messaging.rabbitmq.destination.routing_key` | string | RabbitMQ message routing key. | `myKey` | +| `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` | +| `messaging.rocketmq.consumption_model` | string | Model of message consumption. This only applies to consumer spans. | `clustering` | +| `messaging.rocketmq.message.delay_time_level` | int | The delay time level for delay message, which determines the message delay time. | `3` | +| `messaging.rocketmq.message.delivery_timestamp` | int | The timestamp in milliseconds that the delay message is expected to be delivered to consumer. | `1665987217045` | +| `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` | +| `messaging.rocketmq.message.keys` | string[] | Key(s) of message, another way to mark message besides message id. | `[keyA, keyB]` | +| `messaging.rocketmq.message.tag` | string | The secondary classifier of message besides topic. | `tagA` | +| `messaging.rocketmq.message.type` | string | Type of message. | `normal` | +| `messaging.rocketmq.namespace` | string | Namespace of RocketMQ resources, resources in different namespaces are individual. | `myNamespace` | +| `messaging.system` | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `activemq` | + +**[1]:** 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. + +**[2]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If +the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker. + +**[3]:** 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. + +**[4]:** The name SHOULD uniquely identify a specific queue, topic, or other entity within the broker. If +the broker doesn't have such notion, the original destination name SHOULD uniquely identify the broker. + +**[5]:** 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. + +**[6]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed +body size should be used. + +**[7]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed +size should be used. + +**[8]:** If a custom value is used, it MUST be of low cardinality. + +`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` | One or more messages are provided for publishing to an intermediary. If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. | +| `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. | +| `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | +| `deliver` | One or more messages are passed to a consumer. This operation refers to push-based scenarios, where consumer register callbacks which get called by messaging SDKs. | + +`messaging.rocketmq.consumption_model` MUST be one of the following: + +| Value | Description | +|---|---| +| `clustering` | Clustering consumption model | +| `broadcasting` | Broadcasting consumption model | + +`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.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 | +|---|---| +| `activemq` | Apache ActiveMQ | +| `aws_sqs` | Amazon Simple Queue Service (SQS) | +| `azure_eventgrid` | Azure Event Grid | +| `azure_eventhubs` | Azure Event Hubs | +| `azure_servicebus` | Azure Service Bus | +| `gcp_pubsub` | Google Cloud Pub/Sub | +| `jms` | Java Message Service | +| `kafka` | Apache Kafka | +| `rabbitmq` | RabbitMQ | +| `rocketmq` | Apache RocketMQ | + diff --git a/docs/attributes-registry/network.md b/docs/attributes-registry/network.md new file mode 100644 index 0000000000..a6c5907728 --- /dev/null +++ b/docs/attributes-registry/network.md @@ -0,0 +1,139 @@ + + +# Network + +These attributes may be used for any network related operation. + +## Network Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `network.carrier.icc` | string | The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. | `DE` | +| `network.carrier.mcc` | string | The mobile carrier country code. | `310` | +| `network.carrier.mnc` | string | The mobile carrier network code. | `001` | +| `network.carrier.name` | string | The name of the mobile carrier. | `sprint` | +| `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` | +| `network.connection.type` | string | The internet connection type. | `wifi` | +| `network.io.direction` | string | The network IO operation direction. | `transmit` | +| `network.local.address` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Local address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | +| `network.local.port` | int | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Local port number of the network connection. | `65123` | +| `network.peer.address` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | +| `network.peer.port` | int | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Peer port number of the network connection. | `65123` | +| `network.protocol.name` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
[OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [1] | `amqp`; `http`; `mqtt` | +| `network.protocol.version` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Version of the protocol specified in `network.protocol.name`. [2] | `3.1.1` | +| `network.transport` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
[OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` | +| `network.type` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | + +**[1]:** The value SHOULD be normalized to lowercase. + +**[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 has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[3]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport. For example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[4]:** The value SHOULD be normalized to lowercase. + +`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 | + +`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.io.direction` MUST be one of the following: + +| Value | Description | +|---|---| +| `transmit` | transmit | +| `receive` | receive | + +`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. | +| `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 | + + +## Deprecated Network Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `net.host.name` | string | Deprecated, use `server.address`. | `example.com` | +| `net.host.port` | int | Deprecated, use `server.port`. | `8080` | +| `net.peer.name` | string | Deprecated, use `server.address` on client spans and `client.address` on server spans. | `example.com` | +| `net.peer.port` | int | Deprecated, use `server.port` on client spans and `client.port` on server spans. | `8080` | +| `net.protocol.name` | string | Deprecated, use `network.protocol.name`. | `amqp`; `http`; `mqtt` | +| `net.protocol.version` | string | Deprecated, use `network.protocol.version`. | `3.1.1` | +| `net.sock.family` | string | Deprecated, use `network.transport` and `network.type`. | `inet` | +| `net.sock.host.addr` | string | Deprecated, use `network.local.address`. | `/var/my.sock` | +| `net.sock.host.port` | int | Deprecated, use `network.local.port`. | `8080` | +| `net.sock.peer.addr` | string | Deprecated, use `network.peer.address`. | `192.168.0.1` | +| `net.sock.peer.name` | string | Deprecated, no replacement at this time. | `/var/my.sock` | +| `net.sock.peer.port` | int | Deprecated, use `network.peer.port`. | `65531` | +| `net.transport` | string | Deprecated, use `network.transport`. | `ip_tcp` | + +`net.sock.family` 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 | +|---|---| +| `inet` | IPv4 address | +| `inet6` | IPv6 address | +| `unix` | Unix domain socket path | + +`net.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 | +|---|---| +| `ip_tcp` | ip_tcp | +| `ip_udp` | ip_udp | +| `pipe` | Named or anonymous pipe. | +| `inproc` | In-process communication. [1] | +| `other` | Something else (non IP-based). | + +**[1]:** Signals that there is only in-process communication not using a "real" network protocol in cases where network attributes would normally be expected. Usually all other network attributes can be left out in that case. + diff --git a/docs/attributes-registry/oci.md b/docs/attributes-registry/oci.md new file mode 100644 index 0000000000..abfc4f7479 --- /dev/null +++ b/docs/attributes-registry/oci.md @@ -0,0 +1,14 @@ +# Open Container Initiative (OCI) + +The [Open Container Initiative](https://opencontainers.org/) defines open industry standards around container formats and runtimes. + +## OCI Image Manifest + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `oci.manifest.digest` | string | The digest of the OCI image manifest. For container images specifically is the digest by which the container image is known. [1] | `sha256:e4ca62c0d62f3e886e684806dfe9d4e0cda60d54986898173c1083856cfda0f4` | + +**[1]:** Follows [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md), and specifically the [Digest property](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests). +An example can be found in [Example Image Manifest](https://docs.docker.com/registry/spec/manifest-v2-2/#example-image-manifest). + \ No newline at end of file diff --git a/docs/attributes-registry/os.md b/docs/attributes-registry/os.md new file mode 100644 index 0000000000..a813298f98 --- /dev/null +++ b/docs/attributes-registry/os.md @@ -0,0 +1,32 @@ + +# OS + +## Operating System Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `os.build_id` | string | Unique identifier for a particular build or compilation of the operating system. | `TQ3C.230805.001.B2`; `20E247`; `22621` | +| `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` | +| `os.name` | string | Human readable operating system name. | `iOS`; `Android`; `Ubuntu` | +| `os.type` | string | The operating system type. | `windows` | +| `os.version` | string | The version string of the operating system as defined in [Version Attributes](/docs/resource/README.md#version-attributes). | `14.2.1`; `18.04.1` | + +`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/docs/attributes-registry/process.md b/docs/attributes-registry/process.md new file mode 100644 index 0000000000..edef9364bd --- /dev/null +++ b/docs/attributes-registry/process.md @@ -0,0 +1,22 @@ + + +# Process + +## Process Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `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` | +| `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]` | +| `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"` | +| `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` | +| `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` | +| `process.owner` | string | The username of the user that owns the process. | `root` | +| `process.parent_pid` | int | Parent Process identifier (PID). | `111` | +| `process.pid` | int | Process identifier (PID). | `1234` | +| `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` | +| `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` | +| `process.runtime.version` | string | The version of the runtime of this process, as returned by the runtime without modification. | `14.0.2` | + diff --git a/docs/attributes-registry/rpc.md b/docs/attributes-registry/rpc.md new file mode 100644 index 0000000000..fd112b1d2b --- /dev/null +++ b/docs/attributes-registry/rpc.md @@ -0,0 +1,91 @@ + + +# RPC + +## RPC Attributes + +RPC attributes are intended to be used in the context of events related to remote procedure calls (RPC). + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `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` | +| `rpc.connect_rpc.request.metadata.` | string[] | Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. [1] | `rpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]` | +| `rpc.connect_rpc.response.metadata.` | string[] | Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. [2] | `rpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]` | +| `rpc.grpc.request.metadata.` | string[] | gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [3] | `rpc.grpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]` | +| `rpc.grpc.response.metadata.` | string[] | gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [4] | `rpc.grpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]` | +| `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` | +| `rpc.jsonrpc.error_code` | int | `error.code` property of response if it is an error response. | `-32700`; `100` | +| `rpc.jsonrpc.error_message` | string | `error.message` property of response if it is an error response. | `Parse error`; `User already exists` | +| `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`; `` | +| `rpc.jsonrpc.version` | string | Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted. | `2.0`; `1.0` | +| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [5] | `exampleMethod` | +| `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [6] | `myservice.EchoService` | +| `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | + +**[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + +**[2]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + +**[3]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + +**[4]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + +**[5]:** 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). + +**[6]:** 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). + +`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 | + +`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 | + +`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 | + diff --git a/docs/attributes-registry/server.md b/docs/attributes-registry/server.md new file mode 100644 index 0000000000..a1189591a1 --- /dev/null +++ b/docs/attributes-registry/server.md @@ -0,0 +1,23 @@ + + +# Server Attributes + +These attributes may be used to describe the 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. + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `server.address` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | +| `server.port` | int | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Server port number. [2] | `80`; `8080`; `443` | + +**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + +**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + \ No newline at end of file diff --git a/docs/attributes-registry/source.md b/docs/attributes-registry/source.md new file mode 100644 index 0000000000..c239896bf1 --- /dev/null +++ b/docs/attributes-registry/source.md @@ -0,0 +1,21 @@ + + +# Source Attributes + +These attributes may be used to describe the sender 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. + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `source.address` | string | Source address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `source.example.com`; `10.1.2.80`; `/tmp/my.sock` | +| `source.port` | int | Source port number | `3389`; `2888` | + +**[1]:** When observed from the destination side, and when communicating through an intermediary, `source.address` SHOULD represent the source address behind any intermediaries, for example proxies, if it's available. + \ No newline at end of file diff --git a/docs/attributes-registry/thread.md b/docs/attributes-registry/thread.md new file mode 100644 index 0000000000..5a71c29cc8 --- /dev/null +++ b/docs/attributes-registry/thread.md @@ -0,0 +1,15 @@ + + +# Thread + +These attributes may be used for any operation to store information about a thread. + +## Thread Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `thread.id` | int | Current "managed" thread ID (as opposed to OS thread ID). | `42` | +| `thread.name` | string | Current thread name. | `main` | + \ No newline at end of file diff --git a/docs/attributes-registry/tls.md b/docs/attributes-registry/tls.md new file mode 100644 index 0000000000..f774c31a26 --- /dev/null +++ b/docs/attributes-registry/tls.md @@ -0,0 +1,49 @@ + + +# TLS + +## TLS Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `tls.cipher` | string | String indicating the [cipher](https://datatracker.ietf.org/doc/html/rfc5246#appendix-A.5) used during the current connection. [1] | `TLS_RSA_WITH_3DES_EDE_CBC_SHA`; `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256` | +| `tls.client.certificate` | string | PEM-encoded stand-alone certificate offered by the client. This is usually mutually-exclusive of `client.certificate_chain` since this value also exists in that list. | `MII...` | +| `tls.client.certificate_chain` | string[] | Array of PEM-encoded certificates that make up the certificate chain offered by the client. This is usually mutually-exclusive of `client.certificate` since that value should be the first certificate in the chain. | `[MII..., MI...]` | +| `tls.client.hash.md5` | string | Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the client. For consistency with other hash values, this value should be formatted as an uppercase hash. | `0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC` | +| `tls.client.hash.sha1` | string | Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the client. For consistency with other hash values, this value should be formatted as an uppercase hash. | `9E393D93138888D288266C2D915214D1D1CCEB2A` | +| `tls.client.hash.sha256` | string | Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the client. For consistency with other hash values, this value should be formatted as an uppercase hash. | `0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0` | +| `tls.client.issuer` | string | Distinguished name of [subject](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.6) of the issuer of the x.509 certificate presented by the client. | `CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com` | +| `tls.client.ja3` | string | A hash that identifies clients based on how they perform an SSL/TLS handshake. | `d4e5b18d6b55c71272893221c96ba240` | +| `tls.client.not_after` | string | Date/Time indicating when client certificate is no longer considered valid. | `2021-01-01T00:00:00.000Z` | +| `tls.client.not_before` | string | Date/Time indicating when client certificate is first considered valid. | `1970-01-01T00:00:00.000Z` | +| `tls.client.server_name` | string | Also called an SNI, this tells the server which hostname to which the client is attempting to connect to. | `opentelemetry.io` | +| `tls.client.subject` | string | Distinguished name of subject of the x.509 certificate presented by the client. | `CN=myclient, OU=Documentation Team, DC=example, DC=com` | +| `tls.client.supported_ciphers` | string[] | Array of ciphers offered by the client during the client hello. | `["TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", "..."]` | +| `tls.curve` | string | String indicating the curve used for the given cipher, when applicable | `secp256r1` | +| `tls.established` | boolean | Boolean flag indicating if the TLS negotiation was successful and transitioned to an encrypted tunnel. | `True` | +| `tls.next_protocol` | string | String indicating the protocol being tunneled. Per the values in the [IANA registry](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids), this string should be lower case. | `http/1.1` | +| `tls.protocol.name` | string | Normalized lowercase protocol name parsed from original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES) | `ssl` | +| `tls.protocol.version` | string | Numeric part of the version parsed from the original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES) | `1.2`; `3` | +| `tls.resumed` | boolean | Boolean flag indicating if this TLS connection was resumed from an existing TLS negotiation. | `True` | +| `tls.server.certificate` | string | PEM-encoded stand-alone certificate offered by the server. This is usually mutually-exclusive of `server.certificate_chain` since this value also exists in that list. | `MII...` | +| `tls.server.certificate_chain` | string[] | Array of PEM-encoded certificates that make up the certificate chain offered by the server. This is usually mutually-exclusive of `server.certificate` since that value should be the first certificate in the chain. | `[MII..., MI...]` | +| `tls.server.hash.md5` | string | Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the server. For consistency with other hash values, this value should be formatted as an uppercase hash. | `0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC` | +| `tls.server.hash.sha1` | string | Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the server. For consistency with other hash values, this value should be formatted as an uppercase hash. | `9E393D93138888D288266C2D915214D1D1CCEB2A` | +| `tls.server.hash.sha256` | string | Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the server. For consistency with other hash values, this value should be formatted as an uppercase hash. | `0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0` | +| `tls.server.issuer` | string | Distinguished name of [subject](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.6) of the issuer of the x.509 certificate presented by the client. | `CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com` | +| `tls.server.ja3s` | string | A hash that identifies servers based on how they perform an SSL/TLS handshake. | `d4e5b18d6b55c71272893221c96ba240` | +| `tls.server.not_after` | string | Date/Time indicating when server certificate is no longer considered valid. | `2021-01-01T00:00:00.000Z` | +| `tls.server.not_before` | string | Date/Time indicating when server certificate is first considered valid. | `1970-01-01T00:00:00.000Z` | +| `tls.server.subject` | string | Distinguished name of subject of the x.509 certificate presented by the server. | `CN=myserver, OU=Documentation Team, DC=example, DC=com` | + +**[1]:** The values allowed for `tls.cipher` MUST be one of the `Descriptions` of the [registered TLS Cipher Suits](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#table-tls-parameters-4). + +`tls.protocol.name` 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 | +|---|---| +| `ssl` | ssl | +| `tls` | tls | + \ No newline at end of file diff --git a/docs/attributes-registry/url.md b/docs/attributes-registry/url.md new file mode 100644 index 0000000000..5b1aa7c0d8 --- /dev/null +++ b/docs/attributes-registry/url.md @@ -0,0 +1,22 @@ + +# URL + +## URL Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `url.fragment` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component | `SemConv` | +| `url.full` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | +| `url.path` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component | `/search` | +| `url.query` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [2] | `q=OpenTelemetry` | +| `url.scheme` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | + +**[1]:** 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. + +**[2]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. + \ No newline at end of file diff --git a/docs/attributes-registry/user-agent.md b/docs/attributes-registry/user-agent.md new file mode 100644 index 0000000000..589f722f87 --- /dev/null +++ b/docs/attributes-registry/user-agent.md @@ -0,0 +1,12 @@ + + +# User agent + +## User agent Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `user_agent.original` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
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`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1` | + diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md index e412dba1d9..9eb2077746 100644 --- a/docs/cloud-providers/aws-sdk.md +++ b/docs/cloud-providers/aws-sdk.md @@ -28,9 +28,9 @@ 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/rpc-spans.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | Recommended | -| [`rpc.service`](../rpc/rpc-spans.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/rpc-spans.md) | string | The value `aws-api`. | `aws-api` | Required | +| [`rpc.method`](../attributes-registry/rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | Recommended | +| [`rpc.service`](../attributes-registry/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`](../attributes-registry/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). diff --git a/docs/cloudevents/cloudevents-spans.md b/docs/cloudevents/cloudevents-spans.md index 33f8f9e109..4064262d1d 100644 --- a/docs/cloudevents/cloudevents-spans.md +++ b/docs/cloudevents/cloudevents-spans.md @@ -40,7 +40,7 @@ document. 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]() +can go through many [hops]() until it reaches a consumer. In this scenario, the traditional parent-child trace model is not sufficient to produce a meaningful trace. diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index b6f160457c..0fcc385c82 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -14,17 +14,17 @@ described on this page. ## Call-level attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `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.coordinator.dc` | string | The data center of the coordinating node for a query. | `us-west-2` | Recommended | -| `db.cassandra.coordinator.id` | string | The ID of the coordinating node for a query. | `be13faa2-8574-4d71-926d-27f16cf8a7af` | Recommended | -| `db.cassandra.idempotence` | boolean | Whether or not the query is idempotent. | | Recommended | -| `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.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.table` | string | The name of the primary table that the operation is acting upon, including the keyspace name (if applicable). [1] | `mytable` | Recommended | -| [`db.name`](database-spans.md) | string | The keyspace name in Cassandra. [2] | `mykeyspace` | Conditionally Required: If applicable. | +| [`db.cassandra.consistency_level`](../attributes-registry/db.md) | 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.coordinator.dc`](../attributes-registry/db.md) | string | The data center of the coordinating node for a query. | `us-west-2` | Recommended | +| [`db.cassandra.coordinator.id`](../attributes-registry/db.md) | string | The ID of the coordinating node for a query. | `be13faa2-8574-4d71-926d-27f16cf8a7af` | Recommended | +| [`db.cassandra.idempotence`](../attributes-registry/db.md) | boolean | Whether or not the query is idempotent. | | Recommended | +| [`db.cassandra.page_size`](../attributes-registry/db.md) | int | The fetch size used for paging, i.e. how many rows will be returned at once. | `5000` | Recommended | +| [`db.cassandra.speculative_execution_count`](../attributes-registry/db.md) | 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.table`](../attributes-registry/db.md) | string | The name of the primary Cassandra table that the operation is acting upon, including the keyspace name (if applicable). [1] | `mytable` | Recommended | +| [`db.name`](../attributes-registry/db.md) | string | The keyspace name in Cassandra. [2] | `mykeyspace` | Conditionally Required: If applicable. | **[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. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 5c092cf560..1862a1efa7 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -17,18 +17,18 @@ described on this page. 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.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.operation_type` | string | CosmosDB Operation Type. | `Invalid` | Conditionally Required: [1] | -| `db.cosmosdb.request_charge` | double | RU consumed for that operation | `46.18`; `1.0` | Conditionally Required: when 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] | -| `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 | +| [`db.cosmosdb.client_id`](../attributes-registry/db.md) | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` | Recommended | +| [`db.cosmosdb.connection_mode`](../attributes-registry/db.md) | string | Cosmos client connection mode. | `gateway` | Conditionally Required: if not `direct` (or pick gw as default) | +| [`db.cosmosdb.container`](../attributes-registry/db.md) | string | Cosmos DB container name. | `anystring` | Conditionally Required: if available | +| [`db.cosmosdb.operation_type`](../attributes-registry/db.md) | string | CosmosDB Operation Type. | `Invalid` | Conditionally Required: [1] | +| [`db.cosmosdb.request_charge`](../attributes-registry/db.md) | double | RU consumed for that operation | `46.18`; `1.0` | Conditionally Required: when available | +| [`db.cosmosdb.request_content_length`](../attributes-registry/db.md) | int | Request payload size in bytes | | Recommended | +| [`db.cosmosdb.status_code`](../attributes-registry/db.md) | int | Cosmos DB status code. | `200`; `201` | Conditionally Required: if response was received | +| [`db.cosmosdb.sub_status_code`](../attributes-registry/db.md) | int | Cosmos DB sub status code. | `1000`; `1002` | Conditionally Required: [2] | +| [`user_agent.original`](../attributes-registry/user-agent.md) | 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 diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index 3ee335d759..6702a92b40 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -14,10 +14,10 @@ described on this page. ## Call-level attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`db.operation`](database-spans.md) | string | The HTTP method + the target REST route. [1] | `GET /{db}/{docid}` | Conditionally Required: If `db.statement` is not applicable. | +| [`db.operation`](../attributes-registry/db.md) | string | The HTTP method + the target REST route. [1] | `GET /{db}/{docid}` | Conditionally Required: If `db.statement` is not applicable. | **[1]:** 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}`](http://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid). diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 058f672dd8..f211e64c37 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -45,7 +45,7 @@ This metric is [required][MetricRequired]. | Attribute | 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](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | | `state` | string | The state of a connection in the pool | `idle` | Required | `state` MUST be one of the following: @@ -68,7 +68,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | 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](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | ### Metric: `db.client.connections.idle.min` @@ -84,7 +84,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | 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](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | ### Metric: `db.client.connections.max` @@ -100,7 +100,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | 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](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | ### Metric: `db.client.connections.pending_requests` @@ -116,7 +116,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | 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](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | ### Metric: `db.client.connections.timeouts` @@ -132,7 +132,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | 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](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | ### Metric: `db.client.connections.create_time` @@ -148,7 +148,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | 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](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | ### Metric: `db.client.connections.wait_time` @@ -164,7 +164,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | 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](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | ### Metric: `db.client.connections.use_time` @@ -180,7 +180,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | 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](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | +| `pool.name` | string | The name of the connection pool; unique within the instrumented application. In case the connection pool implementation doesn't provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used | `myDataSource` | Required | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index cc995d3d37..b352e48252 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -41,8 +41,7 @@ linkTitle: Client Calls > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version > for at least six months after it starts emitting both sets of conventions. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). +> * SHOULD drop the environment variable in the next major version. **Span kind:** MUST always be `CLIENT`. @@ -61,31 +60,31 @@ When it's otherwise impossible to get any meaningful span name, `db.name` or the 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.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.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.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended | -| [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended: If different than `server.address`. | -| [`network.peer.port`](../general/attributes.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | -| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the database host. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`db.connection_string`](../attributes-registry/db.md) | 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.instance.id`](../attributes-registry/db.md) | string | An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. The client may obtain this value in databases like MySQL using queries like `select @@hostname`. | `mysql-e26b99z.example.com` | Recommended: If different from the `server.address` | +| [`db.system`](../attributes-registry/db.md) | 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.user`](../attributes-registry/db.md) | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended | +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Name of the database host. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | **[1]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport, for example +a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. **[2]:** The value SHOULD be normalized to lowercase. -**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent -the server address behind any intermediaries (e.g. proxies) if it's available. +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[5]:** If using a port other than the default port for this DBMS and if `server.address` is set. @@ -145,6 +144,22 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | `clickhouse` | ClickHouse | | `spanner` | Cloud Spanner | | `trino` | Trino | + +`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. | +| `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 | ### Notes and well-known identifiers for `db.system` @@ -170,12 +185,12 @@ When additional attributes are added that only apply to a specific DBMS, its ide 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.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. [2] | `findAndModify`; `HMSET`; `SELECT` | Conditionally Required: If `db.statement` is not applicable. | -| `db.statement` | string | The database statement being executed. | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | Recommended: [3] | +| [`db.name`](../attributes-registry/db.md) | 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.operation`](../attributes-registry/db.md) | 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. [2] | `findAndModify`; `HMSET`; `SELECT` | Conditionally Required: If `db.statement` is not applicable. | +| [`db.statement`](../attributes-registry/db.md) | string | The database statement being executed. | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | Recommended: [3] | **[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). diff --git a/docs/database/dynamodb.md b/docs/database/dynamodb.md index 61299804a6..137ebc6f37 100644 --- a/docs/database/dynamodb.md +++ b/docs/database/dynamodb.md @@ -19,7 +19,7 @@ These attributes are filled in for all DynamoDB request types. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`db.system`](database-spans.md) | string | The value `dynamodb`. | `dynamodb` | Required | +| [`db.system`](../attributes-registry/db.md) | string | The value `dynamodb`. | `dynamodb` | Required | ## DynamoDB.BatchGetItem diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 74e956557f..156e7cb15f 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -23,18 +23,18 @@ If the endpoint id is not available, the span name SHOULD be the `http.request.m ## Call-level attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `db.elasticsearch.cluster.name` | string | Represents the identifier of an Elasticsearch cluster. | `e9106fc68e3044f0b1475b04bf4ffd5f` | Recommended: [1] | -| `db.elasticsearch.node.name` | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | Recommended: [2] | -| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. [3] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | Conditionally Required: when the url has dynamic values | -| [`db.operation`](database-spans.md) | string | The endpoint identifier for the request. [4] | `search`; `ml.close_job`; `cat.aliases` | Required | -| [`db.statement`](database-spans.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | Recommended: [5] | +| [`db.elasticsearch.cluster.name`](../attributes-registry/db.md) | string | Represents the identifier of an Elasticsearch cluster. | `e9106fc68e3044f0b1475b04bf4ffd5f` | Recommended: [1] | +| [`db.elasticsearch.node.name`](../attributes-registry/db.md) | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | Recommended: [2] | +| [`db.elasticsearch.path_parts.`](../attributes-registry/db.md) | string | A dynamic value in the url path. [3] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | Conditionally Required: when the url has dynamic values | +| [`db.operation`](../attributes-registry/db.md) | string | The endpoint identifier for the request. [4] | `search`; `ml.close_job`; `cat.aliases` | Required | +| [`db.statement`](../attributes-registry/db.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | Recommended: [5] | | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [6] | `GET`; `POST`; `HEAD` | Required | -| [`server.address`](../general/attributes.md) | string | Name of the database host. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number. [8] | `80`; `8080`; `443` | Conditionally Required: [9] | -| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [10] | `https://localhost:9200/index/_search?q=user.id:kimchy` | Required | +| [`server.address`](../attributes-registry/server.md) | string | Name of the database host. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [8] | `80`; `8080`; `443` | Conditionally Required: [9] | +| [`url.full`](../attributes-registry/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [10] | `https://localhost:9200/index/_search?q=user.id:kimchy` | Required | **[1]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. @@ -61,16 +61,30 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[7]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent -the server address behind any intermediaries (e.g. proxies) if it's available. +**[7]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[8]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[8]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[10]:** 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/`. +**[10]:** 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. + +`http.request.method` 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 | +|---|---| +| `CONNECT` | CONNECT method. | +| `DELETE` | DELETE method. | +| `GET` | GET method. | +| `HEAD` | HEAD method. | +| `OPTIONS` | OPTIONS method. | +| `PATCH` | PATCH method. | +| `POST` | POST method. | +| `PUT` | PUT method. | +| `TRACE` | TRACE method. | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | ## Example diff --git a/docs/database/hbase.md b/docs/database/hbase.md index 8cbc9d41a1..47b8acd2c5 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -14,10 +14,10 @@ described on this page. ## Call-level attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`db.name`](database-spans.md) | string | The HBase namespace. [1] | `mynamespace` | Conditionally Required: If applicable. | +| [`db.name`](../attributes-registry/db.md) | string | The HBase namespace. [1] | `mynamespace` | Conditionally Required: If applicable. | **[1]:** For HBase the `db.name` should be set to the HBase namespace. diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index debad64014..10fdbb785e 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -14,10 +14,10 @@ described on this page. ## Call-level attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `db.mongodb.collection` | string | The collection being accessed within the database stated in `db.name`. | `customers`; `products` | Required | +| [`db.mongodb.collection`](../attributes-registry/db.md) | string | The MongoDB collection being accessed within the database stated in `db.name`. | `customers`; `products` | Required | ## Example @@ -29,9 +29,10 @@ described on this page. | `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"` | +| `network.peer.address` | `"192.0.2.14"` | +| `network.peer.port` | `27017` | +| `network.transport` | `"tcp"` | | `db.name` | `"shopDb"` | | `db.statement` | not set | | `db.operation` | `"findAndModify"` | diff --git a/docs/database/mssql.md b/docs/database/mssql.md index b64cf49678..763e7a1b12 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -14,11 +14,11 @@ described on this page. ## Connection-level attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`db.jdbc.driver_classname`](database-spans.md) | 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 | +| [`db.jdbc.driver_classname`](../attributes-registry/db.md) | 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`](../attributes-registry/db.md) | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/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). diff --git a/docs/database/redis.md b/docs/database/redis.md index 9be10a987b..2614e494fa 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -14,11 +14,11 @@ described on this page. ## Call-level attributes - + | 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.statement`](database-spans.md) | string | The full syntax of the Redis CLI command. [1] | `HMSET myhash field1 'Hello' field2 'World'` | Recommended: [2] | +| [`db.redis.database_index`](../attributes-registry/db.md) | 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.statement`](../attributes-registry/db.md) | string | The full syntax of the Redis CLI command. [1] | `HMSET myhash field1 'Hello' field2 'World'` | Recommended: [2] | **[1]:** For **Redis**, the value provided for `db.statement` SHOULD correspond to the syntax of the Redis CLI. If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.statement`. @@ -27,7 +27,7 @@ described on this page. ## Example -In this example, Redis is connected using a unix domain socket and therefore the connection string and `server.address` are left out. +In this example, Redis is connected using a unix domain socket and therefore the connection string is 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 | @@ -36,8 +36,8 @@ Furthermore, `db.name` is not specified as there is no database name in Redis an | `db.system` | `"redis"` | | `db.connection_string` | not set | | `db.user` | not set | -| `server.socket.address` | `"/tmp/redis.sock"` | -| `network.transport` | `"Unix"` | +| `network.peer.address` | `"/tmp/redis.sock"` | +| `network.transport` | `"unix"` | | `db.name` | not set | | `db.statement` | `"HMSET myhash field1 'Hello' field2 'World"` | | `db.operation` | not set | diff --git a/docs/database/sql.md b/docs/database/sql.md index 70beb8eead..6483e36374 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -12,10 +12,10 @@ described on this page. ## Call-level attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `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 | +| [`db.sql.table`](../attributes-registry/db.md) | 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. @@ -31,9 +31,10 @@ This is an example of attributes for a MySQL database span: | `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"` | +| `network.peer.address` | `"192.0.2.12"` | +| `network.peer.port` | `3306` | +| `network.transport` | `"tcp"` | | `db.name` | `"ShopDb"` | | `db.statement` | `"SELECT * FROM orders WHERE order_id = 'o4711'"` | | `db.operation` | `"SELECT"` | diff --git a/docs/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md index ec64eb86bc..71f929a2a6 100644 --- a/docs/exceptions/exceptions-spans.md +++ b/docs/exceptions/exceptions-spans.md @@ -104,7 +104,7 @@ grained information from a stacktrace, if necessary. [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 +[csharp-stacktrace]: https://docs.microsoft.com/dotnet/api/system.exception.tostring [go-stacktrace]: https://pkg.go.dev/runtime/debug#Stack [telemetry-sdk-resource]: ../resource/README.md#telemetry-sdk [erlang-stacktrace]: https://www.erlang.org/doc/man/erl_error.html#format_exception-3 diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 50dba92033..e0f7800a39 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -66,7 +66,7 @@ contain an incomplete trace context which indicates X-Ray isn’t enabled. The e `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. -**Note**: When instrumenting a Java AWS Lambda, instrumentation SHOULD first try to parse an OpenTelemetry `Context` out of the system property `com.amazonaws.xray.traceHeader` using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/api-propagators.md) before checking and attempting to parse the environment variable above. +**Note**: When instrumenting a Java AWS Lambda, instrumentation SHOULD first try to parse an OpenTelemetry `Context` out of the system property `com.amazonaws.xray.traceHeader` using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/context/api-propagators.md) before checking and attempting to parse the environment variable above. [Span Link]: https://opentelemetry.io/docs/concepts/signals/traces/#span-links diff --git a/docs/faas/faas-metrics.md b/docs/faas/faas-metrics.md index b64d90dd01..e84a0921dc 100644 --- a/docs/faas/faas-metrics.md +++ b/docs/faas/faas-metrics.md @@ -45,10 +45,14 @@ The following metrics are recorded by the FaaS instance. This metric is [recommended][MetricRecommended]. +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advice) +of `[ 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 | | -------- | --------------- | ----------- | -------------- | -| `faas.invoke_duration` | Histogram | `ms` | Measures the duration of the function's logic execution | +| `faas.invoke_duration` | Histogram | `s` | Measures the duration of the function's logic execution | @@ -71,10 +75,14 @@ This metric is [recommended][MetricRecommended]. This metric is [recommended][MetricRecommended]. +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advice) +of `[ 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 | | -------- | --------------- | ----------- | -------------- | -| `faas.init_duration` | Histogram | `ms` | Measures the duration of the function's initialization, such as a cold start | +| `faas.init_duration` | Histogram | `s` | Measures the duration of the function's initialization, such as a cold start | @@ -227,10 +235,14 @@ This metric is [recommended][MetricRecommended]. This metric is [recommended][MetricRecommended]. +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advice) +of `[ 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 | | -------- | --------------- | ----------- | -------------- | -| `faas.cpu_usage` | Histogram | `ms` | Distribution of CPU usage per invocation | +| `faas.cpu_usage` | Histogram | `s` | Distribution of CPU usage per invocation | diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md index 3a9f50c2ad..8088cf7c42 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -41,7 +41,7 @@ If Spans following this convention are produced, a Resource of type `faas` MUST | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`cloud.resource_id`](../resource/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) [1] | `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.resource_id`](../attributes-registry/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/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) [1] | `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 | | `faas.invocation_id` | string | The invocation ID of the current function invocation. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | Recommended | | `faas.trigger` | string | Type of the trigger which caused this function invocation. [2] | `datasource` | Recommended | @@ -57,7 +57,7 @@ The following well-known definitions MUST be used if you set this attribute and 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, +* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/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 @@ -108,7 +108,7 @@ The span attribute `faas.invocation_id` differs from the [resource attribute][Fa - `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 +[Azure functions]: https://docs.microsoft.com/azure/azure-functions/manage-connections#static-clients [Google functions]: https://cloud.google.com/functions/docs/concepts/exec#function_scope_versus_global_scope ## Incoming Invocations diff --git a/docs/general/attribute-naming.md b/docs/general/attribute-naming.md new file mode 100644 index 0000000000..b84f71f03e --- /dev/null +++ b/docs/general/attribute-naming.md @@ -0,0 +1,158 @@ +# Attribute Naming + +**Status**: [Stable][DocumentStatus] + +
+Table of Contents + + + +- [Name Pluralization guidelines](#name-pluralization-guidelines) +- [Name Reuse Prohibition](#name-reuse-prohibition) +- [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors) +- [Recommendations for Application Developers](#recommendations-for-application-developers) +- [otel.\* Namespace](#otel-namespace) + + + +
+ +_This section applies to Resource, Span, Log, and Metric attribute names (also +known as the "attribute keys"). For brevity within this section when we use the +term "name" without an adjective it is implied to mean "attribute name"._ + +Every name MUST be a valid Unicode sequence. + +_Note: we merely require that the names are represented as Unicode sequences. +This specification does not define how exactly the Unicode sequences are +encoded. The encoding can vary from one programming language to another and from +one wire format to another. Use the idiomatic way to represent Unicode in the +particular programming language or wire format._ + +Names SHOULD follow these rules: + +- Use namespacing to avoid name clashes. Delimit the namespaces using a dot + character. For example `service.version` denotes the service version where + `service` is the namespace and `version` is an attribute in that namespace. + +- Namespaces can be nested. For example `telemetry.sdk` is a namespace inside + top-level `telemetry` namespace and `telemetry.sdk.name` is an attribute + inside `telemetry.sdk` namespace. Note: the fact that an entity is located + within another entity is typically not a sufficient reason for forming nested + namespaces. The purpose of a namespace is to avoid name clashes, not to + indicate entity hierarchies. This purpose should primarily drive the decision + about forming nested namespaces. + +- For each multi-word dot-delimited component of the attribute name separate the + words by underscores (i.e. use snake_case). For example + `http.response.status_code` denotes the status code in the http namespace. + +- Names SHOULD NOT coincide with namespaces. For example if + `service.instance.id` is an attribute name then it is no longer valid to have + an attribute named `service.instance` because `service.instance` is already a + namespace. Because of this rule be careful when choosing names: every existing + name prohibits existence of an equally named namespace in the future, and vice + versa: any existing namespace prohibits existence of an equally named + attribute key in the future. + +## Name Pluralization guidelines + +- When an attribute represents a single entity, the attribute name SHOULD be + singular. Examples: `host.name`, `db.user`, `container.id`. + +- When attribute can represent multiple entities, the attribute name SHOULD be + pluralized and the value type SHOULD be an array. E.g. `process.command_args` + might include multiple values: the executable name and command arguments. + +- When an attribute represents a measurement, + [Metric Name Pluralization Guidelines](./metrics.md#pluralization) SHOULD be + followed for the attribute name. + +## Name Reuse Prohibition + +A new attribute MUST NOT be added with the same name as an attribute that +existed in the past but was renamed (with a corresponding schema file). + +When introducing a new attribute name check all existing schema files to make +sure the name does not appear as a key of any "rename_attributes" section (keys +denote old attribute names in rename operations). + +## Recommendations for OpenTelemetry Authors + +- All names that are part of OpenTelemetry semantic conventions SHOULD be part + of a namespace. + +- When coming up with a new semantic convention make sure to check existing + namespaces ([Semantic Conventions](./README.md)) to see if the new name fits. + +- When a new namespace is necessary consider whether it should be a top-level + namespace (e.g. `service`) or a nested namespace (e.g. `service.instance`). + +- Semantic conventions exist for four areas: for Resource, Span, Log, and Metric + attribute names. In addition, for spans we have two more areas: Event and Link + attribute names. Identical namespaces or names in all these areas MUST have + identical meanings. For example the `http.request.method` span attribute name + denotes exactly the same concept as the `http.request.method` metric + attribute, has the same data type and the same set of possible values (in both + cases it records the value of the HTTP protocol's request method as a string). + +- Semantic conventions MUST limit names to printable Basic Latin characters + (more precisely to + [U+0021 .. U+007E]() + subset of Unicode code points). It is recommended to further limit names to + the following Unicode code points: Latin alphabet, Numeric, Underscore, Dot + (as namespace delimiter). + +## Recommendations for Application Developers + +As an application developer when you need to record an attribute first consult +existing [semantic conventions](./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: + +- The name is specific to your company and may be possibly used outside the + company as well. To avoid clashes with names introduced by other companies (in + a distributed system that uses applications from multiple vendors) it is + recommended to prefix the new name by your company's reverse domain name, e.g. + `com.acme.shopname`. + +- The name is specific to your application that will be used internally only. If + you already have an internal company process that helps you to ensure no name + clashes happen then feel free to follow it. Otherwise it is recommended to + prefix the attribute name by your application name, provided that the + application name is reasonably unique within your organization (e.g. + `myuniquemapapp.longitude` is likely fine). Make sure the application name + does not clash with an existing semantic convention namespace. + +- It is not recommended to use existing OpenTelemetry semantic convention + namespace as a prefix for a new company- or application-specific attribute + name. Doing so may result in a name clash in the future, if OpenTelemetry + decides to use that same name for a different purpose or if some other third + party instrumentation decides to use that exact same attribute name and you + combine that instrumentation with your own. + +- The name may be generally applicable to applications in the industry. In that + case consider submitting a proposal to this specification to add a new name to + the semantic conventions, and if necessary also to add a new namespace. + +It is recommended to limit names to printable Basic Latin characters (more +precisely to +[U+0021 .. U+007E]() +subset of Unicode code points). + +## otel.\* Namespace + +Attribute names that start with `otel.` are reserved to be defined by +OpenTelemetry specification. These are typically used to express OpenTelemetry +concepts in formats that don't have a corresponding concept. + +For example, the `otel.scope.name` attribute is used to record the +instrumentation scope name, which is an OpenTelemetry concept that is natively +represented in OTLP, but does not have an equivalent in other telemetry formats +and protocols. + +Any additions to the `otel.*` namespace MUST be approved as part of +OpenTelemetry specification. + +[DocumentStatus]: + https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/general/attribute-requirement-level.md b/docs/general/attribute-requirement-level.md new file mode 100644 index 0000000000..4fe6ddb9dd --- /dev/null +++ b/docs/general/attribute-requirement-level.md @@ -0,0 +1,127 @@ +# Attribute Requirement Levels + +**Status**: [Stable][DocumentStatus] + +
+Table of Contents + + + +- [Required](#required) +- [Conditionally Required](#conditionally-required) +- [Recommended](#recommended) +- [Opt-In](#opt-in) +- [Performance suggestions](#performance-suggestions) + + + +
+ +_This section applies to Log, Metric, Resource, and Span, and describes +requirement levels for attributes defined in semantic conventions._ + +Attribute requirement levels apply to the +[instrumentation library](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/glossary.md#instrumentation-library). + +The following attribute requirement levels are specified: + +- [Required](#required) +- [Conditionally Required](#conditionally-required) +- [Recommended](#recommended) +- [Opt-In](#opt-in) + +The requirement level for an attribute is specified by semantic conventions +depending on attribute availability across instrumented entities, performance, +security, and other factors. When specifying requirement levels, a semantic +convention MUST take into account signal-specific requirements. + +For example, Metric attributes that may have high cardinality can only be +defined with `Opt-In` level. + +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](../database/README.md) references +`network.transport` attribute defined in [General attributes](./README.md) with +`Conditionally Required` level on it. + +## Required + +All instrumentations MUST populate the attribute. A semantic convention defining +a Required attribute expects an absolute majority of instrumentation libraries +and applications are able to efficiently retrieve and populate it, and can +additionally meet requirements for cardinality, security, and any others +specific to the signal defined by the convention. `http.request.method` is an +example of a Required attribute. + +_Note: Consumers of telemetry can detect if a telemetry item follows a specific +semantic convention by checking for the presence of a `Required` attribute +defined by such convention. For example, the presence of the `db.system` +attribute on a span can be used as an indication that the span follows database +semantics._ + +## Conditionally Required + +All instrumentations MUST populate the attribute when the given condition is +satisfied. The semantic convention of a `Conditionally Required` attribute MUST +clarify the condition under which the attribute is to be populated. + +`http.route` is an example of a conditionally required attribute that is +populated when the instrumented HTTP framework provides route information for +the instrumented request. Some low-level HTTP server implementations do not +support routing and corresponding instrumentations can't populate the attribute. + +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](../database/README.md) when available. When +`network.peer.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 + +Instrumentations SHOULD add the attribute by default if it's readily available +and can be [efficiently populated](#performance-suggestions). Instrumentations +MAY offer a configuration option to disable Recommended attributes. + +Instrumentations that decide not to populate `Recommended` attributes due to +[performance](#performance-suggestions), security, privacy, or other +consideration by default, SHOULD allow for users to opt-in to emit them as +defined for the `Opt-In` requirement level (if the attributes are logically +applicable). + +## Opt-In + +Instrumentations SHOULD populate the attribute if and only if the user +configures the instrumentation to do so. Instrumentation that doesn't support +configuration MUST NOT populate `Opt-In` attributes. + +This attribute requirement level is recommended for attributes that are +particularly expensive to retrieve or might pose a security or privacy risk. +These should therefore only be enabled explicitly by a user making an informed +decision. + +## Performance suggestions + +Here are several examples of expensive operations to be avoided by default: + +- DNS lookups to populate `server.address` when only an IP address is available + to the instrumentation. Caching lookup results does not solve the issue for + all possible cases and should be avoided by default too. +- forcing an `http.route` calculation before the HTTP framework calculates it +- reading response stream to find `http.response.body.size` when + `Content-Length` header is not available + +[DocumentStatus]: + https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/general/attributes.md b/docs/general/attributes.md index 6a8793df65..e9f9dddad7 100644 --- a/docs/general/attributes.md +++ b/docs/general/attributes.md @@ -66,16 +66,15 @@ identify the transport, then setting [`network.transport`](#other-network-attrib 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 | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| `server.port` | int | Server port number. [2] | `80`; `8080`; `443` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | Recommended | -**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent -the server address behind any intermediaries (e.g. proxies) if it's available. +**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `server.address` and `server.port` represent logical server name and port. Semantic conventions that refer to these attributes SHOULD @@ -104,15 +103,15 @@ For Unix domain socket, `server.address` attribute represents remote endpoint ad 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 - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| `client.port` | int | Client port number. [2] | `65123` | Recommended | +| [`client.address`](../attributes-registry/client.md) | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`client.port`](../attributes-registry/client.md) | int | Client port number. [2] | `65123` | Recommended | -**[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries (e.g. proxies) if it's available. +**[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. -**[2]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port 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 the client port behind any intermediaries, for example proxies, if it's available. ### Source and destination attributes @@ -126,26 +125,26 @@ This also covers unidirectional UDP flows and peer-to-peer communication where t #### Source - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `source.address` | string | Source address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `source.example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| `source.port` | int | Source port number | `3389`; `2888` | Recommended | +| [`source.address`](../attributes-registry/source.md) | string | Source address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `source.example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`source.port`](../attributes-registry/source.md) | int | Source port number | `3389`; `2888` | Recommended | -**[1]:** When observed from the destination side, and when communicating through an intermediary, `source.address` SHOULD represent the source address behind any intermediaries (e.g. proxies) if it's available. +**[1]:** When observed from the destination side, and when communicating through an intermediary, `source.address` SHOULD represent the source address behind any intermediaries, for example proxies, if it's available. #### Destination Destination fields capture details about the receiver of a network exchange/packet. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `destination.address` | string | Destination address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `destination.example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| `destination.port` | int | Destination port number | `3389`; `2888` | Recommended | +| [`destination.address`](../attributes-registry/destination.md) | string | Destination address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `destination.example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`destination.port`](../attributes-registry/destination.md) | int | Destination port number | `3389`; `2888` | Recommended | -**[1]:** When observed from the source side, and when communicating through an intermediary, `destination.address` SHOULD represent the destination address behind any intermediaries (e.g. proxies) if it's available. +**[1]:** When observed from the source side, and when communicating through an intermediary, `destination.address` SHOULD represent the destination address behind any intermediaries, for example proxies, if it's available. @@ -157,26 +156,26 @@ Destination fields capture details about the receiver of a network exchange/pack 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.local.address` | string | Local address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | -| `network.local.port` | int | Local port number of the network connection. | `65123` | Recommended | -| `network.peer.address` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | -| `network.peer.port` | int | Peer port number of the network connection. | `65123` | Recommended | -| `network.protocol.name` | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [1] | `amqp`; `http`; `mqtt` | Recommended | -| `network.protocol.version` | string | Version of the protocol specified in `network.protocol.name`. [2] | `3.1.1` | Recommended | -| `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). [3] | `tcp`; `udp` | Recommended | -| `network.type` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | Recommended | +| [`network.local.address`](../attributes-registry/network.md) | string | Local address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.local.port`](../attributes-registry/network.md) | int | Local port number of the network connection. | `65123` | Recommended | +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended | +| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [1] | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `3.1.1` | Recommended | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. -**[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`. +**[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 has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. **[3]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport, for example +a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. **[4]:** The value SHOULD be normalized to lowercase. @@ -187,7 +186,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. |---|---| | `tcp` | TCP | | `udp` | UDP | -| `pipe` | Named or anonymous pipe. See note below. | +| `pipe` | Named or anonymous pipe. | | `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. @@ -239,15 +238,15 @@ Note that `network.local.*` attributes are not included in these examples since #### Network connection and carrier attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `network.carrier.icc` | string | The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. | `DE` | 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.name` | string | The name of the mobile carrier. | `sprint` | 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.connection.type` | string | The internet connection type. | `wifi` | Recommended | +| [`network.carrier.icc`](../attributes-registry/network.md) | string | The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. | `DE` | Recommended | +| [`network.carrier.mcc`](../attributes-registry/network.md) | string | The mobile carrier country code. | `310` | Recommended | +| [`network.carrier.mnc`](../attributes-registry/network.md) | string | The mobile carrier network code. | `001` | Recommended | +| [`network.carrier.name`](../attributes-registry/network.md) | string | The name of the mobile carrier. | `sprint` | Recommended | +| [`network.connection.subtype`](../attributes-registry/network.md) | 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.connection.type`](../attributes-registry/network.md) | string | The internet connection type. | `wifi` | Recommended | `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. @@ -345,7 +344,7 @@ Examples of where the `enduser.id` value is extracted from: [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 +[Windows Communication Foundation]: https://docs.microsoft.com/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 @@ -359,21 +358,20 @@ a thread that started a span. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `thread.daemon` | boolean | Whether the thread is daemon or not. | | Recommended | -| `thread.id` | int | Current "managed" thread ID (as opposed to OS thread ID). | `42` | Recommended | -| `thread.name` | string | Current thread name. | `main` | Recommended | +| [`thread.id`](../attributes-registry/thread.md) | int | Current "managed" thread ID (as opposed to OS thread ID). | `42` | Recommended | +| [`thread.name`](../attributes-registry/thread.md) | 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)` | | +| 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:self()` | `erlang:process_info(self(), registered_name)` | ## Source Code Attributes @@ -386,11 +384,12 @@ about the span. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `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 | -| `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.function` | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `serveRequest` | 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.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.column`](../attributes-registry/code.md) | int | The column number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `16` | Recommended | +| [`code.filepath`](../attributes-registry/code.md) | 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.function`](../attributes-registry/code.md) | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `serveRequest` | Recommended | +| [`code.lineno`](../attributes-registry/code.md) | 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.namespace`](../attributes-registry/code.md) | 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.stacktrace`](../attributes-registry/code.md) | 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. | `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)` | Opt-In | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/general/events.md b/docs/general/events.md index 8c9a0c05a7..8fcd24cf8a 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -17,20 +17,10 @@ The following semantic conventions for events are defined: ## General event attributes -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. +Events are recorded as LogRecords that are shaped in a special way: Event +LogRecords have the attribute `event.name` that uniquely identifies the event. +Events with same `event.name` are structurally similar to one another. Events +may also have other LogRecord attributes. 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 @@ -43,19 +33,9 @@ that identify the class of Events but not the instance of the Event. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `event.domain` | string | The domain identifies the business context for the events. [1] | `browser` | Required | -| `event.name` | string | The name identifies the event. | `click`; `exception` | 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. +| `event.name` | string | Identifies the class / type of event. [1] | `browser.mouse.click`; `device.app.lifecycle` | Required | -| Value | Description | -|---|---| -| `browser` | Events from browser apps | -| `device` | Events from mobile apps | -| `k8s` | Events from Kubernetes | +**[1]:** Event names are subject to the same rules as [attribute names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/common/attribute-naming.md). Notably, event names are namespaced to avoid collisions and provide a clean separation of semantics for events in separate domains like browser, mobile, and kubernetes. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 6defc732af..74699fbad0 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -28,7 +28,7 @@ The following semantic conventions surrounding metrics are defined: * **[General Guidelines](#general-guidelines): General metrics guidelines.** * [Database](/docs/database/database-metrics.md): For SQL and NoSQL client metrics. -* [FaaS](/docs/faas/faas-metrics.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) metrics. +* [FaaS](/docs/faas/faas-metrics.md): For [Function as a Service](https://wikipedia.org/wiki/Function_as_a_service) metrics. * [HTTP](/docs/http/http-metrics.md): For HTTP client and server metrics. * [RPC](/docs/rpc/rpc-metrics.md): For RPC client and server metrics. * **System metrics** @@ -105,9 +105,11 @@ using the OpenMetrics exposition format, use the #### Pluralization +Metric namespaces SHOULD NOT be pluralized. + 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). +[countable quantity](https://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}`). @@ -122,12 +124,10 @@ should be pluralized, even if only a single data point is recorded. 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 +For example if we have a namespace `system.process` 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`. +`system.process.count`. #### Do not use `total` diff --git a/docs/general/session.md b/docs/general/session.md index c6d5c55920..9c58d3fc44 100644 --- a/docs/general/session.md +++ b/docs/general/session.md @@ -11,12 +11,17 @@ Consequently, a Session is represented as a collection of Logs, Events, and Span throughout the Session's duration. Each Session is assigned a unique identifier, which is included as an attribute in the Logs, Events, and Spans generated during the Session's lifecycle. +When a session reaches end of life, typically due to user inactivity or session timeout, a new session identifier +will be assigned. The previous session identifier may be provided by the instrumentation so that telemetry +backends can link the two sessions. + ## Attributes | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `session.id` | string | A unique id to identify a session. | `00112233-4455-6677-8899-aabbccddeeff` | Opt-In | +| `session.previous_id` | string | The previous `session.id` for this user, when known. | `00112233-4455-6677-8899-aabbccddeeff` | Opt-In | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/general/trace-compatibility.md b/docs/general/trace-compatibility.md index 54e02fcf92..bfac2262af 100644 --- a/docs/general/trace-compatibility.md +++ b/docs/general/trace-compatibility.md @@ -36,7 +36,7 @@ between a child Span and a parent Span, as defined by | 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 | +| `follows_from` | The parent Span doesn't depend in any way on the result of the child Span | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/general/trace.md b/docs/general/trace.md index 01a99b61c4..2397794348 100644 --- a/docs/general/trace.md +++ b/docs/general/trace.md @@ -26,7 +26,7 @@ The following semantic conventions for spans are defined: * [Cloud Providers](/docs/cloud-providers/README.md): Semantic Conventions for cloud providers spans. * [Database](/docs/database/database-spans.md): For SQL and NoSQL client call spans. * [Exceptions](/docs/exceptions/exceptions-spans.md): For recording exceptions associated with a span. -* [FaaS](/docs/faas/faas-spans.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) (e.g., AWS Lambda) spans. +* [FaaS](/docs/faas/faas-spans.md): For [Function as a Service](https://wikipedia.org/wiki/Function_as_a_service) (e.g., AWS Lambda) spans. * [Feature Flags](/docs/feature-flags/feature-flags-spans.md): For recording feature flag evaluations associated with a span. * [HTTP](/docs/http/http-spans.md): For HTTP client and server spans. * [Messaging](/docs/messaging/messaging-spans.md): For messaging systems (queues, publish/subscribe, etc.) spans. diff --git a/docs/http/README.md b/docs/http/README.md index 1c27a324f4..c4ae8a10d2 100644 --- a/docs/http/README.md +++ b/docs/http/README.md @@ -7,7 +7,7 @@ path_base_for_github_subdir: # Semantic Conventions for HTTP -**Status**: [Experimental, Feature-freeze][DocumentStatus] +**Status**: [Mixed][DocumentStatus] This document defines semantic conventions for HTTP spans, metrics and logs. They can be used for http and https schemes @@ -37,8 +37,7 @@ and various HTTP versions like 1.1, 2 and SPDY. > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version > for at least six months after it starts emitting both sets of conventions. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). +> * SHOULD drop the environment variable in the next major version. Semantic conventions for HTTP are defined for the following signals: diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 2da82c97d6..eae37608ed 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -4,7 +4,7 @@ linkTitle: Metrics # Semantic Conventions for HTTP Metrics -**Status**: [Experimental, partial feature-freeze][DocumentStatus] +**Status**: [Mixed][DocumentStatus] 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 @@ -50,21 +50,20 @@ operations. By adding HTTP attributes to metric events it allows for finely tune > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version > for at least six months after it starts emitting both sets of conventions. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). +> * SHOULD drop the environment variable in the next major version. ## HTTP Server ### Metric: `http.server.request.duration` -**Status**: [Experimental, Feature-freeze][DocumentStatus] +**Status**: [Stable][DocumentStatus] This metric is required. When this metric is reported alongside an HTTP server span, the metric value SHOULD be the same as the HTTP server span duration. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advice) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 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 ]`. @@ -76,15 +75,15 @@ of `[ 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 | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | +| [`error.type`](../attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | [`http.response.status_code`](../attributes-registry/http.md) | 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.route`](../attributes-registry/http.md) | string | The matched route (path template in the format used by the respective server framework). See note below [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `http`; `spdy` | Recommended: if not default (`http`). | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `1.0`; `1.1`; `2`; `3` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Opt-In | -| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [7] | `80`; `8080`; `443` | Opt-In | -| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | +| [`http.route`](../attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | +| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `http`; `spdy` | Conditionally Required: [5] | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [6] | `1.0`; `1.1`; `2`; `3` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Opt-In | +| [`server.port`](../attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [8] | `80`; `8080`; `443` | Opt-In | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. [9] | `http`; `https` | Required | **[1]:** If the request fails with an error before response status code was sent or received, `error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) @@ -123,30 +122,27 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin **[4]:** The value SHOULD be normalized to lowercase. -**[5]:** `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`. +**[5]:** If not `http` and `network.protocol.version` is set. -**[6]:** Determined by using the first of the following that applies +**[6]:** `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 has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -- The [primary server name](/docs/http/http-spans.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. +**[7]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +> **Warning** +> Since this attribute is based on HTTP headers, opting in to it may allow an attacker +> to trigger cardinality limits, degrading the usefulness of the metric. -**[7]:** Determined by using the first of the following that applies +**[8]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +> **Warning** +> Since this attribute is based on HTTP headers, opting in to it may allow an attacker +> to trigger cardinality limits, degrading the usefulness of the metric. -- Port identifier of the [primary server host](/docs/http/http-spans.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 +**[9]:** The scheme of the original client request, if known (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request. `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. | Value | Description | |---|---| -| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | `http.request.method` 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. @@ -180,9 +176,9 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Opt-In | -| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [3] | `80`; `8080`; `443` | Opt-In | -| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | +| [`server.address`](../attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Opt-In | +| [`server.port`](../attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [3] | `80`; `8080`; `443` | Opt-In | +| [`url.scheme`](../attributes-registry/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]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) @@ -199,28 +195,15 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[2]:** Determined by using the first of the following that applies - -- The [primary server name](/docs/http/http-spans.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. - -Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker -to trigger cardinality limits, degrading the usefulness of the metric. - -**[3]:** Determined by using the first of the following that applies - -- Port identifier of the [primary server host](/docs/http/http-spans.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 +**[2]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +> **Warning** +> Since this attribute is based on HTTP headers, opting in to it may allow an attacker +> to trigger cardinality limits, degrading the usefulness of the metric. -Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker -to trigger cardinality limits, degrading the usefulness of the metric. +**[3]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +> **Warning** +> Since this attribute is based on HTTP headers, opting in to it may allow an attacker +> to trigger cardinality limits, degrading the usefulness of the metric. `http.request.method` 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. @@ -255,15 +238,15 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | +| [`error.type`](../attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | [`http.response.status_code`](../attributes-registry/http.md) | 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.route`](../attributes-registry/http.md) | string | The matched route (path template in the format used by the respective server framework). See note below [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `http`; `spdy` | Recommended: if not default (`http`). | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `1.0`; `1.1`; `2`; `3` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Opt-In | -| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [7] | `80`; `8080`; `443` | Opt-In | -| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | +| [`http.route`](../attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | +| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `http`; `spdy` | Conditionally Required: [5] | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [6] | `1.0`; `1.1`; `2`; `3` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Opt-In | +| [`server.port`](../attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [8] | `80`; `8080`; `443` | Opt-In | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. [9] | `http`; `https` | Required | **[1]:** If the request fails with an error before response status code was sent or received, `error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) @@ -302,30 +285,27 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin **[4]:** The value SHOULD be normalized to lowercase. -**[5]:** `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`. - -**[6]:** Determined by using the first of the following that applies +**[5]:** If not `http` and `network.protocol.version` is set. -- The [primary server name](/docs/http/http-spans.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 +**[6]:** `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 has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. +**[7]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +> **Warning** +> Since this attribute is based on HTTP headers, opting in to it may allow an attacker +> to trigger cardinality limits, degrading the usefulness of the metric. -**[7]:** Determined by using the first of the following that applies +**[8]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +> **Warning** +> Since this attribute is based on HTTP headers, opting in to it may allow an attacker +> to trigger cardinality limits, degrading the usefulness of the metric. -- Port identifier of the [primary server host](/docs/http/http-spans.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 +**[9]:** The scheme of the original client request, if known (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request. `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. | Value | Description | |---|---| -| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | `http.request.method` 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. @@ -360,15 +340,15 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | +| [`error.type`](../attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | [`http.response.status_code`](../attributes-registry/http.md) | 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.route`](../attributes-registry/http.md) | string | The matched route (path template in the format used by the respective server framework). See note below [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `http`; `spdy` | Recommended: if not default (`http`). | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `1.0`; `1.1`; `2`; `3` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Opt-In | -| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [7] | `80`; `8080`; `443` | Opt-In | -| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | +| [`http.route`](../attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | +| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `http`; `spdy` | Conditionally Required: [5] | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [6] | `1.0`; `1.1`; `2`; `3` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Opt-In | +| [`server.port`](../attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [8] | `80`; `8080`; `443` | Opt-In | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. [9] | `http`; `https` | Required | **[1]:** If the request fails with an error before response status code was sent or received, `error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) @@ -407,30 +387,27 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin **[4]:** The value SHOULD be normalized to lowercase. -**[5]:** `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`. - -**[6]:** Determined by using the first of the following that applies +**[5]:** If not `http` and `network.protocol.version` is set. -- The [primary server name](/docs/http/http-spans.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 +**[6]:** `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 has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. +**[7]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +> **Warning** +> Since this attribute is based on HTTP headers, opting in to it may allow an attacker +> to trigger cardinality limits, degrading the usefulness of the metric. -**[7]:** Determined by using the first of the following that applies +**[8]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +> **Warning** +> Since this attribute is based on HTTP headers, opting in to it may allow an attacker +> to trigger cardinality limits, degrading the usefulness of the metric. -- Port identifier of the [primary server host](/docs/http/http-spans.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 +**[9]:** The scheme of the original client request, if known (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request. `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. | Value | Description | |---|---| -| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | `http.request.method` 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. @@ -452,14 +429,14 @@ SHOULD NOT be set if only IP address is available and capturing name would requi ### Metric: `http.client.request.duration` -**Status**: [Experimental, Feature-freeze][DocumentStatus] +**Status**: [Stable][DocumentStatus] This metric is required. When this metric is reported alongside an HTTP client span, the metric value SHOULD be the same as the HTTP client span duration. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advice) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 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 ]`. @@ -471,14 +448,14 @@ of `[ 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 | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | +| [`error.type`](../attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | [`http.response.status_code`](../attributes-registry/http.md) | 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`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `http`; `spdy` | Recommended: if not default (`http`). | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [4] | `1.0`; `1.1`; `2`; `3` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [6] | `80`; `8080`; `443` | Conditionally Required: [7] | -| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Required | +| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `http`; `spdy` | Conditionally Required: [4] | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `1.0`; `1.1`; `2`; `3` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [7] | `80`; `8080`; `443` | Required | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Opt-In | **[1]:** If the request fails with an error before response status code was sent or received, `error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) @@ -514,26 +491,19 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[3]:** The value SHOULD be normalized to lowercase. -**[4]:** `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`. - -**[5]:** Determined by using the first of the following that applies +**[4]:** If not `http` and `network.protocol.version` is set. -- 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 +**[5]:** `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 has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -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. +**[6]:** 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. -**[6]:** 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. - -**[7]:** If not default (`80` for `http` scheme, `443` for `https`). +**[7]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. | Value | Description | |---|---| -| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | `http.request.method` 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. @@ -568,14 +538,14 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | +| [`error.type`](../attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | [`http.response.status_code`](../attributes-registry/http.md) | 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`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `http`; `spdy` | Recommended: if not default (`http`). | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [4] | `1.0`; `1.1`; `2`; `3` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [6] | `80`; `8080`; `443` | Conditionally Required: [7] | -| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Required | +| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `http`; `spdy` | Conditionally Required: [4] | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `1.0`; `1.1`; `2`; `3` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [7] | `80`; `8080`; `443` | Required | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Opt-In | **[1]:** If the request fails with an error before response status code was sent or received, `error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) @@ -611,26 +581,19 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[3]:** The value SHOULD be normalized to lowercase. -**[4]:** `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`. - -**[5]:** 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 +**[4]:** If not `http` and `network.protocol.version` is set. -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. +**[5]:** `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 has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[6]:** 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. +**[6]:** 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. -**[7]:** If not default (`80` for `http` scheme, `443` for `https`). +**[7]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. | Value | Description | |---|---| -| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | `http.request.method` 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. @@ -665,14 +628,14 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | +| [`error.type`](../attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | [`http.response.status_code`](../attributes-registry/http.md) | 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`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `http`; `spdy` | Recommended: if not default (`http`). | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [4] | `1.0`; `1.1`; `2`; `3` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [6] | `80`; `8080`; `443` | Conditionally Required: [7] | -| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Required | +| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `http`; `spdy` | Conditionally Required: [4] | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `1.0`; `1.1`; `2`; `3` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [7] | `80`; `8080`; `443` | Required | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Opt-In | **[1]:** If the request fails with an error before response status code was sent or received, `error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) @@ -708,26 +671,19 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[3]:** The value SHOULD be normalized to lowercase. -**[4]:** `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`. - -**[5]:** 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 +**[4]:** If not `http` and `network.protocol.version` is set. -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. +**[5]:** `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 has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[6]:** 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. +**[6]:** 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. -**[7]:** If not default (`80` for `http` scheme, `443` for `https`). +**[7]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. | Value | Description | |---|---| -| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | `http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 257ead144c..98bc63d4ba 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -4,7 +4,7 @@ linkTitle: Spans # Semantic Conventions for HTTP Spans -**Status**: [Experimental, Feature-freeze][DocumentStatus] +**Status**: [Stable][DocumentStatus] This document defines semantic conventions for HTTP client and server Spans. They can be used for http and https schemes @@ -22,6 +22,9 @@ and various HTTP versions like 1.1, 2 and SPDY. * [HTTP request retries and redirects](#http-request-retries-and-redirects) - [HTTP server](#http-server) * [HTTP server definitions](#http-server-definitions) + + [Setting `server.address` and `server.port` attributes](#setting-serveraddress-and-serverport-attributes) + + [Simple client/server example](#simple-clientserver-example) + + [Client/server example with reverse proxy](#clientserver-example-with-reverse-proxy) * [HTTP Server semantic conventions](#http-server-semantic-conventions) - [Examples](#examples) * [HTTP client-server example](#http-client-server-example) @@ -58,8 +61,7 @@ and various HTTP versions like 1.1, 2 and SPDY. > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version > for at least six months after it starts emitting both sets of conventions. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). +> * SHOULD drop the environment variable in the next major version. ## Name @@ -74,7 +76,7 @@ If there is no (low-cardinality) `http.route` available, HTTP server span names SHOULD be [`{method}`](#method-placeholder). 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 be +is not generally aware of the "route", and therefore HTTP client span names SHOULD be [`{method}`](#method-placeholder). @@ -115,19 +117,16 @@ sections below. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | -| [`http.request.body.size`](../attributes-registry/http.md) | 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.request.header.`](../attributes-registry/http.md) | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [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.request.method`](../attributes-registry/http.md) | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required | -| [`http.request.method_original`](../attributes-registry/http.md) | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | Conditionally Required: [4] | -| [`http.response.body.size`](../attributes-registry/http.md) | 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.response.header.`](../attributes-registry/http.md) | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [5] | `http.response.header.content_type=["application/json"]`; `http.response.header.my_custom_header=["abc", "def"]` | Opt-In | +| [`error.type`](../attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | +| [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | +| [`http.request.method_original`](../attributes-registry/http.md) | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | Conditionally Required: [3] | +| [`http.response.header.`](../attributes-registry/http.md) | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [4] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | Opt-In | | [`http.response.status_code`](../attributes-registry/http.md) | 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`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [6] | `http`; `spdy` | Recommended: if not default (`http`). | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [7] | `1.0`; `1.1`; `2`; `3` | Recommended | -| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [8] | `tcp`; `udp` | Conditionally Required: [9] | -| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [10] | `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 | +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | +| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [5] | `http`; `spdy` | Conditionally Required: [6] | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [7] | `1.0`; `1.1`; `2`; `3` | Recommended | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [8] | `tcp`; `udp` | Opt-In | **[1]:** If the request fails with an error before response status code was sent or received, `error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) @@ -146,11 +145,7 @@ additional filters are applied. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[2]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request 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. -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. - -**[3]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). @@ -165,27 +160,21 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[4]:** If and only if it's different than `http.request.method`. +**[3]:** If and only if it's different than `http.request.method`. -**[5]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +**[4]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. 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. -**[6]:** The value SHOULD be normalized to lowercase. - -**[7]:** `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`. - -**[8]:** The value SHOULD be normalized to lowercase. +**[5]:** The value SHOULD be normalized to lowercase. -Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport, for example -different processes could be listening on TCP port 12345 and UDP port 12345. +**[6]:** If not `http` and `network.protocol.version` is set. -**[9]:** If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`). +**[7]:** `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 has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[10]:** The value SHOULD be normalized to lowercase. +**[8]:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible. -Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: +The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): * [`http.request.method`](../attributes-registry/http.md) @@ -193,7 +182,7 @@ Following attributes MUST be provided **at span creation time** (when provided a | Value | Description | |---|---| -| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | `http.request.method` 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. @@ -216,15 +205,8 @@ Following attributes MUST be provided **at span creation time** (when provided a |---|---| | `tcp` | TCP | | `udp` | UDP | -| `pipe` | Named or anonymous pipe. See note below. | +| `pipe` | Named or anonymous pipe. | | `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 client @@ -244,41 +226,35 @@ For an HTTP client span, `SpanKind` MUST be `Client`. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`http.resend_count`](../attributes-registry/http.md) | int | The ordinal number of request resending attempt (for any reason, including redirects). [1] | `3` | Recommended: if and only if request was retried. | -| [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended: If different than `server.address`. | -| [`network.peer.port`](../general/attributes.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | -| [`server.address`](../general/attributes.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`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../general/attributes.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] | -| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [5] | `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 +| [`http.request.header.`](../attributes-registry/http.md) | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [1] | `http.request.header.content-type=["application/json"]`; `http.request.header.x-forwarded-for=["1.2.3.4", "1.2.3.5"]` | Opt-In | +| [`http.request.resend_count`](../attributes-registry/http.md) | int | The ordinal number of request resending attempt (for any reason, including redirects). [2] | `3` | Recommended: if and only if request was retried. | +| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Required | +| [`url.full`](../attributes-registry/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [5] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Required | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Opt-In | +| [`user_agent.original`](../attributes-registry/user-agent.md) | 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`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1` | Opt-In | + +**[1]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request 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. +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. -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. +**[2]:** 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). -**[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. +**[3]:** 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. -**[4]:** If not default (`80` for `http` scheme, `443` for `https`). +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[5]:** 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/`. +**[5]:** 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: +The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): -* [`server.address`](../general/attributes.md) -* [`server.port`](../general/attributes.md) -* [`url.full`](../url/url.md) +* [`server.address`](../attributes-registry/server.md) +* [`server.port`](../attributes-registry/server.md) +* [`url.full`](../attributes-registry/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 client span duration There are some minimal constraints that SHOULD be honored: @@ -311,52 +287,47 @@ See the examples for more details about: ## HTTP server -To understand the attributes defined in this section, it is helpful to read the "Definitions" subsection. +Read the following section to understand how HTTP server instrumentations are suggested to capture server information. ### 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 +An HTTP request can be routed to a specific HTTP application via intermediaries such as reverse proxies. +HTTP requests sent to the same domain name may be handled by multiple applications depending on the port, path, headers, or other parameters. + +For example, different versions of the same web-application can run side-by-side as independent applications behind the reverse proxy which routes request to one or another based on the request path. + +Instances of different HTTP server applications may run on the same physical host and share the same IP address, but listen to different TCP/UDP ports. +In order to route the request to a specific application, reverse proxies usually modify the [HTTP Host header][Host and authority] replacing the original value provided by the client with an actual proxied server name. This behavior depends on the reverse proxy configuration. In some cases, the `Host` header is not used when routing request to a specific application, making it prone to having bogus content. + +HTTP server frameworks and their instrumentations have limited knowledge about the HTTP infrastructure and intermediaries that requests go through. In a general case, they can only use HTTP request properties such as request target or headers to populate `server.*` attributes. + +#### Setting `server.address` and `server.port` attributes + +In the context of HTTP server, `server.address` and `server.port` attributes capture the original host name and port. They are intended, whenever possible, to be the same on the client and server sides. + +HTTP server instrumentations SHOULD do the best effort when populating `server.address` and `server.port` attributes and SHOULD determine them by using the first of the following that applies: + +* The original host which may be passed by the reverse proxy in the [`Forwarded#host`][Forwarded#host], [`X-Forwarded-Host`][X-Forwarded-Host], or a similar header. +* The [`:authority`][HTTP/2 authority] pseudo-header in case of HTTP/2 or HTTP/3 +* The [`Host`][Host header] header. + +> **Note**: The `Host` and `:authority` headers contain host and port number of the server. The same applies to the `host` identifier of `Forwarded` header or the `X-Forwarded-Host` header. Instrumentations SHOULD populate both `server.address` and `server.port` attributes by parsing the value of corresponding header. + +Application developers MAY overwrite potentially inaccurate values of `server.*` attributes using a [SpanProcessor][SpanProcessor] and MAY capture private host information using applicable [resource attributes](/docs/resource/README.md). + +#### Simple client/server example + +![simple-http-server.png](simple-http-server.png) + +#### Client/server example with reverse proxy + +![reverse-proxy-http-server.png](reverse-proxy-http-server.png) + +[Host and authority]: https://tools.ietf.org/html/rfc9110#section-7.2 +[Host header]: https://tools.ietf.org/html/rfc7230#section-5.4 +[HTTP/2 authority]: https://tools.ietf.org/html/rfc9113#section-8.3.1 +[Forwarded#host]: https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#host +[X-Forwarded-Host]: https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Host ### HTTP Server semantic conventions @@ -367,62 +338,52 @@ For an HTTP server span, `SpanKind` MUST be `Server`. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`client.address`](../general/attributes.md) | string | Client address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `83.164.160.102` | Recommended | -| [`client.port`](../general/attributes.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. [2] | `65123` | Recommended | -| [`http.route`](../attributes-registry/http.md) | string | The matched route (path template in the format used by the respective server framework). See note below [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| [`network.local.address`](../general/attributes.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.1.2.80`; `/tmp/my.sock` | Opt-In | -| [`network.local.port`](../general/attributes.md) | int | Local socket port. Useful in case of a multi-port host. | `65123` | Opt-In | -| [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`network.peer.port`](../general/attributes.md) | int | Peer port number of the network connection. | `65123` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Recommended: [6] | -| [`url.path`](../url/url.md) | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [7] | `/search` | Required | -| [`url.query`](../url/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [8] | `q=OpenTelemetry` | Conditionally Required: If and only if one was received/sent. | -| [`url.scheme`](../url/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]:** 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. - -**[2]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries (e.g. proxies) if it's available. - -**[3]:** 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](/docs/http/http-spans.md#http-server-definitions) if there is one. - -**[4]:** Determined by using the first of the following that applies - -- The [primary server name](/docs/http/http-spans.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. +| [`client.address`](../attributes-registry/client.md) | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `83.164.160.102` | Recommended | +| [`client.port`](../attributes-registry/client.md) | int | The port of whichever client was captured in `client.address`. [2] | `65123` | Opt-In | +| [`http.request.header.`](../attributes-registry/http.md) | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [3] | `http.request.header.content-type=["application/json"]`; `http.request.header.x-forwarded-for=["1.2.3.4", "1.2.3.5"]` | Opt-In | +| [`http.route`](../attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [4] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | +| [`network.local.address`](../attributes-registry/network.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.1.2.80`; `/tmp/my.sock` | Opt-In | +| [`network.local.port`](../attributes-registry/network.md) | int | Local socket port. Useful in case of a multi-port host. | `65123` | Opt-In | +| [`server.address`](../attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [6] | `80`; `8080`; `443` | Conditionally Required: If `server.address` is set. | +| [`url.path`](../attributes-registry/url.md) | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component | `/search` | Required | +| [`url.query`](../attributes-registry/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [7] | `q=OpenTelemetry` | Conditionally Required: If and only if one was received/sent. | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. [8] | `http`; `https` | Required | +| [`user_agent.original`](../attributes-registry/user-agent.md) | 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`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1` | Recommended | + +**[1]:** The IP address of the original client behind all proxies, if known (e.g. from [Forwarded#for](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#for), [X-Forwarded-For](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-For), or a similar header). Otherwise, the immediate client peer address. + +**[2]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries, for example proxies, if it's available. + +**[3]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request 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. +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. -**[5]:** Determined by using the first of the following that applies +**[4]:** 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](/docs/http/http-spans.md#http-server-definitions) if there is one. -- Port identifier of the [primary server host](/docs/http/http-spans.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]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). -**[6]:** If not default (`80` for `http` scheme, `443` for `https`). +**[6]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). -**[7]:** When missing, the value is assumed to be `/` +**[7]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. -**[8]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. +**[8]:** The scheme of the original client request, if known (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request. -Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: +The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): -* [`server.address`](../general/attributes.md) -* [`server.port`](../general/attributes.md) -* [`url.path`](../url/url.md) -* [`url.query`](../url/url.md) -* [`url.scheme`](../url/url.md) +* [`client.address`](../attributes-registry/client.md) +* [`http.request.header.`](../attributes-registry/http.md) +* [`server.address`](../attributes-registry/server.md) +* [`server.port`](../attributes-registry/server.md) +* [`url.path`](../attributes-registry/url.md) +* [`url.query`](../attributes-registry/url.md) +* [`url.scheme`](../attributes-registry/url.md) +* [`user_agent.original`](../attributes-registry/user-agent.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 @@ -437,8 +398,9 @@ Span name: `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"` | +| `server.port` | `8080` | +| `network.peer.address` | `"192.0.2.5"` | +| `network.peer.port` | `8080` | | `http.response.status_code` | `200` | The corresponding server Span may look like this: @@ -593,3 +555,4 @@ Span name: `POST /uploads/:document_id`. | `error.type` | `WebSocketDisconnect` | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md +[SpanProcessor]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/trace/sdk.md#span-processor diff --git a/docs/http/reverse-proxy-http-server.png b/docs/http/reverse-proxy-http-server.png new file mode 100644 index 0000000000..1649e41255 Binary files /dev/null and b/docs/http/reverse-proxy-http-server.png differ diff --git a/docs/http/simple-http-server.png b/docs/http/simple-http-server.png new file mode 100644 index 0000000000..41d4a2574c Binary files /dev/null and b/docs/http/simple-http-server.png differ diff --git a/docs/messaging/README.md b/docs/messaging/README.md index 3d0a28ea6e..5308786270 100644 --- a/docs/messaging/README.md +++ b/docs/messaging/README.md @@ -14,11 +14,13 @@ This document defines semantic conventions for messaging systems spans, metrics Semantic conventions for messaging systems are defined for the following signals: * [Messaging Spans](messaging-spans.md): Semantic Conventions for messaging *spans*. +* [Messaging Metrics](messaging-metrics.md): Semantic Conventions for messaging *metrics*. Technology specific semantic conventions are defined for the following messaging systems: * [Kafka](kafka.md): Semantic Conventions for *Apache Kafka*. * [RabbitMQ](rabbitmq.md): Semantic Conventions for *RabbitMQ*. * [RocketMQ](rocketmq.md): Semantic Conventions for *Apache RocketMQ*. +* [Google Cloud Pub/Sub](gcp-pubsub.md): Semantic Conventions for *Google Cloud Pub/Sub*. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/messaging/gcp-pubsub.md b/docs/messaging/gcp-pubsub.md new file mode 100644 index 0000000000..08027ce032 --- /dev/null +++ b/docs/messaging/gcp-pubsub.md @@ -0,0 +1,22 @@ + + +# Semantic Conventions for Google Cloud Pub/Sub + +**Status**: [Experimental][DocumentStatus] + +The Semantic Conventions for [Google Cloud Pub/Sub](https://cloud.google.com/pubsub) extend and override the [Messaging Semantic Conventions](README.md) that describe common messaging operations attributes in addition to the Semantic Conventions described on this page. + +`messaging.system` MUST be set to `"gcp_pubsub"`. + +## Span attributes + +For Google Cloud Pub/Sub, the following additional attributes are defined: + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`messaging.gcp_pubsub.message.ordering_key`](../attributes-registry/messaging.md) | string | The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. | `ordering_key` | Conditionally Required: If the message type has an ordering key set. | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index 9bfb1c2332..ffb30d89c2 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -24,14 +24,14 @@ described on this page. For Apache Kafka, the following additional attributes are defined: - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `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.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.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] | +| [`messaging.kafka.consumer.group`](../attributes-registry/messaging.md) | 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`](../attributes-registry/messaging.md) | int | Partition the message is sent to. | `2` | Recommended | +| [`messaging.kafka.message.key`](../attributes-registry/messaging.md) | 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.message.offset`](../attributes-registry/messaging.md) | int | The offset of a record in the corresponding Kafka partition. | `42` | Recommended | +| [`messaging.kafka.message.tombstone`](../attributes-registry/messaging.md) | 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. @@ -81,7 +81,7 @@ Process CB: | Span Rcv2 | | `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.destination.partition` | `"1"` | `"1"` | `"1"` | `"3"` | `"3"` | | `messaging.kafka.message.offset` | `"12"` | `"12"` | `"12"` | `"32"` | `"32"` | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md new file mode 100644 index 0000000000..b2f7046bdd --- /dev/null +++ b/docs/messaging/messaging-metrics.md @@ -0,0 +1,182 @@ +# Semantic Conventions for Messaging Metrics + +**Status**: [Experimental][DocumentStatus] + + + + + +- [Common attributes](#common-attributes) +- [Producer metrics](#producer-metrics) + * [Metric: `messaging.publish.duration`](#metric-messagingpublishduration) + * [Metric: `messaging.publish.messages`](#metric-messagingpublishmessages) +- [Consumer metrics](#consumer-metrics) + * [Metric: `messaging.receive.duration`](#metric-messagingreceiveduration) + * [Metric: `messaging.receive.messages`](#metric-messagingreceivemessages) + * [Metric: `messaging.deliver.duration`](#metric-messagingdeliverduration) + * [Metric: `messaging.deliver.messages`](#metric-messagingdelivermessages) + + + +## Common attributes + +All messaging metrics share the same set of attributes: + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`error.type`](../attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | Conditionally Required: [2] | +| [`messaging.destination.name`](../attributes-registry/messaging.md) | string | The message destination name [3] | `MyQueue`; `MyTopic` | Conditionally Required: [4] | +| [`messaging.destination.template`](../attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [5] | `/customers/{customerId}` | Conditionally Required: if available. | +| [`messaging.system`](../attributes-registry/messaging.md) | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `activemq` | Required | +| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [6] | `amqp`; `mqtt` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [7] | `3.1.1` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [9] | `80`; `8080`; `443` | Recommended | + +**[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low. +Telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time when no +additional filters are applied. + +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + +If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), +it's RECOMMENDED to: + +* Use a domain-specific attribute +* Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. + +**[2]:** If and only if the messaging operation has failed. + +**[3]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If +the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker. + +**[4]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. + +**[5]:** 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. + +**[6]:** The value SHOULD be normalized to lowercase. + +**[7]:** `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 has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[8]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. + +**[9]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | + +`messaging.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 | +|---|---| +| `activemq` | Apache ActiveMQ | +| `aws_sqs` | Amazon Simple Queue Service (SQS) | +| `azure_eventgrid` | Azure Event Grid | +| `azure_eventhubs` | Azure Event Hubs | +| `azure_servicebus` | Azure Service Bus | +| `gcp_pubsub` | Google Cloud Pub/Sub | +| `jms` | Java Message Service | +| `kafka` | Apache Kafka | +| `rabbitmq` | RabbitMQ | +| `rocketmq` | Apache RocketMQ | + + +## Producer metrics + +### Metric: `messaging.publish.duration` + +This metric is [required][MetricRequired]. + +When this metric is reported alongside a messaging publish span, the metric value SHOULD be the same as the corresponding span duration. + +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advice) +of `[ 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 | +| -------- | --------------- | ----------- | -------------- | +| `messaging.publish.duration` | Histogram | `s` | Measures the duration of publish operation. | + + +### Metric: `messaging.publish.messages` + +This metric is [required][MetricRequired] when the messaging system supports batch publishing. It's [opt-in][MetricOptIn] when the messaging system does not support batch publishing, since the message count can be derived from the `messaging.publish.duration` histogram. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `messaging.publish.messages` | Counter | `{message}` | Measures the number of published messages. | + + +> The need to report `messaging.publish.messages` depends on the messaging system capabilities and not application scenarios or client library limitations. For example, RabbitMQ does not support batch publishing and corresponding instrumentations don't need to report `messaging.publish.messages`. Kafka supports both, single and batch publishing, and instrumentations MUST report `messaging.publish.messages` counter regardless of application scenarios or APIs available in the client library. + +## Consumer metrics + +### Metric: `messaging.receive.duration` + +This metric is [required][MetricRequired] for operations that are initiated by the application code (pull-based). + +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advice) +of `[ 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 ]`. + +When this metric is reported alongside a messaging receive span, the metric value SHOULD be the same as the corresponding span duration. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `messaging.receive.duration` | Histogram | `s` | Measures the duration of receive operation. | + + +### Metric: `messaging.receive.messages` + +This metric is [required][MetricRequired] for batch receive operations. It's [opt-in][MetricOptIn] when the messaging system does not support batch receive since the message count can be derived from the `messaging.receive.duration` histogram. + +_Note: The need to report `messaging.receive.messages` depends on the messaging system capabilities and not application scenarios or client library limitations._ + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `messaging.receive.messages` | Counter | `{message}` | Measures the number of received messages. | + + +### Metric: `messaging.deliver.duration` + +This metric is [required][MetricRequired] for operations are not initiated by the application code (push-based deliver). + +When this metric is reported alongside a messaging deliver span, the metric value SHOULD be the same as the corresponding span duration. + +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advice) +of `[ 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 | +| -------- | --------------- | ----------- | -------------- | +| `messaging.deliver.duration` | Histogram | `s` | Measures the duration of deliver operation. | + + +### Metric: `messaging.deliver.messages` + +This metric is [required][MetricRequired] for batch delivery operations. It's [opt-in][MetricOptIn] when the messaging system does not support batch delivery since the message count can be derived from the `messaging.deliver.duration` histogram. + +_Note: The need to report `messaging.deliver.messages` depends on the messaging system capabilities and not application scenarios or client library limitations._ + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `messaging.deliver.messages` | Counter | `{message}` | Measures the number of delivered messages. | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md +[MetricRequired]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/metrics/metric-requirement-level.md#required +[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/metrics/metric-requirement-level.md#opt-in diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 388ec90b03..7562e2972b 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -1,4 +1,4 @@ -# Messaging Systems +# Semantic Conventions for Messaging Spans **Status**: [Experimental][DocumentStatus] @@ -18,8 +18,11 @@ - [Conventions](#conventions) * [Context propagation](#context-propagation) * [Span name](#span-name) - * [Span kind](#span-kind) * [Operation names](#operation-names) + * [Span kind](#span-kind) + * [Trace structure](#trace-structure) + + [Producer spans](#producer-spans) + + [Consumer spans](#consumer-spans) - [Messaging attributes](#messaging-attributes) * [Attribute namespaces](#attribute-namespaces) * [Consumer attributes](#consumer-attributes) @@ -28,7 +31,6 @@ - [Examples](#examples) * [Topic with multiple consumers](#topic-with-multiple-consumers) * [Batch receiving](#batch-receiving) - * [Batch processing](#batch-processing) - [Semantic Conventions for specific messaging technologies](#semantic-conventions-for-specific-messaging-technologies) @@ -57,8 +59,7 @@ > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version > for at least six months after it starts emitting both sets of conventions. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). +> * SHOULD drop the environment variable in the next major version. ## Definitions @@ -196,101 +197,218 @@ Examples: * `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. | +| `publish` | One or more messages are provided for publishing to an intermediary. If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. | +| `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. | +| `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | +| `deliver` | One or more messages are passed to a consumer. This operation refers to push-based scenarios, where consumer register callbacks which get called by messaging SDKs. | + +### Span kind + +[Span kinds](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/trace/api.md#spankind) +SHOULD be set according to the following table, based on the operation a span describes. + +| Operation name | Span kind| +|----------------|-------------| +| `publish` | `PRODUCER` if the context of the "Publish" span is used as creation context. | +| `create` | `PRODUCER` | +| `receive` | `CONSUMER` | +| `deliver` | `CONSUMER` | + +For cases not covered by the table above, the span kind should be set according +to the [generic specification about span kinds](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/trace/api.md#spankind), +e. g. it should be set to CLIENT for the "Publish" span if its context is not +used as creation context and if the "Publish" span models a synchronous call to +the intermediary. + +Setting span kinds according to this table ensures that span links between +consumers and producers always exist between a PRODUCER span on the producer +side and a CONSUMER span on the consumer side. This allows analysis tools to +interpret linked traces without the need for additional semantic hints. + +### Trace structure + +#### Producer spans + +"Publish" spans SHOULD be created for operations of providing messages for +sending or publishing to an intermediary. A single "Publish" span can account +for a single message, or for multiple messages (in the case of providing +messages in batches). "Create" spans MAY be created. A single "Create" span +SHOULD account only for a single message. "Create" spans SHOULD either be +children or links of the related "Publish" span. + +If a user provides a custom creation context in a message, this context SHOULD +NOT be modified, a "Create" span SHOULD NOT be created, and the "Publish" span +SHOULD link to the custom creation context. Otherwise, if a "Create" span +exists for a message, its context SHOULD be injected into the message. If no +"Create" span exists and no custom creation context is injected into the +message, the context of the related "Publish" span SHOULD be injected into the +message. + +#### Consumer spans + +"Deliver" spans SHOULD be created for operations of passing messages to the +application when those operations are not initiated by the application code +(push-based scenarios). A "Deliver" span covers the duration of such an +operation, which is usually a callback or handler. + +"Receive" spans SHOULD be created for operations of passing messages to the +application when those operations are initiated by the application code +(pull-based scenarios). + +"Deliver" or "Receive" spans MUST NOT be created for messages that are +pre-fetched or cached by messaging libraries or SDKs until they are forwarded +to the caller. + +A single "Deliver" or "Receive" span can account for a single message, for a +batch of messages, or for no message at all (if it is signalled that no +messages were received). For each message it accounts for, the "Deliver" or +"Receive" span SHOULD link to the message's creation context. ## Messaging attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `messaging.batch.message_count` | int | The number of messages sent, received, or processed in the scope of the batching operation. [1] | `0`; `1`; `2` | Conditionally Required: [2] | -| `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.destination.anonymous` | boolean | A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name). | | Conditionally Required: [3] | -| `messaging.destination.name` | string | The message destination name [4] | `MyQueue`; `MyTopic` | Conditionally Required: [5] | -| `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [6] | `/customers/{customerId}` | Conditionally Required: [7] | -| `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: [8] | -| `messaging.message.body.size` | int | The size of the message body in bytes. [9] | `1439` | Recommended: [10] | -| `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: [11] | -| `messaging.message.envelope.size` | int | The size of the message body and metadata in bytes. [12] | `2738` | Recommended: [13] | -| `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [14] | -| `messaging.operation` | string | A string identifying the kind of messaging operation as defined in the [Operation names](#operation-names) section above. [15] | `publish` | Required | -| `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required | -| [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended: If different than `server.address`. | -| [`network.peer.port`](../general/attributes.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [16] | `amqp`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [17] | `3.1.1` | Recommended | -| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [18] | `tcp`; `udp` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [19] | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [20] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. | +| [`error.type`](../attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | Conditionally Required: [2] | +| [`messaging.batch.message_count`](../attributes-registry/messaging.md) | int | The number of messages sent, received, or processed in the scope of the batching operation. [3] | `0`; `1`; `2` | Conditionally Required: [4] | +| [`messaging.client_id`](../attributes-registry/messaging.md) | 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.destination.anonymous`](../attributes-registry/messaging.md) | boolean | A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name). | | Conditionally Required: [5] | +| [`messaging.destination.name`](../attributes-registry/messaging.md) | string | The message destination name [6] | `MyQueue`; `MyTopic` | Conditionally Required: [7] | +| [`messaging.destination.template`](../attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [8] | `/customers/{customerId}` | Conditionally Required: [9] | +| [`messaging.destination.temporary`](../attributes-registry/messaging.md) | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | Conditionally Required: [10] | +| [`messaging.message.body.size`](../attributes-registry/messaging.md) | int | The size of the message body in bytes. [11] | `1439` | Recommended: [12] | +| [`messaging.message.conversation_id`](../attributes-registry/messaging.md) | string | The conversation ID identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended: [13] | +| [`messaging.message.envelope.size`](../attributes-registry/messaging.md) | int | The size of the message body and metadata in bytes. [14] | `2738` | Recommended: [15] | +| [`messaging.message.id`](../attributes-registry/messaging.md) | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [16] | +| [`messaging.operation`](../attributes-registry/messaging.md) | string | A string identifying the kind of messaging operation. [17] | `publish` | Required | +| [`messaging.system`](../attributes-registry/messaging.md) | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `activemq` | Required | +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | +| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [18] | `amqp`; `mqtt` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [19] | `3.1.1` | Recommended | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [20] | `tcp`; `udp` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [21] | `ipv4`; `ipv6` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [22] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [23] | `80`; `8080`; `443` | Recommended | -**[1]:** 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. +**[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. -**[2]:** If the span describes an operation on a batch of messages. +The cardinality of `error.type` within one instrumentation library SHOULD be low. +Telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time when no +additional filters are applied. -**[3]:** If value is `true`. When missing, the value is assumed to be `false`. +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[4]:** 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. +If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), +it's RECOMMENDED to: -**[5]:** If span describes operation on a single message or if the value applies to all messages in the batch. +* Use a domain-specific attribute +* Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. -**[6]:** 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. +**[2]:** If and only if the messaging operation has failed. -**[7]:** If available. Instrumentations MUST NOT use `messaging.destination.name` as template unless low-cardinality of destination name is guaranteed. +**[3]:** 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. -**[8]:** If value is `true`. When missing, the value is assumed to be `false`. +**[4]:** If the span describes an operation on a batch of messages. -**[9]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed -body size should be used. +**[5]:** If value is `true`. When missing, the value is assumed to be `false`. -**[10]:** Only if span represents operation on a single message. +**[6]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If +the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker. -**[11]:** Only if span represents operation on a single message. +**[7]:** If span describes operation on a single message or if the value applies to all messages in the batch. -**[12]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed -size should be used. +**[8]:** 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. + +**[9]:** If available. Instrumentations MUST NOT use `messaging.destination.name` as template unless low-cardinality of destination name is guaranteed. + +**[10]:** If value is `true`. When missing, the value is assumed to be `false`. + +**[11]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed +body size should be used. + +**[12]:** Only if span represents operation on a single message. **[13]:** Only if span represents operation on a single message. -**[14]:** Only for spans that represent an operation on a single message. +**[14]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed +size should be used. -**[15]:** If a custom value is used, it MUST be of low cardinality. +**[15]:** Only if span represents operation on a single message. -**[16]:** The value SHOULD be normalized to lowercase. +**[16]:** Only for spans that represent an operation on a single message. -**[17]:** `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`. +**[17]:** If a custom value is used, it MUST be of low cardinality. **[18]:** The value SHOULD be normalized to lowercase. +**[19]:** `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 has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[20]:** The value SHOULD be normalized to lowercase. + Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport, for example +a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. -**[19]:** The value SHOULD be normalized to lowercase. +**[21]:** The value SHOULD be normalized to lowercase. + +**[22]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. + +**[23]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[20]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. +`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | `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 | +| `publish` | One or more messages are provided for publishing to an intermediary. If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. | +| `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. | +| `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | +| `deliver` | One or more messages are passed to a consumer. This operation refers to push-based scenarios, where consumer register callbacks which get called by messaging SDKs. | + +`messaging.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 | +|---|---| +| `activemq` | Apache ActiveMQ | +| `aws_sqs` | Amazon Simple Queue Service (SQS) | +| `azure_eventgrid` | Azure Event Grid | +| `azure_eventhubs` | Azure Event Hubs | +| `azure_servicebus` | Azure Service Bus | +| `gcp_pubsub` | Google Cloud Pub/Sub | +| `jms` | Java Message Service | +| `kafka` | Apache Kafka | +| `rabbitmq` | RabbitMQ | +| `rocketmq` | Apache RocketMQ | + +`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. | +| `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 | Additionally `server.port` from the [network attributes][] is recommended. @@ -328,26 +446,19 @@ under the namespace `messaging.destination_publish.*` | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `messaging.destination_publish.anonymous` | boolean | A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name). | | Recommended | -| `messaging.destination_publish.name` | string | The name of the original destination the message was published to [1] | `MyQueue`; `MyTopic` | Recommended | +| [`messaging.destination_publish.anonymous`](../attributes-registry/messaging.md) | boolean | A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name). | | Recommended | +| [`messaging.destination_publish.name`](../attributes-registry/messaging.md) | string | The name of the original destination the message was published to [1] | `MyQueue`; `MyTopic` | Recommended | **[1]:** The name SHOULD uniquely identify a specific queue, topic, or other entity within the broker. If -the broker does not have such notion, the original destination name SHOULD uniquely identify the broker. +the broker doesn't have such notion, the original destination name SHOULD uniquely identify the broker. -The *receive* span is 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. +For batch operations, per-message attributes are usually different and cannot be set on the corresponding span. In such cases the attributes SHOULD be set on links. See [Batch receiving](#batch-receiving) 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` MAY be set on links. Instrumentations MAY set destination attributes on the span if all messages in the batch share the same destination. @@ -365,92 +476,83 @@ All attributes that are specific for a messaging system SHOULD be populated in ` ### 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 | +Given is a publisher that publishes a message to a topic exchange "T" on RabbitMQ, and two consumers which both get the message delivered. + +```mermaid +flowchart LR; + subgraph PRODUCER + direction TB + P[Span Publish A] + end + subgraph CONSUMER1 + direction TB + R1[Span Deliver A 1] + end + subgraph CONSUMER2 + direction TB + R2[Span Deliver A 2] + end + P-. link .-R1; + P-. link .-R2; + + classDef normal fill:green + class P,R1,R2 normal + linkStyle 0,1 color:green,stroke:green ``` -| Field or Attribute | Span Prod1 | Span CA1 | Span CB1 | +| Field or Attribute | Span Publish A | Span Deliver A 1| Span Deliver A 2 | |-|-|-|-| -| Span name | `"T publish"` | `"T process"` | `"T process"` | -| Parent | | Span Prod1 | Span Prod1 | -| Links | | | | +| Span name | `T publish` | `T deliver` | `T deliver` | +| Parent | | | | +| Links | | `T publish` | `T publish` | | 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"` | `"T"` | `"T"` | -| `messaging.operation` | | `"process"` | `"process"` | -| `messaging.message.id` | `"a1"` | `"a1"`| `"a1"` | +| `messaging.operation` | `"publish"` | `"deliver"` | `"deliver"` | +| `messaging.message.id` | `"a"` | `"a"`| `"a"` | ### 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. - +Given is a publisher that publishes two messages to a topic "Q" on Kafka, and a consumer which receives both messages in one batch. + +```mermaid +flowchart LR; + subgraph PRODUCER + direction TB + PA[Span Publish A] + PB[Span Publish B] + end + subgraph CONSUMER1 + direction TB + D1[Span Receive A B] + end + PA-. link .-D1; + PB-. link .-D1; + + classDef normal fill:green + class PA,PB,D1 normal + linkStyle 0,1 color:green,stroke:green ``` -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"` | `"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](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/trace/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"` | `"Q"` | `"Q"` | `"Q"` | -| `messaging.operation` | | | `"receive"` | `"receive"` | `"process"` | -| `messaging.message.id` | `"a1"` | `"a2"` | `"a1"` | `"a2"` | | -| `messaging.batch.message_count` | | | 1 | 1 | 2 | +| Field or Attribute | Span Publish A | Span Publish B | Span Receive A B | +|-|-|-|-| +| Span name | `Q publish` | `Q publish` | `Q receive` | +| Parent | | | | +| Links | | | Span Publish A, Span Publish B | +| Link attributes | | | Span Publish A: `messaging.message.id`: `"a1"` | +| | | | Span Publish B: `messaging.message.id`: `"a2"` | +| SpanKind | `PRODUCER` | `PRODUCER` | `CONSUMER` | +| Status | `Ok` | `Ok` | `Ok` | +| `server.address` | `"ms"` | `"ms"` | `"ms"` | +| `server.port` | `1234` | `1234` | `1234` | +| `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | +| `messaging.destination.name` | `"Q"` | `"Q"` | `"Q"` | +| `messaging.operation` | `"publish"` | `"publish"` | `"receive"` | +| `messaging.message.id` | `"a1"` | `"a2"` | | +| `messaging.batch.message_count` | | | 2 | ## Semantic Conventions for specific messaging technologies diff --git a/docs/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md index fcc120f338..1c762c4386 100644 --- a/docs/messaging/rabbitmq.md +++ b/docs/messaging/rabbitmq.md @@ -6,7 +6,7 @@ linkTitle: RabbitMQ **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for [RibbitMQ](https://www.rabbitmq.com/) extend and override the [Messaging Semantic Conventions](README.md) +The Semantic Conventions for [RabbitMQ](https://www.rabbitmq.com/) extend and override the [Messaging Semantic Conventions](README.md) that describe common messaging operations attributes in addition to the Semantic Conventions described on this page. @@ -17,10 +17,10 @@ described on this page. 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. | +| [`messaging.rabbitmq.destination.routing_key`](../attributes-registry/messaging.md) | string | RabbitMQ message routing key. | `myKey` | Conditionally Required: If not empty. | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/messaging/rocketmq.md b/docs/messaging/rocketmq.md index fe6a7d3401..8f4bbca5fb 100644 --- a/docs/messaging/rocketmq.md +++ b/docs/messaging/rocketmq.md @@ -16,18 +16,18 @@ described on this page. Specific attributes for Apache RocketMQ are defined below. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `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.consumption_model` | string | Model of message consumption. This only applies to consumer spans. | `clustering` | Recommended | -| `messaging.rocketmq.message.delay_time_level` | int | The delay time level for delay message, which determines the message delay time. | `3` | Conditionally Required: [1] | -| `messaging.rocketmq.message.delivery_timestamp` | int | The timestamp in milliseconds that the delay message is expected to be delivered to consumer. | `1665987217045` | 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.keys` | string[] | Key(s) of message, another way to mark message besides message id. | `[keyA, keyB]` | Recommended | -| `messaging.rocketmq.message.tag` | string | The secondary classifier of message besides topic. | `tagA` | Recommended | -| `messaging.rocketmq.message.type` | string | Type of message. | `normal` | Recommended | -| `messaging.rocketmq.namespace` | string | Namespace of RocketMQ resources, resources in different namespaces are individual. | `myNamespace` | Required | +| [`messaging.rocketmq.client_group`](../attributes-registry/messaging.md) | 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.consumption_model`](../attributes-registry/messaging.md) | string | Model of message consumption. This only applies to consumer spans. | `clustering` | Recommended | +| [`messaging.rocketmq.message.delay_time_level`](../attributes-registry/messaging.md) | int | The delay time level for delay message, which determines the message delay time. | `3` | Conditionally Required: [1] | +| [`messaging.rocketmq.message.delivery_timestamp`](../attributes-registry/messaging.md) | int | The timestamp in milliseconds that the delay message is expected to be delivered to consumer. | `1665987217045` | Conditionally Required: [2] | +| [`messaging.rocketmq.message.group`](../attributes-registry/messaging.md) | 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.keys`](../attributes-registry/messaging.md) | string[] | Key(s) of message, another way to mark message besides message id. | `[keyA, keyB]` | Recommended | +| [`messaging.rocketmq.message.tag`](../attributes-registry/messaging.md) | string | The secondary classifier of message besides topic. | `tagA` | Recommended | +| [`messaging.rocketmq.message.type`](../attributes-registry/messaging.md) | string | Type of message. | `normal` | Recommended | +| [`messaging.rocketmq.namespace`](../attributes-registry/messaging.md) | string | Namespace of RocketMQ resources, resources in different namespaces are individual. | `myNamespace` | Required | **[1]:** If the message type is delay and delivery timestamp is not specified. diff --git a/docs/mobile/README.md b/docs/mobile/README.md new file mode 100644 index 0000000000..bcf994e485 --- /dev/null +++ b/docs/mobile/README.md @@ -0,0 +1,18 @@ + + +# Semantic Convention for Mobile Platform + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions for mobile platform spans, metrics and logs. + +Semantic conventions for the mobile platform are defined for the following signals: + +* [Mobile Events](events.md) : Semantic Conventions for mobile events in *logs*. + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/mobile/events.md b/docs/mobile/events.md new file mode 100644 index 0000000000..70a5d6fdc3 --- /dev/null +++ b/docs/mobile/events.md @@ -0,0 +1,66 @@ +# Semantic Conventions for mobile events + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions for instrumentations that emit +events on mobile platforms. All mobile events MUST use a namespace of +`device` in the `event.name` property. + + + +- [Lifecycle instrumentation](#lifecycle-instrumentation) + * [iOS](#ios) + * [Android](#android) + + + +## Lifecycle instrumentation + +This section defines how to apply semantic conventions when instrumenting +application lifecycle. This event is meant to be used in conjunction with +`os.name` [resource semantic convention](/docs/resource/os.md) to identify the +mobile operating system (e.g. Android, iOS). + +### iOS + + +The event name MUST be `device.app.lifecycle`. + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `ios.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [1] | `active` | Required | + +**[1]:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), and from which the `OS terminology` column values are derived. + +`ios.state` MUST be one of the following: + +| Value | Description | +|---|---| +| `active` | The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`. | +| `inactive` | The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. | +| `background` | The app is now in the background. This value is associated with UIKit notification `applicationDidEnterBackground`. | +| `foreground` | The app is now in the foreground. This value is associated with UIKit notification `applicationWillEnterForeground`. | +| `terminate` | The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. | + + +### Android + + +The event name MUST be `device.app.lifecycle`. + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `android.state` | string | This attribute represents the state the application has transitioned into at the occurrence of the event. [1] | `created` | Required | + +**[1]:** The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), and from which the `OS identifiers` are derived. + +`android.state` MUST be one of the following: + +| Value | Description | +|---|---| +| `created` | Any time before Activity.onResume() or, if the app has no Activity, Context.startService() has been called in the app for the first time. | +| `background` | Any time after Activity.onPause() or, if the app has no Activity, Context.stopService() has been called when the app was in the foreground state. | +| `foreground` | Any time after Activity.onResume() or, if the app has no Activity, Context.startService() has been called when the app was in either the created or background states. | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/README.md b/docs/resource/README.md index 4d3e747dd6..5a12b18593 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -47,7 +47,7 @@ This document defines standard attributes for resources. These attributes are ty 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](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/common/attribute-requirement-level.md) for details on when attributes +See [Attribute Requirement Levels](../general/attribute-requirement-level.md) for details on when attributes should be included. ## Attributes with Special Handling diff --git a/docs/resource/browser.md b/docs/resource/browser.md index c352b70c70..cec3fe9494 100644 --- a/docs/resource/browser.md +++ b/docs/resource/browser.md @@ -15,7 +15,7 @@ All of these attributes can be provided by the user agent itself in the form of | `browser.language` | string | Preferred language of the user using the browser [2] | `en`; `en-US`; `fr`; `fr-FR` | Recommended | | `browser.mobile` | boolean | A boolean that is true if the browser is running on a mobile device [3] | | Recommended | | `browser.platform` | string | The platform on which the browser is running [4] | `Windows`; `macOS`; `Android` | 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 | +| [`user_agent.original`](../attributes-registry/user-agent.md) | 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`). diff --git a/docs/resource/cloud.md b/docs/resource/cloud.md index 6644e63325..c8ced8c2c3 100644 --- a/docs/resource/cloud.md +++ b/docs/resource/cloud.md @@ -6,21 +6,21 @@ **Description:** A cloud infrastructure (e.g. GCP, Azure, AWS). - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `cloud.account.id` | string | The cloud account ID the resource is assigned to. | `111111111111`; `opentelemetry` | 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. [1] | `us-east-1c` | Recommended | -| `cloud.platform` | string | The cloud platform in use. [2] | `alibaba_cloud_ecs` | Recommended | -| `cloud.provider` | string | Name of the cloud provider. | `alibaba_cloud` | Recommended | -| `cloud.region` | string | The geographical region the resource is running. [3] | `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) [4] | `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.account.id`](../attributes-registry/cloud.md) | string | The cloud account ID the resource is assigned to. | `111111111111`; `opentelemetry` | Recommended | +| [`cloud.availability_zone`](../attributes-registry/cloud.md) | string | Cloud regions often have multiple, isolated locations known as zones to increase availability. Availability zone represents the zone where the resource is running. [1] | `us-east-1c` | Recommended | +| [`cloud.platform`](../attributes-registry/cloud.md) | string | The cloud platform in use. [2] | `alibaba_cloud_ecs` | Recommended | +| [`cloud.provider`](../attributes-registry/cloud.md) | string | Name of the cloud provider. | `alibaba_cloud` | Recommended | +| [`cloud.region`](../attributes-registry/cloud.md) | string | The geographical region the resource is running. [3] | `us-central1`; `us-east-1` | Recommended | +| [`cloud.resource_id`](../attributes-registry/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/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) [4] | `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]:** Availability zones are called "zones" on Alibaba Cloud and Google Cloud. **[2]:** The prefix of the service SHOULD match the one specified in `cloud.provider`. -**[3]:** 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). +**[3]:** 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/global-infrastructure/geographies/), [Google Cloud regions](https://cloud.google.com/about/locations), or [Tencent Cloud regions](https://www.tencentcloud.com/document/product/213/6091). **[4]:** 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. @@ -34,7 +34,7 @@ The following well-known definitions MUST be used if you set this attribute and 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, +* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/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 diff --git a/docs/resource/container.md b/docs/resource/container.md index 827e20b779..1abdd5c277 100644 --- a/docs/resource/container.md +++ b/docs/resource/container.md @@ -9,17 +9,18 @@ | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `container.command` | string | The command used to run the container (i.e. the command name). [1] | `otelcontribcol` | Opt-In | -| `container.command_args` | string[] | All the command arguments (including the command/executable itself) run by the container. [2] | `[otelcontribcol, --config, config.yaml]` | Opt-In | -| `container.command_line` | string | The full command run by the container as a single string representing the full command. [2] | `otelcontribcol --config config.yaml` | Opt-In | -| `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.image.id` | string | Runtime specific image identifier. Usually a hash algorithm followed by a UUID. [2] | `sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f` | Recommended | -| `container.image.name` | string | Name of the image the container was built on. | `gcr.io/opentelemetry/operator` | Recommended | -| `container.image.repo_digests` | string[] | Repo digests of the container image as provided by the container runtime. [3] | `[example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb, internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578]` | Recommended | -| `container.image.tags` | string[] | Container image tags. An example can be found in [Docker Image Inspect](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect). Should be only the `` section of the full name for example from `registry.example.com/my-org/my-image:`. | `[v1.27.1, 3.5.7-0]` | Recommended | -| `container.labels.` | string | Container labels, `` being the label name, the value being the label value. | `container.labels.app=nginx` | Recommended | -| `container.name` | string | Container name used by container runtime. | `opentelemetry-autoconf` | Recommended | -| `container.runtime` | string | The container runtime managing this container. | `docker`; `containerd`; `rkt` | Recommended | +| [`container.command`](../attributes-registry/container.md) | string | The command used to run the container (i.e. the command name). [1] | `otelcontribcol` | Opt-In | +| [`container.command_args`](../attributes-registry/container.md) | string[] | All the command arguments (including the command/executable itself) run by the container. [2] | `[otelcontribcol, --config, config.yaml]` | Opt-In | +| [`container.command_line`](../attributes-registry/container.md) | string | The full command run by the container as a single string representing the full command. [2] | `otelcontribcol --config config.yaml` | Opt-In | +| [`container.id`](../attributes-registry/container.md) | 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.image.id`](../attributes-registry/container.md) | string | Runtime specific image identifier. Usually a hash algorithm followed by a UUID. [2] | `sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f` | Recommended | +| [`container.image.name`](../attributes-registry/container.md) | string | Name of the image the container was built on. | `gcr.io/opentelemetry/operator` | Recommended | +| [`container.image.repo_digests`](../attributes-registry/container.md) | string[] | Repo digests of the container image as provided by the container runtime. [3] | `[example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb, internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578]` | Recommended | +| [`container.image.tags`](../attributes-registry/container.md) | string[] | Container image tags. An example can be found in [Docker Image Inspect](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect). Should be only the `` section of the full name for example from `registry.example.com/my-org/my-image:`. | `[v1.27.1, 3.5.7-0]` | Recommended | +| [`container.labels.`](../attributes-registry/container.md) | string | Container labels, `` being the label name, the value being the label value. | `container.labels.app=nginx` | Recommended | +| [`container.name`](../attributes-registry/container.md) | string | Container name used by container runtime. | `opentelemetry-autoconf` | Recommended | +| [`container.runtime`](../attributes-registry/container.md) | string | The container runtime managing this container. | `docker`; `containerd`; `rkt` | Recommended | +| [`oci.manifest.digest`](../attributes-registry/oci.md) | string | The digest of the OCI image manifest. For container images specifically is the digest by which the container image is known. [4] | `sha256:e4ca62c0d62f3e886e684806dfe9d4e0cda60d54986898173c1083856cfda0f4` | Recommended | **[1]:** If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage. @@ -28,29 +29,8 @@ K8s defines a link to the container registry repository with digest `"imageID": The ID is assinged by the container runtime and can vary in different environments. Consider using `oci.manifest.digest` if it is important to identify the same image in different environments/runtimes. **[3]:** [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field. - - -## Open Container Initiative (OCI) - -The [Open Container Initiative](https://opencontainers.org/) defines open industry standards around container formats and runtimes. - -### OCI Image Manifest - -This section refers to the [specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md) -that defines an OCI Image manifest. - -**Status**: [Experimental][DocumentStatus] - -**type:** `oci` - -**Description:** Attributes of an OCI image manifest. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `oci.manifest.digest` | string | The digest of the OCI image manifest. For container images specifically is the digest by which the container image is known. [1] | `sha256:e4ca62c0d62f3e886e684806dfe9d4e0cda60d54986898173c1083856cfda0f4` | Recommended | -**[1]:** Follows [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md), and specifically the [Digest property](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests). +**[4]:** Follows [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/main/manifest.md), and specifically the [Digest property](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests). An example can be found in [Example Image Manifest](https://docs.docker.com/registry/spec/manifest-v2-2/#example-image-manifest). diff --git a/docs/resource/deployment-environment.md b/docs/resource/deployment-environment.md index 9766919543..faba4a47d9 100644 --- a/docs/resource/deployment-environment.md +++ b/docs/resource/deployment-environment.md @@ -9,7 +9,15 @@ | 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 | +| `deployment.environment` | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). [1] | `staging`; `production` | Recommended | + +**[1]:** `deployment.environment` does not affect the uniqueness constraints defined through +the `service.namespace`, `service.name` and `service.instance.id` resource attributes. +This implies that resources carrying the following attribute combinations MUST be +considered to be identifying the same service: + +* `service.name=frontend`, `deployment.environment=production` +* `service.name=frontend`, `deployment.environment=staging`. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/resource/device.md b/docs/resource/device.md index cfbaf9d82d..57bd6dea97 100644 --- a/docs/resource/device.md +++ b/docs/resource/device.md @@ -9,18 +9,18 @@ | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `device.id` | string | A unique identifier representing the device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | Recommended | -| `device.manufacturer` | string | The name of the device manufacturer [2] | `Apple`; `Samsung` | Recommended | -| `device.model.identifier` | string | The model identifier for the device [3] | `iPhone3,4`; `SM-G920F` | Recommended | -| `device.model.name` | string | The marketing name for the device model [4] | `iPhone 6s Plus`; `Samsung Galaxy S6` | Recommended | +| [`device.id`](../attributes-registry/device.md) | string | A unique identifier representing the device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | Recommended | +| [`device.manufacturer`](../attributes-registry/device.md) | string | The name of the device manufacturer [2] | `Apple`; `Samsung` | Recommended | +| [`device.model.identifier`](../attributes-registry/device.md) | string | The model identifier for the device [3] | `iPhone3,4`; `SM-G920F` | Recommended | +| [`device.model.name`](../attributes-registry/device.md) | string | The marketing name for the device model [4] | `iPhone 6s Plus`; `Samsung Galaxy S6` | 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]:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`. -**[3]:** 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 machine-readable version of the model identifier rather than the market or consumer-friendly name of the device. -**[4]:** It's recommended this value represents a human readable version of the device model rather than a machine readable alternative. +**[4]:** It's recommended this value represents a human-readable version of the device model rather than a machine-readable alternative. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/resource/faas.md b/docs/resource/faas.md index f8560c1471..c83eabc193 100644 --- a/docs/resource/faas.md +++ b/docs/resource/faas.md @@ -16,7 +16,7 @@ See also: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`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) [1] | `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.resource_id`](../attributes-registry/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/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) [1] | `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 | | `faas.instance` | string | The execution environment ID as a string, that will be potentially reused for other invocations to the same function/function version. [2] | `2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de` | Recommended | | `faas.max_memory` | int | The amount of memory available to the serverless function converted to Bytes. [3] | `134217728` | Recommended | | `faas.name` | string | The name of the single function that this runtime instance executes. [4] | `my-function`; `myazurefunctionapp/some-function-name` | Required | @@ -34,7 +34,7 @@ The following well-known definitions MUST be used if you set this attribute and 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, +* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/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 diff --git a/docs/resource/host.md b/docs/resource/host.md index d074a30f6c..a11c735b86 100644 --- a/docs/resource/host.md +++ b/docs/resource/host.md @@ -9,20 +9,23 @@ The `host.*` namespace SHOULD be exclusively used to capture resource attributes. To report host metrics, the `system.*` namespace SHOULD be used. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `host.arch` | string | The CPU architecture the host system is running on. | `amd64` | Recommended | -| `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.image.id` | string | VM image ID or host OS image ID. For Cloud, this value is from the provider. | `ami-07b06b442921831e5` | 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.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.ip` | string[] | Available IP addresses of the host, excluding loopback interfaces. [1] | `[192.168.1.140, fe80::abc2:4a28:737a:609e]` | Opt-In | -| `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`](../attributes-registry/host.md) | string | The CPU architecture the host system is running on. | `amd64` | Recommended | +| [`host.id`](../attributes-registry/host.md) | 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.image.id`](../attributes-registry/host.md) | string | VM image ID or host OS image ID. For Cloud, this value is from the provider. | `ami-07b06b442921831e5` | Recommended | +| [`host.image.name`](../attributes-registry/host.md) | 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.version`](../attributes-registry/host.md) | string | The version string of the VM image or host OS as defined in [Version Attributes](/docs/resource/README.md#version-attributes). | `0.1` | Recommended | +| [`host.ip`](../attributes-registry/host.md) | string[] | Available IP addresses of the host, excluding loopback interfaces. [1] | `[192.168.1.140, fe80::abc2:4a28:737a:609e]` | Opt-In | +| [`host.mac`](../attributes-registry/host.md) | string[] | Available MAC addresses of the host, excluding loopback interfaces. [2] | `[AC-DE-48-23-45-67, AC-DE-48-23-45-67-01-9F]` | Opt-In | +| [`host.name`](../attributes-registry/host.md) | 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`](../attributes-registry/host.md) | string | Type of host. For Cloud, this must be the machine type. | `n1-standard-1` | Recommended | **[1]:** IPv4 Addresses MUST be specified in dotted-quad notation. IPv6 addresses MUST be specified in the [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952.html) format. +**[2]:** MAC Addresses MUST be represented in [IEEE RA hexadecimal form](https://standards.ieee.org/wp-content/uploads/import/documents/tutorials/eui.pdf): as hyphen-separated octets in uppercase hexadecimal form from most to least significant. + `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 | @@ -42,12 +45,12 @@ To report host metrics, the `system.*` namespace SHOULD be used. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `host.cpu.cache.l2.size` | int | The amount of level 2 memory cache available to the processor (in Bytes). | `12288000` | Opt-In | -| `host.cpu.family` | int | Numeric value specifying the family or generation of the CPU. | `6` | Opt-In | -| `host.cpu.model.id` | int | Model identifier. It provides more granular information about the CPU, distinguishing it from other CPUs within the same family. | `6` | Opt-In | -| `host.cpu.model.name` | string | Model designation of the processor. | `11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz` | Opt-In | -| `host.cpu.stepping` | int | Stepping or core revisions. | `1` | Opt-In | -| `host.cpu.vendor.id` | string | Processor manufacturer identifier. A maximum 12-character string. [1] | `GenuineIntel` | Opt-In | +| [`host.cpu.cache.l2.size`](../attributes-registry/host.md) | int | The amount of level 2 memory cache available to the processor (in Bytes). | `12288000` | Opt-In | +| [`host.cpu.family`](../attributes-registry/host.md) | string | Family or generation of the CPU. | `6`; `PA-RISC 1.1e` | Opt-In | +| [`host.cpu.model.id`](../attributes-registry/host.md) | string | Model identifier. It provides more granular information about the CPU, distinguishing it from other CPUs within the same family. | `6`; `9000/778/B180L` | Opt-In | +| [`host.cpu.model.name`](../attributes-registry/host.md) | string | Model designation of the processor. | `11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz` | Opt-In | +| [`host.cpu.stepping`](../attributes-registry/host.md) | int | Stepping or core revisions. | `1` | Opt-In | +| [`host.cpu.vendor.id`](../attributes-registry/host.md) | string | Processor manufacturer identifier. A maximum 12-character string. [1] | `GenuineIntel` | Opt-In | **[1]:** [CPUID](https://wiki.osdev.org/CPUID) command returns the vendor ID string in EBX, EDX and ECX registers. Writing these to memory in this order results in a 12-character string. diff --git a/docs/resource/k8s.md b/docs/resource/k8s.md index ef50c8a818..f5ed62b723 100644 --- a/docs/resource/k8s.md +++ b/docs/resource/k8s.md @@ -24,10 +24,10 @@ Kubernetes object, but "name" is usually more user friendly so can be also set. | 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 | +| [`k8s.cluster.name`](../attributes-registry/k8s.md) | string | The name of the cluster. | `opentelemetry-cluster` | Recommended | +| [`k8s.cluster.uid`](../attributes-registry/k8s.md) | 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 +**[1]:** K8s doesn't 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 @@ -60,8 +60,8 @@ conflict. | 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 | +| [`k8s.node.name`](../attributes-registry/k8s.md) | string | The name of the Node. | `node-1` | Recommended | +| [`k8s.node.uid`](../attributes-registry/k8s.md) | string | The UID of the Node. | `1eb3a0c6-0477-4080-a9cb-0cb7db65c6a2` | Recommended | ## Namespace @@ -76,7 +76,7 @@ a namespace, but not across namespaces. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `k8s.namespace.name` | string | The name of the namespace that the pod is running in. | `default` | Recommended | +| [`k8s.namespace.name`](../attributes-registry/k8s.md) | string | The name of the namespace that the pod is running in. | `default` | Recommended | ## Pod @@ -91,8 +91,9 @@ containers on your cluster. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `k8s.pod.name` | string | The name of the Pod. | `opentelemetry-pod-autoconf` | Recommended | -| `k8s.pod.uid` | string | The UID of the Pod. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | +| [`k8s.pod.labels.`](../attributes-registry/k8s.md) | string | The labels placed on the Pod, the `` being the label name, the value being the label value. | `k8s.pod.labels.app=my-app`; `k8s.pod.labels.mycompany.io/arch=x64`; `k8s.pod.labels.data=` | Recommended | +| [`k8s.pod.name`](../attributes-registry/k8s.md) | string | The name of the Pod. | `opentelemetry-pod-autoconf` | Recommended | +| [`k8s.pod.uid`](../attributes-registry/k8s.md) | string | The UID of the Pod. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | ## Container @@ -111,8 +112,8 @@ to a running container. | 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 | +| [`k8s.container.name`](../attributes-registry/k8s.md) | 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`](../attributes-registry/k8s.md) | 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 @@ -127,8 +128,8 @@ any given time. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `k8s.replicaset.name` | string | The name of the ReplicaSet. | `opentelemetry` | Recommended | -| `k8s.replicaset.uid` | string | The UID of the ReplicaSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | +| [`k8s.replicaset.name`](../attributes-registry/k8s.md) | string | The name of the ReplicaSet. | `opentelemetry` | Recommended | +| [`k8s.replicaset.uid`](../attributes-registry/k8s.md) | string | The UID of the ReplicaSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | ## Deployment @@ -144,8 +145,8 @@ distributed among the nodes of a cluster. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `k8s.deployment.name` | string | The name of the Deployment. | `opentelemetry` | Recommended | -| `k8s.deployment.uid` | string | The UID of the Deployment. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | +| [`k8s.deployment.name`](../attributes-registry/k8s.md) | string | The name of the Deployment. | `opentelemetry` | Recommended | +| [`k8s.deployment.uid`](../attributes-registry/k8s.md) | string | The UID of the Deployment. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | ## StatefulSet @@ -160,8 +161,8 @@ about the ordering and uniqueness of these Pods. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `k8s.statefulset.name` | string | The name of the StatefulSet. | `opentelemetry` | Recommended | -| `k8s.statefulset.uid` | string | The UID of the StatefulSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | +| [`k8s.statefulset.name`](../attributes-registry/k8s.md) | string | The name of the StatefulSet. | `opentelemetry` | Recommended | +| [`k8s.statefulset.uid`](../attributes-registry/k8s.md) | string | The UID of the StatefulSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | ## DaemonSet @@ -175,8 +176,8 @@ A DaemonSet ensures that all (or some) Nodes run a copy of a Pod. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `k8s.daemonset.name` | string | The name of the DaemonSet. | `opentelemetry` | Recommended | -| `k8s.daemonset.uid` | string | The UID of the DaemonSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | +| [`k8s.daemonset.name`](../attributes-registry/k8s.md) | string | The name of the DaemonSet. | `opentelemetry` | Recommended | +| [`k8s.daemonset.uid`](../attributes-registry/k8s.md) | string | The UID of the DaemonSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | ## Job @@ -191,8 +192,8 @@ successfully terminate. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `k8s.job.name` | string | The name of the Job. | `opentelemetry` | Recommended | -| `k8s.job.uid` | string | The UID of the Job. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | +| [`k8s.job.name`](../attributes-registry/k8s.md) | string | The name of the Job. | `opentelemetry` | Recommended | +| [`k8s.job.uid`](../attributes-registry/k8s.md) | string | The UID of the Job. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | ## CronJob @@ -206,8 +207,8 @@ A CronJob creates Jobs on a repeating schedule. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `k8s.cronjob.name` | string | The name of the CronJob. | `opentelemetry` | Recommended | -| `k8s.cronjob.uid` | string | The UID of the CronJob. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | +| [`k8s.cronjob.name`](../attributes-registry/k8s.md) | string | The name of the CronJob. | `opentelemetry` | Recommended | +| [`k8s.cronjob.uid`](../attributes-registry/k8s.md) | string | The UID of the CronJob. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/resource/os.md b/docs/resource/os.md index 542b61ad2a..4b681018d9 100644 --- a/docs/resource/os.md +++ b/docs/resource/os.md @@ -8,14 +8,14 @@ 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.build_id` | string | Unique identifier for a particular build or compilation of the operating system. | `TQ3C.230805.001.B2`; `20E247`; `22621` | Recommended | -| `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.type` | string | The operating system type. | `windows` | Required | -| `os.version` | string | The version string of the operating system as defined in [Version Attributes](/docs/resource/README.md#version-attributes). | `14.2.1`; `18.04.1` | Recommended | +| [`os.build_id`](../attributes-registry/os.md) | string | Unique identifier for a particular build or compilation of the operating system. | `TQ3C.230805.001.B2`; `20E247`; `22621` | Recommended | +| [`os.description`](../attributes-registry/os.md) | 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`](../attributes-registry/os.md) | string | Human readable operating system name. | `iOS`; `Android`; `Ubuntu` | Recommended | +| [`os.type`](../attributes-registry/os.md) | string | The operating system type. | `windows` | Required | +| [`os.version`](../attributes-registry/os.md) | string | The version string of the operating system as defined in [Version Attributes](/docs/resource/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. diff --git a/docs/resource/process.md b/docs/resource/process.md index 737c4aca68..b3817f34df 100644 --- a/docs/resource/process.md +++ b/docs/resource/process.md @@ -27,22 +27,22 @@ | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `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_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.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.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.owner` | string | The username of the user that owns the process. | `root` | Recommended | -| `process.parent_pid` | int | Parent Process identifier (PID). | `111` | Recommended | -| `process.pid` | int | Process identifier (PID). | `1234` | Recommended | +| [`process.command`](../attributes-registry/process.md) | 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_args`](../attributes-registry/process.md) | 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.command_line`](../attributes-registry/process.md) | 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.executable.name`](../attributes-registry/process.md) | 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`](../attributes-registry/process.md) | 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.owner`](../attributes-registry/process.md) | string | The username of the user that owns the process. | `root` | Recommended | +| [`process.parent_pid`](../attributes-registry/process.md) | int | Parent Process identifier (PID). | `111` | Recommended | +| [`process.pid`](../attributes-registry/process.md) | int | Process identifier (PID). | `1234` | 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` +* [`process.executable.name`](../attributes-registry/process.md) +* [`process.executable.path`](../attributes-registry/process.md) +* [`process.command`](../attributes-registry/process.md) +* [`process.command_line`](../attributes-registry/process.md) +* [`process.command_args`](../attributes-registry/process.md) Between `process.command_args` and `process.command_line`, usually `process.command_args` should be preferred. @@ -62,9 +62,9 @@ In that case it MUST be interpreted as if it was `process.command_args`. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `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 | -| `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`](../attributes-registry/process.md) | 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 | +| [`process.runtime.name`](../attributes-registry/process.md) | 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`](../attributes-registry/process.md) | string | The version of the runtime of this process, as returned by the runtime without modification. | `14.0.2` | Recommended | How to set these attributes for particular runtime kinds is described in the following subsections. diff --git a/docs/rpc/connect-rpc.md b/docs/rpc/connect-rpc.md index 75798f2fb8..dd590f75dd 100644 --- a/docs/rpc/connect-rpc.md +++ b/docs/rpc/connect-rpc.md @@ -16,12 +16,12 @@ described on this page. Below is a table of attributes that SHOULD be included on client and server Connect RPC measurements. - + | 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] | -| `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. [2] | `rpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]` | Opt-In | -| `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. [3] | `rpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]` | Opt-In | +| [`rpc.connect_rpc.error_code`](../attributes-registry/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] | +| [`rpc.connect_rpc.request.metadata.`](../attributes-registry/rpc.md) | string[] | Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. [2] | `rpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]` | Opt-In | +| [`rpc.connect_rpc.response.metadata.`](../attributes-registry/rpc.md) | string[] | Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. [3] | `rpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]` | Opt-In | **[1]:** If response is not successful and if error code available. diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md index 8ff11b8cf8..100f17dc4b 100644 --- a/docs/rpc/grpc.md +++ b/docs/rpc/grpc.md @@ -16,12 +16,12 @@ described on this page. Below is a table of attributes that SHOULD be included on client and server gRPC measurements. - + | 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. [2] | `rpc.grpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]` | Opt-In | -| `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.request.metadata.`](../attributes-registry/rpc.md) | string[] | gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), 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.`](../attributes-registry/rpc.md) | string[] | gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. [2] | `rpc.grpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]` | Opt-In | +| [`rpc.grpc.status_code`](../attributes-registry/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 | **[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. diff --git a/docs/rpc/json-rpc.md b/docs/rpc/json-rpc.md index e0842a6c0b..dbf79fca70 100644 --- a/docs/rpc/json-rpc.md +++ b/docs/rpc/json-rpc.md @@ -14,14 +14,14 @@ described on this page. `rpc.system` MUST be set to `"jsonrpc"`. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `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.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.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.method`](rpc-spans.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [1] | `exampleMethod` | Required | +| [`rpc.jsonrpc.error_code`](../attributes-registry/rpc.md) | 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`](../attributes-registry/rpc.md) | string | `error.message` property of response if it is an error response. | `Parse error`; `User already exists` | Recommended | +| [`rpc.jsonrpc.request_id`](../attributes-registry/rpc.md) | 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.version`](../attributes-registry/rpc.md) | string | Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted. | `2.0`; `1.0` | Conditionally Required: If other than the default version (`1.0`) | +| [`rpc.method`](../attributes-registry/rpc.md) | 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/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index f9994db859..106e2e6c4a 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -59,8 +59,7 @@ metrics can be filtered for finer grain analysis. > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version > for at least six months after it starts emitting both sets of conventions. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). +> * SHOULD drop the environment variable in the next major version. ## Metric instruments @@ -220,18 +219,18 @@ measurements. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | -| [`rpc.method`](rpc-spans.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [3] | `exampleMethod` | Recommended | -| [`rpc.service`](rpc-spans.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [4] | `myservice.EchoService` | Recommended | -| [`rpc.system`](rpc-spans.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number. [6] | `80`; `8080`; `443` | Recommended | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | +| [`rpc.method`](../attributes-registry/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [3] | `exampleMethod` | Recommended | +| [`rpc.service`](../attributes-registry/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [4] | `myservice.EchoService` | Recommended | +| [`rpc.system`](../attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport, for example +a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. **[2]:** The value SHOULD be normalized to lowercase. @@ -240,10 +239,9 @@ different processes could be listening on TCP port 12345 and UDP port 12345. **[4]:** 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). -**[5]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent -the server address behind any intermediaries (e.g. proxies) if it's available. +**[5]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `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. @@ -251,7 +249,7 @@ the server address behind any intermediaries (e.g. proxies) if it's available. |---|---| | `tcp` | TCP | | `udp` | UDP | -| `pipe` | Named or anonymous pipe. See note below. | +| `pipe` | Named or anonymous pipe. | | `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. @@ -272,10 +270,6 @@ the server address behind any intermediaries (e.g. proxies) if it's available. | `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). diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index eb1a9a9298..c3a9554350 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -49,8 +49,7 @@ This document defines how to describe remote procedure calls > * Note: `http/dup` has higher precedence than `http` in case both values are present > * SHOULD maintain (security patching at a minimum) the existing major version > for at least six months after it starts emitting both sets of conventions. -> * SHOULD drop the environment variable in the next major version (stable -> next major version SHOULD NOT be released prior to October 1, 2023). +> * SHOULD drop the environment variable in the next major version. ## Common remote procedure call conventions @@ -82,21 +81,21 @@ Examples of span names: ### Common attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | -| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [3] | `exampleMethod` | Recommended | -| `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [4] | `myservice.EchoService` | Recommended | -| `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | -| [`server.address`](../general/attributes.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../general/attributes.md) | int | Server port number. [6] | `80`; `8080`; `443` | Conditionally Required: See below | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | +| [`rpc.method`](../attributes-registry/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [3] | `exampleMethod` | Recommended | +| [`rpc.service`](../attributes-registry/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [4] | `myservice.EchoService` | Recommended | +| [`rpc.system`](../attributes-registry/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | +| [`server.address`](../attributes-registry/server.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [6] | `80`; `8080`; `443` | Conditionally Required: [7] | **[1]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport, for example +a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. **[2]:** The value SHOULD be normalized to lowercase. @@ -107,7 +106,25 @@ different processes could be listening on TCP port 12345 and UDP port 12345. **[5]:** 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. -**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[7]:** if the port is supported by the network transport used for communication. + +`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. | +| `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 | `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. @@ -120,9 +137,6 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | `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. @@ -142,8 +156,8 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended: If different than `server.address`. | -| [`network.peer.port`](../general/attributes.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | ### Server attributes @@ -151,21 +165,21 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`client.address`](../general/attributes.md) | string | Client address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`client.port`](../general/attributes.md) | int | Client port number. [2] | `65123` | Recommended | -| [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended: If different than `client.address`. | -| [`network.peer.port`](../general/attributes.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | -| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | Recommended | +| [`client.address`](../attributes-registry/client.md) | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`client.port`](../attributes-registry/client.md) | int | Client port number. [2] | `65123` | Recommended | +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | Recommended | -**[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries (e.g. proxies) if it's available. +**[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries, for example proxies, if it's available. -**[2]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port 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 the client port behind any intermediaries, for example proxies, if it's available. **[3]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport, for example +a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. **[4]:** The value SHOULD be normalized to lowercase. diff --git a/docs/runtime/README.md b/docs/runtime/README.md index bc6f2c9b75..24d221e3b6 100644 --- a/docs/runtime/README.md +++ b/docs/runtime/README.md @@ -1,5 +1,5 @@ # Semantic Conventions for Runtime Environment diff --git a/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md index a5d656ba5c..41e2d38ac4 100644 --- a/docs/runtime/jvm-metrics.md +++ b/docs/runtime/jvm-metrics.md @@ -13,10 +13,10 @@ This document describes semantic conventions for JVM metrics in OpenTelemetry. - [JVM Memory](#jvm-memory) - * [Metric: `jvm.memory.usage`](#metric-jvmmemoryusage) + * [Metric: `jvm.memory.used`](#metric-jvmmemoryused) * [Metric: `jvm.memory.committed`](#metric-jvmmemorycommitted) * [Metric: `jvm.memory.limit`](#metric-jvmmemorylimit) - * [Metric: `jvm.memory.usage_after_last_gc`](#metric-jvmmemoryusage_after_last_gc) + * [Metric: `jvm.memory.used_after_last_gc`](#metric-jvmmemoryused_after_last_gc) - [JVM Garbage Collection](#jvm-garbage-collection) * [Metric: `jvm.gc.duration`](#metric-jvmgcduration) - [JVM Threads](#jvm-threads) @@ -43,18 +43,18 @@ This document describes semantic conventions for JVM metrics in OpenTelemetry. **Description:** Java Virtual Machine (JVM) metrics captured under the namespace `jvm.memory.*` -### Metric: `jvm.memory.usage` +### Metric: `jvm.memory.used` This metric is [recommended][MetricRecommended]. 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 | | -------- | --------------- | ----------- | -------------- | -| `jvm.memory.usage` | UpDownCounter | `By` | Measure of memory used. | +| `jvm.memory.used` | UpDownCounter | `By` | Measure of memory used. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | @@ -124,18 +124,18 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle | `non_heap` | Non-heap memory | -### Metric: `jvm.memory.usage_after_last_gc` +### Metric: `jvm.memory.used_after_last_gc` This metric is [recommended][MetricRecommended]. 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 | | -------- | --------------- | ----------- | -------------- | -| `jvm.memory.usage_after_last_gc` | UpDownCounter | `By` | Measure of memory used, as measured after the most recent garbage collection event on this pool. | +| `jvm.memory.used_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 | |---|---|---|---|---| | `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | @@ -162,8 +162,8 @@ 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`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advice) -of `[]` (single bucket histogram capturing count, sum, min, max). +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advisory-parameters) +of `[ 0.01, 0.1, 1, 10 ]`. | Name | Instrument Type | Unit (UCUM) | Description | @@ -189,8 +189,13 @@ of `[]` (single bucket histogram capturing count, sum, min, max). ### Metric: `jvm.thread.count` This metric is [recommended][MetricRecommended]. -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--). +This metric is obtained from a combination of + +* [`ThreadMXBean#getAllThreadIds()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getAllThreadIds--) +* [`ThreadMXBean#getThreadInfo()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getThreadInfo-long:A-) +* [`ThreadInfo#getThreadState()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadInfo.html#getThreadState--) +* [`ThreadInfo#isDaemon()`](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/ThreadInfo.html#isDaemon()) (requires Java 9+) + Note that this is the number of platform threads (as opposed to virtual threads). @@ -202,7 +207,19 @@ Note that this is the number of platform threads (as opposed to virtual threads) | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`thread.daemon`](../general/attributes.md) | boolean | Whether the thread is daemon or not. | | Recommended | +| `jvm.thread.daemon` | boolean | Whether the thread is daemon or not. | | Recommended | +| `jvm.thread.state` | string | State of the thread. | `runnable`; `blocked` | Recommended | + +`jvm.thread.state` MUST be one of the following: + +| Value | Description | +|---|---| +| `new` | A thread that has not yet started is in this state. | +| `runnable` | A thread executing in the Java virtual machine is in this state. | +| `blocked` | A thread that is blocked waiting for a monitor lock is in this state. | +| `waiting` | A thread that is waiting indefinitely for another thread to perform a particular action is in this state. | +| `timed_waiting` | A thread that is waiting for another thread to perform an action for up to a specified waiting time is in this state. | +| `terminated` | A thread that has exited is in this state. | ## JVM Classes diff --git a/docs/system/hardware-metrics.md b/docs/system/hardware-metrics.md index b5b6cee212..904dd8c74d 100644 --- a/docs/system/hardware-metrics.md +++ b/docs/system/hardware-metrics.md @@ -298,7 +298,7 @@ Additional **Recommended** attributes: | | | | | | `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.physical_disk.smart` | Value of the corresponding [S.M.A.R.T.](https://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` | diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index c92dff04e5..d39384babc 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -26,8 +26,10 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam * [Metric: `system.cpu.utilization`](#metric-systemcpuutilization) * [Metric: `system.cpu.physical.count`](#metric-systemcpuphysicalcount) * [Metric: `system.cpu.logical.count`](#metric-systemcpulogicalcount) + * [Metric: `system.cpu.frequency`](#metric-systemcpufrequency) - [Memory Metrics](#memory-metrics) * [Metric: `system.memory.usage`](#metric-systemmemoryusage) + * [Metric: `system.memory.limit`](#metric-systemmemorylimit) * [Metric: `system.memory.utilization`](#metric-systemmemoryutilization) - [Paging/Swap Metrics](#pagingswap-metrics) * [Metric: `system.paging.usage`](#metric-systempagingusage) @@ -145,6 +147,22 @@ This metric is [recommended][MetricRecommended]. +### Metric: `system.cpu.frequency` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.cpu.frequency` | Gauge | `{Hz}` | Reports the current frequency of the CPU in Hz | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `system.cpu.logical_number` | int | The logical CPU number [0..n-1] | `1` | Recommended | + + ## Memory Metrics **Description:** System level memory metrics capture under the namespace `system.memory`. @@ -157,7 +175,10 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `system.memory.usage` | UpDownCounter | `By` | | +| `system.memory.usage` | UpDownCounter | `By` | Reports memory in use by state. [1] | + +**[1]:** The sum over all `system.memory.state` values SHOULD equal the total memory +available on the system, that is `system.memory.limit`. @@ -169,7 +190,6 @@ This metric is [recommended][MetricRecommended]. | Value | Description | |---|---| -| `total` | total | | `used` | used | | `free` | free | | `shared` | shared | @@ -177,6 +197,21 @@ This metric is [recommended][MetricRecommended]. | `cached` | cached | +### Metric: `system.memory.limit` + +This metric is [opt-in][MetricOptIn]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.memory.limit` | UpDownCounter | `By` | Total memory available in the system. [1] | + +**[1]:** Its value SHOULD equal the sum of `system.memory.state` over all states. + + + + + ### Metric: `system.memory.utilization` This metric is [recommended][MetricRecommended]. @@ -196,7 +231,6 @@ This metric is [recommended][MetricRecommended]. | Value | Description | |---|---| -| `total` | total | | `used` | used | | `free` | free | | `shared` | shared | @@ -325,10 +359,10 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| [`disk.io.direction`](../attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | Recommended | | `system.device` | string | The device identifier | `(identifier)` | Recommended | -| `system.disk.direction` | string | The disk operation direction | `read` | Recommended | -`system.disk.direction` MUST be one of the following: +`disk.io.direction` MUST be one of the following: | Value | Description | |---|---| @@ -349,10 +383,10 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| [`disk.io.direction`](../attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | Recommended | | `system.device` | string | The device identifier | `(identifier)` | Recommended | -| `system.disk.direction` | string | The disk operation direction | `read` | Recommended | -`system.disk.direction` MUST be one of the following: +`disk.io.direction` MUST be one of the following: | Value | Description | |---|---| @@ -373,7 +407,7 @@ This metric is [recommended][MetricRecommended]. - Linux: Field 13 from [procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) - Windows: The complement of - ["Disk\% Idle Time"](https://learn.microsoft.com/en-us/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained) + ["Disk\% Idle Time"](https://learn.microsoft.com/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained) performance counter: `uptime * (100 - "Disk\% Idle Time") / 100` @@ -401,10 +435,10 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| [`disk.io.direction`](../attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | Recommended | | `system.device` | string | The device identifier | `(identifier)` | Recommended | -| `system.disk.direction` | string | The disk operation direction | `read` | Recommended | -`system.disk.direction` MUST be one of the following: +`disk.io.direction` MUST be one of the following: | Value | Description | |---|---| @@ -425,10 +459,10 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| [`disk.io.direction`](../attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | Recommended | | `system.device` | string | The device identifier | `(identifier)` | Recommended | -| `system.disk.direction` | string | The disk operation direction | `read` | Recommended | -`system.disk.direction` MUST be one of the following: +`disk.io.direction` MUST be one of the following: | Value | Description | |---|---| @@ -534,17 +568,17 @@ This metric is [recommended][MetricRecommended]. **[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) +- Windows: [`InDiscards`/`OutDiscards`](https://docs.microsoft.com/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) + from [`GetIfEntry2`](https://docs.microsoft.com/windows/win32/api/netioapi/nf-netioapi-getifentry2) | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| [`network.io.direction`](../attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | Recommended | | `system.device` | string | The device identifier | `(identifier)` | Recommended | -| `system.network.direction` | string | | `transmit` | Recommended | -`system.network.direction` MUST be one of the following: +`network.io.direction` MUST be one of the following: | Value | Description | |---|---| @@ -565,10 +599,10 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| [`network.io.direction`](../attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | Recommended | | `system.device` | string | The device identifier | `(identifier)` | Recommended | -| `system.network.direction` | string | | `transmit` | Recommended | -`system.network.direction` MUST be one of the following: +`network.io.direction` MUST be one of the following: | Value | Description | |---|---| @@ -588,17 +622,17 @@ This metric is [recommended][MetricRecommended]. **[1]:** 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). +- Windows: [`InErrors`/`OutErrors`](https://docs.microsoft.com/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) + from [`GetIfEntry2`](https://docs.microsoft.com/windows/win32/api/netioapi/nf-netioapi-getifentry2). | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| [`network.io.direction`](../attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | Recommended | | `system.device` | string | The device identifier | `(identifier)` | Recommended | -| `system.network.direction` | string | | `transmit` | Recommended | -`system.network.direction` MUST be one of the following: +`network.io.direction` MUST be one of the following: | Value | Description | |---|---| @@ -619,10 +653,10 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| [`network.io.direction`](../attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | Recommended | | `system.device` | string | The device identifier | `(identifier)` | Recommended | -| `system.network.direction` | string | | `transmit` | Recommended | -`system.network.direction` MUST be one of the following: +`network.io.direction` MUST be one of the following: | Value | Description | |---|---| @@ -643,14 +677,14 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended | +| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended | | `system.device` | string | The device identifier | `(identifier)` | Recommended | | `system.network.state` | string | A stateless protocol MUST NOT set this attribute | `close_wait` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport, for example +a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345. `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. @@ -659,7 +693,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. |---|---| | `tcp` | TCP | | `udp` | UDP | -| `pipe` | Named or anonymous pipe. See note below. | +| `pipe` | Named or anonymous pipe. | | `unix` | Unix domain socket | `system.network.state` MUST be one of the following: @@ -730,7 +764,7 @@ 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 +average](https://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: @@ -752,6 +786,7 @@ an `{os}` prefix to split this metric across OSes. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md [MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#recommended +[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.26.0/specification/metrics/metric-requirement-level.md#opt-in ### Metric: `system.linux.memory.available` diff --git a/docs/url/url.md b/docs/url/url.md index 0b8cc15980..f9605574ee 100644 --- a/docs/url/url.md +++ b/docs/url/url.md @@ -25,19 +25,17 @@ This document defines semantic conventions that describe URL and its components. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `url.fragment` | string | The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component | `SemConv` | Recommended | -| `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | -| `url.path` | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [2] | `/search` | Recommended | -| `url.query` | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [3] | `q=OpenTelemetry` | Recommended | -| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Recommended | - -**[1]:** 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.fragment`](../attributes-registry/url.md) | string | The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component | `SemConv` | Recommended | +| [`url.full`](../attributes-registry/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | +| [`url.path`](../attributes-registry/url.md) | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component | `/search` | Recommended | +| [`url.query`](../attributes-registry/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [2] | `q=OpenTelemetry` | Recommended | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Recommended | + +**[1]:** 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. -**[2]:** When missing, the value is assumed to be `/` - -**[3]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. +**[2]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. ## Sensitive information diff --git a/internal/tools/schema_check.sh b/internal/tools/schema_check.sh index 32c489d1a7..801fcee04f 100755 --- a/internal/tools/schema_check.sh +++ b/internal/tools/schema_check.sh @@ -6,7 +6,7 @@ set -e -BUILD_TOOL_SCHEMAS_VERSION=0.22.0 +BUILD_TOOL_SCHEMAS_VERSION=0.23.0 # List of versions that do not require or have a schema. declare -a skip_versions=("1.0.0" "1.0.1" "1.1.0" "1.2.0" "1.3.0" "1.6.0") diff --git a/internal/tools/update_specification_version.sh b/internal/tools/update_specification_version.sh index 86cd140b88..765c6c6f88 100755 --- a/internal/tools/update_specification_version.sh +++ b/internal/tools/update_specification_version.sh @@ -12,6 +12,9 @@ LATEST_SPECIFICATION_VERSION="v1.26.0" # The specific pattern we look for when replacing URLs SPECIFICATION_URL_PREFIX="https://github.com/open-telemetry/opentelemetry-specification/tree/" SPECIFICATION_BLOB_URL_PREFIX="https://github.com/open-telemetry/opentelemetry-specification/blob/" +# The specific pattern we look for updating the Badge with the spec version +SPECIFICATION_BADGE_PREFIX="https://img.shields.io/badge/OTel_specification_version-" +SPECIFICATION_BADGE_RELEASE_TAG_PREFIX="https://github.com/open-telemetry/opentelemetry-specification/releases/tag/" fix_file() { @@ -19,6 +22,8 @@ fix_file() { sed -i \ -e "s,${SPECIFICATION_URL_PREFIX}${PREVIOUS_SPECIFICATION_VERSION},${SPECIFICATION_URL_PREFIX}${LATEST_SPECIFICATION_VERSION},g" \ -e "s,${SPECIFICATION_BLOB_URL_PREFIX}${PREVIOUS_SPECIFICATION_VERSION},${SPECIFICATION_URL_PREFIX}${LATEST_SPECIFICATION_VERSION},g" \ + -e "s,${SPECIFICATION_BADGE_PREFIX}${PREVIOUS_SPECIFICATION_VERSION},${SPECIFICATION_BADGE_PREFIX}${LATEST_SPECIFICATION_VERSION},g" \ + -e "s,${SPECIFICATION_BADGE_RELEASE_TAG_PREFIX}${PREVIOUS_SPECIFICATION_VERSION},${SPECIFICATION_BADGE_RELEASE_TAG_PREFIX}${LATEST_SPECIFICATION_VERSION},g" \ "$1" } diff --git a/model/README.md b/model/README.md index 33f3cd3379..2fc6f39b35 100644 --- a/model/README.md +++ b/model/README.md @@ -10,16 +10,16 @@ the generated markdown output in the [docs](../docs/README.md) folder. ## Writing semantic conventions Semantic conventions for the spec MUST adhere to the -[attribute naming](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/common/attribute-naming.md), -[attribute requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/common/attribute-requirement-level.md), +[attribute naming](../docs/general/attribute-naming.md), +[attribute requirement level](../docs/general/attribute-requirement-level.md), and [metric requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md) conventions. -Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.22.0/semantic-conventions/syntax.md) +Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.23.0/semantic-conventions/syntax.md) for how to write the YAML files for semantic conventions and what the YAML properties mean. A schema file for VS code is configured in the `/.vscode/settings.json` of this repository, enabling auto-completion and additional checks. Refer to -[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.22.0/semantic-conventions/README.md) for what extension you need. +[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.23.0/semantic-conventions/README.md) for what extension you need. ## Generating markdown @@ -30,7 +30,7 @@ formatted Markdown tables for all semantic conventions in the specification. Run make table-generation ``` -For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.22.0/semantic-conventions) +For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.23.0/semantic-conventions) in the OpenTelemetry build tools repository. Using this build tool, it is also possible to generate code for use in OpenTelemetry language projects. diff --git a/model/general.yaml b/model/general.yaml index 4f387bac6f..e3bad3d46a 100644 --- a/model/general.yaml +++ b/model/general.yaml @@ -1,4 +1,32 @@ groups: + - id: general.client + type: attribute_group + brief: > + General client attributes. + attributes: + - ref: client.address + - ref: client.port + - id: general.server + type: attribute_group + brief: > + General server attributes. + attributes: + - ref: server.address + - ref: server.port + - id: general.source + type: attribute_group + brief: > + General source attributes. + attributes: + - ref: source.address + - ref: source.port + - id: general.destination + type: attribute_group + brief: > + General destination attributes. + attributes: + - ref: destination.address + - ref: destination.port - id: peer prefix: peer type: span @@ -37,53 +65,21 @@ groups: 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). examples: 'read:message, write:files' - id: thread - prefix: thread type: span brief: > These attributes may be used for any operation to store information about a thread that started a span. attributes: - - id: id - type: int - brief: > - Current "managed" thread ID (as opposed to OS thread ID). - examples: 42 - - id: name - type: string - brief: > - Current thread name. - examples: main - - id: daemon - brief: "Whether the thread is daemon or not." - type: boolean + - ref: thread.id + - ref: thread.name - id: code - prefix: code type: span brief: > These attributes allow to report this unit of code and therefore to provide more context about the span. attributes: - - id: function - type: string - brief: > - The method or function name, or equivalent (usually rightmost part of the code unit's name). - examples: serveRequest - - id: namespace - type: string - brief: > - 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. - examples: com.example.MyHttpService - - id: filepath - type: string - brief: > - The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). - examples: /usr/local/MyApplication/content_root/app/index.php - - id: lineno - type: int - brief: > - The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. - examples: 42 - - id: column - type: int - brief: > - The column number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. - examples: 16 + - ref: code.function + - ref: code.namespace + - ref: code.filepath + - ref: code.lineno + - ref: code.column + - ref: code.stacktrace + requirement_level: opt_in diff --git a/model/http-common.yaml b/model/http-common.yaml index f10e7de342..2187943dda 100644 --- a/model/http-common.yaml +++ b/model/http-common.yaml @@ -32,7 +32,7 @@ groups: - ref: network.protocol.name examples: ['http', 'spdy'] requirement_level: - recommended: if not default (`http`). + conditionally_required: If not `http` and `network.protocol.version` is set. - ref: network.protocol.version examples: ['1.0', '1.1', '2', '3'] @@ -45,23 +45,16 @@ groups: requirement_level: required brief: > Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: | - 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 - + note: > 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. - ref: server.port - requirement_level: - conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). + requirement_level: required brief: > Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: > - 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. + - ref: url.scheme + requirement_level: opt_in + examples: ["http", "https"] - id: attributes.http.server type: attribute_group @@ -74,29 +67,21 @@ groups: - ref: server.address brief: > Name of the local HTTP server that received the request. - note: | - Determined by using the first of the following that applies - - - The [primary server name](/docs/http/http-spans.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. - + note: > + See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). - ref: server.port brief: > Port of the local HTTP server that received the request. - note: | - Determined by using the first of the following that applies - - - Port identifier of the [primary server host](/docs/http/http-spans.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 + note: > + See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). requirement_level: - recommended: If not default (`80` for `http` scheme, `443` for `https`). + conditionally_required: If `server.address` is set. - ref: url.scheme requirement_level: required examples: ["http", "https"] + note: > + The scheme of the original client request, if known + (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), + [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), + or a similar header). + Otherwise, the scheme of the immediate peer request. diff --git a/model/logs/events.yaml b/model/logs/events.yaml index f3398c9ac1..3942d432fd 100644 --- a/model/logs/events.yaml +++ b/model/logs/events.yaml @@ -9,24 +9,10 @@ groups: type: string requirement_level: required brief: > - The name identifies the event. - examples: ['click', 'exception'] - - id: domain - brief: > - The domain identifies the business context for the events. - type: - allow_custom_values: true - members: - - id: browser - value: 'browser' - brief: 'Events from browser apps' - - id: device - value: 'device' - brief: 'Events from mobile apps' - - id: k8s - value: 'k8s' - brief: 'Events from Kubernetes' - requirement_level: required - note: | - Events across different domains may have same `event.name`, yet be - unrelated events. + Identifies the class / type of event. + note: > + Event names are subject to the same rules as [attribute names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/common/attribute-naming.md). + Notably, event names are namespaced to avoid collisions and provide a clean + separation of semantics for events in separate domains like browser, mobile, and + kubernetes. + examples: ['browser.mouse.click', 'device.app.lifecycle'] diff --git a/model/logs/mobile-events.yaml b/model/logs/mobile-events.yaml new file mode 100644 index 0000000000..d6f49e70c5 --- /dev/null +++ b/model/logs/mobile-events.yaml @@ -0,0 +1,72 @@ +groups: + - id: ios.lifecycle.events + type: event + prefix: ios + name: device.app.lifecycle + brief: > + This event represents an occurrence of a lifecycle transition on the iOS platform. + attributes: + - id: state + requirement_level: "required" + note: > + The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), + and from which the `OS terminology` column values are derived. + brief: > + This attribute represents the state the application has transitioned into at the occurrence of the event. + type: + allow_custom_values: false + members: + - id: active + value: 'active' + brief: > + The app has become `active`. Associated with UIKit notification `applicationDidBecomeActive`. + - id: inactive + value: 'inactive' + brief: > + The app is now `inactive`. Associated with UIKit notification `applicationWillResignActive`. + - id: background + value: 'background' + brief: > + The app is now in the background. + This value is associated with UIKit notification `applicationDidEnterBackground`. + - id: foreground + value: 'foreground' + brief: > + The app is now in the foreground. + This value is associated with UIKit notification `applicationWillEnterForeground`. + - id: terminate + value: 'terminate' + brief: > + The app is about to terminate. Associated with UIKit notification `applicationWillTerminate`. + - id: android.lifecycle.events + type: event + prefix: android + name: device.app.lifecycle + brief: > + This event represents an occurrence of a lifecycle transition on the Android platform. + attributes: + - id: state + requirement_level: required + brief: > + This attribute represents the state the application has transitioned into at the occurrence of the event. + note: > + The Android lifecycle states are defined in [Activity lifecycle callbacks](https://developer.android.com/guide/components/activities/activity-lifecycle#lc), + and from which the `OS identifiers` are derived. + type: + allow_custom_values: false + members: + - id: created + value: 'created' + brief: > + Any time before Activity.onResume() or, if the app has no Activity, Context.startService() + has been called in the app for the first time. + - id: background + value: 'background' + brief: > + Any time after Activity.onPause() or, if the app has no Activity, + Context.stopService() has been called when the app was in the foreground state. + - id: foreground + value: 'foreground' + brief: > + Any time after Activity.onResume() or, if the app has no Activity, + Context.startService() has been called when the app was in either the created or background states. diff --git a/model/messaging-common.yaml b/model/messaging-common.yaml new file mode 100644 index 0000000000..07ef5f4a78 --- /dev/null +++ b/model/messaging-common.yaml @@ -0,0 +1,23 @@ +groups: + - id: messaging.attributes.common + type: attribute_group + brief: "Common messaging attributes." + prefix: messaging + attributes: + - ref: messaging.system + requirement_level: required + - ref: error.type + examples: ['amqp:decode-error', 'KAFKA_STORAGE_ERROR', 'channel-error'] + requirement_level: + conditionally_required: If and only if the messaging operation has failed. + - ref: server.address + note: > + This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. + requirement_level: + conditionally_required: If available. + - ref: server.port + - ref: network.protocol.name + examples: ['amqp', 'mqtt'] + tag: connection-level + - ref: network.protocol.version + tag: connection-level diff --git a/model/metrics/database-metrics.yaml b/model/metrics/database-metrics.yaml index fdb6a0ce2a..3df6d86a2c 100644 --- a/model/metrics/database-metrics.yaml +++ b/model/metrics/database-metrics.yaml @@ -19,7 +19,7 @@ groups: requirement_level: required brief: > The name of the connection pool; unique within the instrumented application. - In case the connection pool implementation does not provide a name, + In case the connection pool implementation doesn't provide a name, then the [db.connection_string](/docs/database/database-spans.md#connection-level-attributes) should be used examples: ["myDataSource"] diff --git a/model/metrics/faas-metrics.yaml b/model/metrics/faas-metrics.yaml index 6a753a7351..d68119f320 100644 --- a/model/metrics/faas-metrics.yaml +++ b/model/metrics/faas-metrics.yaml @@ -4,7 +4,7 @@ groups: metric_name: faas.invoke_duration brief: "Measures the duration of the function's logic execution" instrument: histogram - unit: "ms" + unit: "s" attributes: - ref: faas.trigger @@ -13,7 +13,7 @@ groups: metric_name: faas.init_duration brief: "Measures the duration of the function's initialization, such as a cold start" instrument: histogram - unit: "ms" + unit: "s" attributes: - ref: faas.trigger @@ -67,7 +67,7 @@ groups: metric_name: faas.cpu_usage brief: "Distribution of CPU usage per invocation" instrument: histogram - unit: "ms" + unit: "s" attributes: - ref: faas.trigger diff --git a/model/metrics/http.yaml b/model/metrics/http.yaml index 2596a06f08..9e12896e88 100644 --- a/model/metrics/http.yaml +++ b/model/metrics/http.yaml @@ -6,16 +6,22 @@ groups: attributes: - ref: server.address requirement_level: opt_in + note: | + See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). + > **Warning** + > Since this attribute is based on HTTP headers, opting in to it may allow an attacker + > to trigger cardinality limits, degrading the usefulness of the metric. - ref: server.port requirement_level: opt_in - + note: | + See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). + > **Warning** + > Since this attribute is based on HTTP headers, opting in to it may allow an attacker + > to trigger cardinality limits, degrading the usefulness of the metric. - id: metric_attributes.http.client type: attribute_group brief: 'HTTP client attributes' extends: attributes.http.client - attributes: - - ref: url.scheme - requirement_level: required - id: metric.http.server.request.duration type: metric @@ -42,33 +48,19 @@ groups: brief: > Name of the local HTTP server that received the request. note: | - Determined by using the first of the following that applies - - - The [primary server name](/docs/http/http-spans.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. - - Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker - to trigger cardinality limits, degrading the usefulness of the metric. - + See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). + > **Warning** + > Since this attribute is based on HTTP headers, opting in to it may allow an attacker + > to trigger cardinality limits, degrading the usefulness of the metric. - ref: server.port requirement_level: opt_in brief: > Port of the local HTTP server that received the request. note: | - Determined by using the first of the following that applies - - - Port identifier of the [primary server host](/docs/http/http-spans.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 - - Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker - to trigger cardinality limits, degrading the usefulness of the metric. + See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). + > **Warning** + > Since this attribute is based on HTTP headers, opting in to it may allow an attacker + > to trigger cardinality limits, degrading the usefulness of the metric. - id: metric.http.server.request.body.size type: metric diff --git a/model/metrics/jvm-metrics.yaml b/model/metrics/jvm-metrics.yaml index 4306fc239c..ba1f560453 100644 --- a/model/metrics/jvm-metrics.yaml +++ b/model/metrics/jvm-metrics.yaml @@ -26,9 +26,9 @@ groups: 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()). - - id: metric.jvm.memory.usage + - id: metric.jvm.memory.used type: metric - metric_name: jvm.memory.usage + metric_name: jvm.memory.used extends: attributes.jvm.memory brief: "Measure of memory used." instrument: updowncounter @@ -50,9 +50,9 @@ groups: instrument: updowncounter unit: "By" - - id: metric.jvm.memory.usage_after_last_gc + - id: metric.jvm.memory.used_after_last_gc type: metric - metric_name: jvm.memory.usage_after_last_gc + metric_name: jvm.memory.used_after_last_gc extends: attributes.jvm.memory brief: "Measure of memory used, as measured after the most recent garbage collection event on this pool." instrument: updowncounter @@ -90,8 +90,35 @@ groups: instrument: updowncounter unit: "{thread}" attributes: - - ref: thread.daemon + - id: jvm.thread.daemon + type: boolean requirement_level: recommended + brief: "Whether the thread is daemon or not." + - id: jvm.thread.state + requirement_level: recommended + type: + allow_custom_values: false + members: + - id: new + value: 'new' + brief: 'A thread that has not yet started is in this state.' + - id: runnable + value: 'runnable' + brief: 'A thread executing in the Java virtual machine is in this state.' + - id: blocked + value: 'blocked' + brief: 'A thread that is blocked waiting for a monitor lock is in this state.' + - id: waiting + value: 'waiting' + brief: 'A thread that is waiting indefinitely for another thread to perform a particular action is in this state.' + - id: timed_waiting + value: 'timed_waiting' + brief: 'A thread that is waiting for another thread to perform an action for up to a specified waiting time is in this state.' + - id: terminated + value: 'terminated' + brief: 'A thread that has exited is in this state.' + brief: "State of the thread." + examples: ["runnable", "blocked"] - id: metric.jvm.class.loaded type: metric diff --git a/model/metrics/messaging.yaml b/model/metrics/messaging.yaml new file mode 100644 index 0000000000..2d2f2a29ef --- /dev/null +++ b/model/metrics/messaging.yaml @@ -0,0 +1,62 @@ +groups: + - id: metric.messaging.attributes + type: attribute_group + brief: "Common messaging metrics attributes." + extends: messaging.attributes.common + attributes: + - ref: messaging.destination.name + requirement_level: + conditionally_required: if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. + - ref: messaging.destination.template + requirement_level: + conditionally_required: if available. + + # durations + - id: metric.messaging.publish.duration + type: metric + metric_name: messaging.publish.duration + brief: "Measures the duration of publish operation." + instrument: histogram + unit: "s" + extends: metric.messaging.attributes + + - id: metric.messaging.receive.duration + type: metric + metric_name: messaging.receive.duration + brief: "Measures the duration of receive operation." + instrument: histogram + unit: "s" + extends: metric.messaging.attributes + + - id: metric.messaging.deliver.duration + type: metric + metric_name: messaging.deliver.duration + brief: "Measures the duration of deliver operation." + instrument: histogram + unit: "s" + extends: metric.messaging.attributes + + # counters + - id: metric.messaging.publish.messages + type: metric + metric_name: messaging.publish.messages + brief: "Measures the number of published messages." + instrument: counter + unit: "{message}" + extends: metric.messaging.attributes + + - id: metric.messaging.receive.messages + type: metric + metric_name: messaging.receive.messages + brief: "Measures the number of received messages." + instrument: counter + unit: "{message}" + extends: metric.messaging.attributes + + - id: metric.messaging.deliver.messages + type: metric + metric_name: messaging.deliver.messages + brief: "Measures the number of delivered messages." + instrument: counter + unit: "{message}" + extends: metric.messaging.attributes diff --git a/model/metrics/rpc-metrics.yaml b/model/metrics/rpc-metrics.yaml index 43186b0765..ca29cdf194 100644 --- a/model/metrics/rpc-metrics.yaml +++ b/model/metrics/rpc-metrics.yaml @@ -7,6 +7,7 @@ groups: brief: "Describes RPC metric attributes." attributes: - ref: rpc.system + requirement_level: required - ref: rpc.service - ref: rpc.method - ref: network.transport diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml index cfd20979f2..d411115ea8 100644 --- a/model/metrics/system-metrics.yaml +++ b/model/metrics/system-metrics.yaml @@ -61,6 +61,15 @@ groups: - ref: system.cpu.state - ref: system.cpu.logical_number + - id: metric.system.cpu.frequency + type: metric + metric_name: system.cpu.frequency + brief: "Reports the current frequency of the CPU in Hz" + instrument: gauge + unit: "{Hz}" + attributes: + - ref: system.cpu.logical_number + - id: metric.system.cpu.physical.count type: metric metric_name: system.cpu.physical.count @@ -87,8 +96,6 @@ groups: type: allow_custom_values: true members: - - id: total - value: 'total' - id: used value: 'used' - id: free @@ -105,12 +112,24 @@ groups: - id: metric.system.memory.usage type: metric metric_name: system.memory.usage - brief: "" + brief: "Reports memory in use by state." + note: | + The sum over all `system.memory.state` values SHOULD equal the total memory + available on the system, that is `system.memory.limit`. instrument: updowncounter unit: "By" attributes: - ref: system.memory.state + - id: metric.system.memory.limit + type: metric + metric_name: system.memory.limit + brief: "Total memory available in the system." + note: | + Its value SHOULD equal the sum of `system.memory.state` over all states. + instrument: updowncounter + unit: "By" + - id: metric.system.memory.utilization type: metric metric_name: system.memory.utilization @@ -194,22 +213,6 @@ groups: - ref: system.paging.direction # system.disk.* metrics and attribute group - - id: attributes.system.disk - prefix: system.disk - type: attribute_group - brief: "Describes System Disk metric attributes" - attributes: - - id: direction - type: - allow_custom_values: false - members: - - id: read - value: 'read' - - id: write - value: 'write' - brief: "The disk operation direction" - examples: ["read"] - - id: metric.system.disk.io type: metric metric_name: system.disk.io @@ -218,7 +221,7 @@ groups: unit: "By" attributes: - ref: system.device - - ref: system.disk.direction + - ref: disk.io.direction - id: metric.system.disk.operations type: metric @@ -228,7 +231,7 @@ groups: unit: "{operation}" attributes: - ref: system.device - - ref: system.disk.direction + - ref: disk.io.direction - id: metric.system.disk.io_time type: metric @@ -241,7 +244,7 @@ groups: - Linux: Field 13 from [procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats) - Windows: The complement of - ["Disk\% Idle Time"](https://learn.microsoft.com/en-us/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained) + ["Disk\% Idle Time"](https://learn.microsoft.com/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained) performance counter: `uptime * (100 - "Disk\% Idle Time") / 100` attributes: - ref: system.device @@ -259,7 +262,7 @@ groups: - Windows: "Avg. Disk sec/Read" perf counter multiplied by "Disk Reads/sec" perf counter (similar for Writes) attributes: - ref: system.device - - ref: system.disk.direction + - ref: disk.io.direction - id: metric.system.disk.merged type: metric @@ -269,7 +272,7 @@ groups: unit: "{operation}" attributes: - ref: system.device - - ref: system.disk.direction + - ref: disk.io.direction # system.filesystem.* metrics and attribute group - id: attributes.system.filesystem @@ -343,21 +346,13 @@ groups: - ref: system.filesystem.mountpoint # system.network.* metrics and attribute group + + # System-specific network attributes - id: attributes.system.network prefix: system.network type: attribute_group brief: "Describes Network metric attributes" attributes: - - id: direction - type: - allow_custom_values: false - members: - - id: transmit - value: 'transmit' - - id: receive - value: 'receive' - brief: "" - examples: ["transmit"] - id: state type: allow_custom_values: false @@ -399,11 +394,11 @@ groups: 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) + - Windows: [`InDiscards`/`OutDiscards`](https://docs.microsoft.com/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) + from [`GetIfEntry2`](https://docs.microsoft.com/windows/win32/api/netioapi/nf-netioapi-getifentry2) attributes: - ref: system.device - - ref: system.network.direction + - ref: network.io.direction - id: metric.system.network.packets type: metric @@ -413,7 +408,7 @@ groups: unit: "{packet}" attributes: - ref: system.device - - ref: system.network.direction + - ref: network.io.direction - id: metric.system.network.errors type: metric @@ -425,11 +420,11 @@ groups: 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). + - Windows: [`InErrors`/`OutErrors`](https://docs.microsoft.com/windows/win32/api/netioapi/ns-netioapi-mib_if_row2) + from [`GetIfEntry2`](https://docs.microsoft.com/windows/win32/api/netioapi/nf-netioapi-getifentry2). attributes: - ref: system.device - - ref: system.network.direction + - ref: network.io.direction - id: metric.system.network.io type: metric @@ -439,7 +434,7 @@ groups: unit: "By" attributes: - ref: system.device - - ref: system.network.direction + - ref: network.io.direction - id: metric.system.network.connections type: metric diff --git a/model/network.yaml b/model/network.yaml index 2652a2fd1b..7e1ee396f6 100644 --- a/model/network.yaml +++ b/model/network.yaml @@ -3,76 +3,16 @@ groups: prefix: network type: attribute_group brief: > - These attributes may be used for any network related operation. + These attributes may be used for any network related operation. attributes: - - id: transport - type: - allow_custom_values: true - members: - - id: tcp - value: 'tcp' - brief: "TCP" - - id: udp - value: 'udp' - brief: "UDP" - - id: pipe - value: "pipe" - brief: 'Named or anonymous pipe. See note below.' - - id: unix - value: 'unix' - brief: "Unix domain socket" - brief: > - [OSI transport layer](https://osi-model.com/transport-layer/) or - [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). - note: | - The value SHOULD be normalized to lowercase. - - Consider always setting the transport when setting a port number, since - a port number is ambiguous without knowing the transport, for example - different processes could be listening on TCP port 12345 and UDP port 12345. - examples: ['tcp', 'udp'] - - id: type - type: - allow_custom_values: true - members: - - id: ipv4 - value: 'ipv4' - brief: "IPv4" - - id: ipv6 - value: 'ipv6' - brief: "IPv6" - brief: '[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent.' - note: The value SHOULD be normalized to lowercase. - examples: ['ipv4', 'ipv6'] - - id: protocol.name - type: string - brief: '[OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent.' - note: The value SHOULD be normalized to lowercase. - examples: ['amqp', 'http', 'mqtt'] - - id: protocol.version - type: string - brief: Version of the protocol specified in `network.protocol.name`. - examples: '3.1.1' - note: > - `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`. - - id: peer.address - type: string - brief: Peer address of the network connection - IP address or Unix domain socket name. - examples: ['10.1.2.80', '/tmp/my.sock'] - - id: peer.port - type: int - brief: Peer port number of the network connection. - examples: [65123] - - id: local.address - type: string - brief: Local address of the network connection - IP address or Unix domain socket name. - examples: ['10.1.2.80', '/tmp/my.sock'] - - id: local.port - type: int - brief: Local port number of the network connection. - examples: [65123] + - ref: network.transport + - ref: network.type + - ref: network.protocol.name + - ref: network.protocol.version + - ref: network.peer.address + - ref: network.peer.port + - ref: network.local.address + - ref: network.local.port - id: network-connection-and-carrier prefix: network @@ -80,104 +20,9 @@ groups: brief: > These attributes may be used for any network related operation. attributes: - - id: connection.type - type: - allow_custom_values: true - members: - - id: wifi - value: "wifi" - - id: wired - value: "wired" - - id: cell - value: "cell" - - id: unavailable - value: "unavailable" - - id: unknown - value: "unknown" - brief: 'The internet connection type.' - examples: 'wifi' - - id: connection.subtype - type: - allow_custom_values: true - members: - - id: gprs - brief: GPRS - value: "gprs" - - id: edge - brief: EDGE - value: "edge" - - id: umts - brief: UMTS - value: "umts" - - id: cdma - brief: CDMA - value: "cdma" - - id: evdo_0 - brief: EVDO Rel. 0 - value: "evdo_0" - - id: evdo_a - brief: "EVDO Rev. A" - value: "evdo_a" - - id: cdma2000_1xrtt - brief: CDMA2000 1XRTT - value: "cdma2000_1xrtt" - - id: hsdpa - brief: HSDPA - value: "hsdpa" - - id: hsupa - brief: HSUPA - value: "hsupa" - - id: hspa - brief: HSPA - value: "hspa" - - id: iden - brief: IDEN - value: "iden" - - id: evdo_b - brief: "EVDO Rev. B" - value: "evdo_b" - - id: lte - brief: LTE - value: "lte" - - id: ehrpd - brief: EHRPD - value: "ehrpd" - - id: hspap - brief: HSPAP - value: "hspap" - - id: gsm - brief: GSM - value: "gsm" - - id: td_scdma - brief: TD-SCDMA - value: "td_scdma" - - id: iwlan - brief: IWLAN - value: "iwlan" - - id: nr - brief: "5G NR (New Radio)" - value: "nr" - - id: nrnsa - brief: "5G NRNSA (New Radio Non-Standalone)" - value: "nrnsa" - - id: lte_ca - brief: LTE CA - value: "lte_ca" - brief: '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.' - examples: 'LTE' - - id: carrier.name - type: string - brief: "The name of the mobile carrier." - examples: "sprint" - - id: carrier.mcc - type: string - brief: "The mobile carrier country code." - examples: "310" - - id: carrier.mnc - type: string - brief: "The mobile carrier network code." - examples: "001" - - id: carrier.icc - type: string - brief: "The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network." - examples: "DE" + - ref: network.connection.type + - ref: network.connection.subtype + - ref: network.carrier.name + - ref: network.carrier.mcc + - ref: network.carrier.mnc + - ref: network.carrier.icc diff --git a/model/client.yaml b/model/registry/client.yaml similarity index 71% rename from model/client.yaml rename to model/registry/client.yaml index 71d285f7dc..bd214a1708 100644 --- a/model/client.yaml +++ b/model/registry/client.yaml @@ -7,20 +7,22 @@ groups: 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). + protocol / API doesn't 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. attributes: - id: address + stability: stable type: string - brief: Client address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. + brief: "Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name." note: > When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent - the client address behind any intermediaries (e.g. proxies) if it's available. + the client address behind any intermediaries, for example proxies, if it's available. examples: ['client.example.com', '10.1.2.80', '/tmp/my.sock'] - id: port + stability: stable type: int brief: Client port number. examples: [65123] note: > When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent - the client port behind any intermediaries (e.g. proxies) if it's available. + the client port behind any intermediaries, for example proxies, if it's available. diff --git a/model/registry/cloud.yaml b/model/registry/cloud.yaml new file mode 100644 index 0000000000..2c669052e8 --- /dev/null +++ b/model/registry/cloud.yaml @@ -0,0 +1,179 @@ +groups: + - id: registry.cloud + prefix: cloud + type: resource + brief: > + A cloud environment (e.g. GCP, Azure, AWS). + attributes: + - id: provider + type: + allow_custom_values: true + members: + - id: 'alibaba_cloud' + value: 'alibaba_cloud' + brief: 'Alibaba Cloud' + - id: 'aws' + value: 'aws' + brief: 'Amazon Web Services' + - id: 'azure' + value: 'azure' + brief: 'Microsoft Azure' + - id: 'gcp' + value: 'gcp' + brief: 'Google Cloud Platform' + - id: 'heroku' + value: 'heroku' + brief: 'Heroku Platform as a Service' + - id: 'ibm_cloud' + value: 'ibm_cloud' + brief: 'IBM Cloud' + - id: 'tencent_cloud' + value: 'tencent_cloud' + brief: 'Tencent Cloud' + + brief: > + Name of the cloud provider. + - id: account.id + type: string + brief: > + The cloud account ID the resource is assigned to. + examples: ['111111111111', 'opentelemetry'] + - id: region + type: string + brief: > + The geographical region the resource is running. + note: > + 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/global-infrastructure/geographies/), + [Google Cloud regions](https://cloud.google.com/about/locations), + or [Tencent Cloud regions](https://www.tencentcloud.com/document/product/213/6091). + examples: ['us-central1', 'us-east-1'] + - id: resource_id + type: string + brief: > + 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/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) + note: | + 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/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. + examples: + - '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/' + - id: availability_zone + type: string + brief: > + Cloud regions often have multiple, isolated locations known as zones + to increase availability. Availability zone represents the + zone where the resource is running. + note: > + Availability zones are called "zones" on Alibaba Cloud and Google Cloud. + examples: ['us-east-1c'] + - id: platform + type: + allow_custom_values: true + members: + - id: alibaba_cloud_ecs + value: 'alibaba_cloud_ecs' + brief: Alibaba Cloud Elastic Compute Service + - id: alibaba_cloud_fc + value: 'alibaba_cloud_fc' + brief: Alibaba Cloud Function Compute + - id: alibaba_cloud_openshift + value: 'alibaba_cloud_openshift' + brief: Red Hat OpenShift on Alibaba Cloud + - id: aws_ec2 + value: 'aws_ec2' + brief: AWS Elastic Compute Cloud + - id: aws_ecs + value: 'aws_ecs' + brief: AWS Elastic Container Service + - id: aws_eks + value: 'aws_eks' + brief: AWS Elastic Kubernetes Service + - id: aws_lambda + value: 'aws_lambda' + brief: AWS Lambda + - id: aws_elastic_beanstalk + value: 'aws_elastic_beanstalk' + brief: AWS Elastic Beanstalk + - id: aws_app_runner + value: 'aws_app_runner' + brief: AWS App Runner + - id: aws_openshift + value: 'aws_openshift' + brief: Red Hat OpenShift on AWS (ROSA) + - id: azure_vm + value: 'azure_vm' + brief: Azure Virtual Machines + - id: azure_container_instances + value: 'azure_container_instances' + brief: Azure Container Instances + - id: azure_aks + value: 'azure_aks' + brief: Azure Kubernetes Service + - id: azure_functions + value: 'azure_functions' + brief: Azure Functions + - id: azure_app_service + value: 'azure_app_service' + brief: Azure App Service + - id: azure_openshift + value: 'azure_openshift' + brief: Azure Red Hat OpenShift + - id: gcp_bare_metal_solution + value: 'gcp_bare_metal_solution' + brief: Google Bare Metal Solution (BMS) + - id: gcp_compute_engine + value: 'gcp_compute_engine' + brief: Google Cloud Compute Engine (GCE) + - id: gcp_cloud_run + value: 'gcp_cloud_run' + brief: Google Cloud Run + - id: gcp_kubernetes_engine + value: 'gcp_kubernetes_engine' + brief: Google Cloud Kubernetes Engine (GKE) + - id: gcp_cloud_functions + value: 'gcp_cloud_functions' + brief: Google Cloud Functions (GCF) + - id: gcp_app_engine + value: 'gcp_app_engine' + brief: Google Cloud App Engine (GAE) + - id: gcp_openshift + value: 'gcp_openshift' + brief: Red Hat OpenShift on Google Cloud + - id: ibm_cloud_openshift + value: 'ibm_cloud_openshift' + brief: Red Hat OpenShift on IBM Cloud + - id: tencent_cloud_cvm + value: 'tencent_cloud_cvm' + brief: Tencent Cloud Cloud Virtual Machine (CVM) + - id: tencent_cloud_eks + value: 'tencent_cloud_eks' + brief: Tencent Cloud Elastic Kubernetes Service (EKS) + - id: tencent_cloud_scf + value: 'tencent_cloud_scf' + brief: Tencent Cloud Serverless Cloud Function (SCF) + brief: > + The cloud platform in use. + note: > + The prefix of the service SHOULD match the one specified in `cloud.provider`. diff --git a/model/registry/code.yaml b/model/registry/code.yaml new file mode 100644 index 0000000000..d5afceeaed --- /dev/null +++ b/model/registry/code.yaml @@ -0,0 +1,41 @@ +groups: + - id: registry.code + prefix: code + type: span + brief: > + These attributes allow to report this unit of code and therefore to provide more context about the span. + attributes: + - id: function + type: string + brief: > + The method or function name, or equivalent (usually rightmost part of the code unit's name). + examples: serveRequest + - id: namespace + type: string + brief: > + 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. + examples: com.example.MyHttpService + - id: filepath + type: string + brief: > + The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). + examples: /usr/local/MyApplication/content_root/app/index.php + - id: lineno + type: int + brief: > + The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. + examples: 42 + - id: column + type: int + brief: > + The column number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. + examples: 16 + - id: stacktrace + type: string + brief: > + 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. + examples: '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)' diff --git a/model/registry/container.yaml b/model/registry/container.yaml new file mode 100644 index 0000000000..0755d078af --- /dev/null +++ b/model/registry/container.yaml @@ -0,0 +1,86 @@ +groups: + - id: registry.container + prefix: container + type: resource + brief: > + A container instance. + attributes: + - id: name + type: string + brief: > + Container name used by container runtime. + examples: ['opentelemetry-autoconf'] + - id: id + type: string + brief: > + 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. + examples: ['a3bf90e006b2'] + - id: runtime + type: string + brief: > + The container runtime managing this container. + examples: ['docker', 'containerd', 'rkt'] + - id: image.name + type: string + brief: > + Name of the image the container was built on. + examples: ['gcr.io/opentelemetry/operator'] + - id: image.tags + type: string[] + brief: > + Container image tags. An example can be found in + [Docker Image Inspect](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect). + Should be only the `` section of the full name for example + from `registry.example.com/my-org/my-image:`. + examples: ['v1.27.1', '3.5.7-0'] + - id: image.id + type: string + brief: > + Runtime specific image identifier. Usually a hash algorithm followed by a UUID. + note: > + Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker + container inspect [API](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerInspect) + endpoint. + + K8s defines a link to the container registry repository with digest `"imageID": "registry.azurecr.io + /namespace/service/dockerfile@sha256:bdeabd40c3a8a492eaf9e8e44d0ebbb84bac7ee25ac0cf8a7159d25f62555625"`. + + The ID is assinged by the container runtime and can vary in different environments. + Consider using `oci.manifest.digest` if it is important to identify the same + image in different environments/runtimes. + examples: ['sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f'] + - id: image.repo_digests + type: string[] + brief: > + Repo digests of the container image as provided by the container runtime. + note: > + [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and + [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) + report those under the `RepoDigests` field. + examples: + - 'example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb' + - 'internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578' + - id: command + type: string + note: > + If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage. + brief: > + The command used to run the container (i.e. the command name). + examples: [ 'otelcontribcol' ] + - id: command_line + type: string + brief: > + The full command run by the container as a single string representing the full command. [2] + examples: [ 'otelcontribcol --config config.yaml' ] + - id: command_args + type: string[] + brief: > + All the command arguments (including the command/executable itself) run by the container. [2] + examples: [ 'otelcontribcol, --config, config.yaml' ] + - id: labels + type: template[string] + brief: > + Container labels, `` being the label name, the value being the label value. + examples: [ 'container.labels.app=nginx' ] diff --git a/model/registry/db.yaml b/model/registry/db.yaml new file mode 100644 index 0000000000..a17c1046d4 --- /dev/null +++ b/model/registry/db.yaml @@ -0,0 +1,432 @@ +groups: + - id: registry.db + prefix: db + type: attribute_group + brief: > + This document defines the attributes used to describe telemetry in the context of databases. + attributes: + - id: cassandra.coordinator.dc + type: string + brief: > + The data center of the coordinating node for a query. + examples: 'us-west-2' + tag: tech-specific-cassandra + - id: cassandra.coordinator.id + type: string + brief: > + The ID of the coordinating node for a query. + examples: 'be13faa2-8574-4d71-926d-27f16cf8a7af' + tag: tech-specific-cassandra + - id: cassandra.consistency_level + brief: > + 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). + type: + members: + - id: all + value: 'all' + - id: each_quorum + value: 'each_quorum' + - id: quorum + value: 'quorum' + - id: local_quorum + value: 'local_quorum' + - id: one + value: 'one' + - id: two + value: 'two' + - id: three + value: 'three' + - id: local_one + value: 'local_one' + - id: any + value: 'any' + - id: serial + value: 'serial' + - id: local_serial + value: 'local_serial' + tag: tech-specific-cassandra + - id: cassandra.idempotence + type: boolean + brief: > + Whether or not the query is idempotent. + tag: tech-specific-cassandra + - id: cassandra.page_size + type: int + brief: > + The fetch size used for paging, i.e. how many rows will be returned at once. + examples: [5000] + tag: tech-specific-cassandra + - id: cassandra.speculative_execution_count + type: int + brief: > + The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. + examples: [0, 2] + tag: tech-specific-cassandra + - id: cassandra.table + type: string + brief: The name of the primary Cassandra table that the operation is acting upon, including the keyspace name (if applicable). + note: > + 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. + examples: 'mytable' + tag: tech-specific-cassandra + - id: connection_string + type: string + brief: > + The connection string used to connect to the database. + It is recommended to remove embedded credentials. + examples: 'Server=(localdb)\v11.0;Integrated Security=true;' + tag: db-generic + - id: cosmosdb.client_id + type: string + brief: Unique Cosmos client instance id. + examples: '3ba4827d-4422-483f-b59f-85b74211c11d' + tag: tech-specific-cosmosdb + - id: cosmosdb.connection_mode + type: + allow_custom_values: false + members: + - id: gateway + value: 'gateway' + brief: Gateway (HTTP) connections mode + - id: direct + value: 'direct' + brief: Direct connection. + brief: Cosmos client connection mode. + tag: tech-specific-cosmosdb + - id: cosmosdb.container + type: string + brief: Cosmos DB container name. + examples: 'anystring' + tag: tech-specific-cosmosdb + - id: cosmosdb.operation_type + type: + allow_custom_values: true + members: + - id: invalid + value: 'Invalid' + - id: create + value: 'Create' + - id: patch + value: 'Patch' + - id: read + value: 'Read' + - id: read_feed + value: 'ReadFeed' + - id: delete + value: 'Delete' + - id: replace + value: 'Replace' + - id: execute + value: 'Execute' + - id: query + value: 'Query' + - id: head + value: 'Head' + - id: head_feed + value: 'HeadFeed' + - id: upsert + value: 'Upsert' + - id: batch + value: 'Batch' + - id: query_plan + value: 'QueryPlan' + - id: execute_javascript + value: 'ExecuteJavaScript' + brief: CosmosDB Operation Type. + tag: tech-specific-cosmosdb + - id: cosmosdb.request_charge + type: double + brief: RU consumed for that operation + examples: [46.18, 1.0] + tag: tech-specific-cosmosdb + - id: cosmosdb.request_content_length + type: int + brief: Request payload size in bytes + tag: tech-specific-cosmosdb + - id: cosmosdb.status_code + type: int + brief: Cosmos DB status code. + examples: [200, 201] + tag: tech-specific-cosmosdb + - id: cosmosdb.sub_status_code + type: int + brief: Cosmos DB sub status code. + examples: [1000, 1002] + tag: tech-specific-cosmosdb + - id: elasticsearch.cluster.name + type: string + brief: > + Represents the identifier of an Elasticsearch cluster. + examples: ["e9106fc68e3044f0b1475b04bf4ffd5f"] + tag: tech-specific-elasticsearch + - id: elasticsearch.node.name + type: string + brief: > + Represents the human-readable identifier of the node/instance to which a request was routed. + examples: ["instance-0000000001"] + tag: tech-specific-elasticsearch + - id: elasticsearch.path_parts + type: template[string] + brief: > + A dynamic value in the url path. + note: > + Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format + `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD + reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) + in order to map the path part values to their names. + examples: ['db.elasticsearch.path_parts.index=test-index', 'db.elasticsearch.path_parts.doc_id=123'] + tag: tech-specific-elasticsearch + - id: jdbc.driver_classname + type: string + brief: > + 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. + examples: ['org.postgresql.Driver', 'com.microsoft.sqlserver.jdbc.SQLServerDriver'] + tag: tech-specific-jdbc + - id: mongodb.collection + type: string + brief: > + The MongoDB collection being accessed within the database stated in `db.name`. + examples: [ 'customers', 'products' ] + tag: tech-specific-mongodb + - id: mssql.instance_name + type: string + note: > + If setting a `db.mssql.instance_name`, `server.port` is no longer + required (but still recommended if non-standard). + brief: > + The Microsoft SQL Server [instance name](https://docs.microsoft.com/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. + examples: 'MSSQLSERVER' + tag: tech-specific-mssql + - id: name + type: string + brief: > + 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). + note: > + 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). + examples: [ 'customers', 'main' ] + tag: db-generic + - id: operation + type: string + brief: > + 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. + note: > + 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. + examples: ['findAndModify', 'HMSET', 'SELECT'] + tag: db-generic + - id: redis.database_index + type: int + brief: > + 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. + examples: [0, 1, 15] + tag: tech-specific-redis + - id: sql.table + type: string + brief: The name of the primary table that the operation is acting upon, including the database name (if applicable). + note: > + 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. + examples: ['public.users', 'customers'] + tag: tech-specific-sql + - id: statement + type: string + brief: > + The database statement being executed. + examples: ['SELECT * FROM wuser_table', 'SET mykey "WuValue"'] + tag: db-generic + - id: system + brief: An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. + type: + allow_custom_values: true + members: + - id: other_sql + value: 'other_sql' + brief: 'Some other SQL database. Fallback only. See notes.' + - id: mssql + value: 'mssql' + brief: 'Microsoft SQL Server' + - id: mssqlcompact + value: 'mssqlcompact' + brief: 'Microsoft SQL Server Compact' + - id: mysql + value: 'mysql' + brief: 'MySQL' + - id: oracle + value: 'oracle' + brief: 'Oracle Database' + - id: db2 + value: 'db2' + brief: 'IBM Db2' + - id: postgresql + value: 'postgresql' + brief: 'PostgreSQL' + - id: redshift + value: 'redshift' + brief: 'Amazon Redshift' + - id: hive + value: 'hive' + brief: 'Apache Hive' + - id: cloudscape + value: 'cloudscape' + brief: 'Cloudscape' + - id: hsqldb + value: 'hsqldb' + brief: 'HyperSQL DataBase' + - id: progress + value: 'progress' + brief: 'Progress Database' + - id: maxdb + value: 'maxdb' + brief: 'SAP MaxDB' + - id: hanadb + value: 'hanadb' + brief: 'SAP HANA' + - id: ingres + value: 'ingres' + brief: 'Ingres' + - id: firstsql + value: 'firstsql' + brief: 'FirstSQL' + - id: edb + value: 'edb' + brief: 'EnterpriseDB' + - id: cache + value: 'cache' + brief: 'InterSystems Caché' + - id: adabas + value: 'adabas' + brief: 'Adabas (Adaptable Database System)' + - id: firebird + value: 'firebird' + brief: 'Firebird' + - id: derby + value: 'derby' + brief: 'Apache Derby' + - id: filemaker + value: 'filemaker' + brief: 'FileMaker' + - id: informix + value: 'informix' + brief: 'Informix' + - id: instantdb + value: 'instantdb' + brief: 'InstantDB' + - id: interbase + value: 'interbase' + brief: 'InterBase' + - id: mariadb + value: 'mariadb' + brief: 'MariaDB' + - id: netezza + value: 'netezza' + brief: 'Netezza' + - id: pervasive + value: 'pervasive' + brief: 'Pervasive PSQL' + - id: pointbase + value: 'pointbase' + brief: 'PointBase' + - id: sqlite + value: 'sqlite' + brief: 'SQLite' + - id: sybase + value: 'sybase' + brief: 'Sybase' + - id: teradata + value: 'teradata' + brief: 'Teradata' + - id: vertica + value: 'vertica' + brief: 'Vertica' + - id: h2 + value: 'h2' + brief: 'H2' + - id: coldfusion + value: 'coldfusion' + brief: 'ColdFusion IMQ' + - id: cassandra + value: 'cassandra' + brief: 'Apache Cassandra' + - id: hbase + value: 'hbase' + brief: 'Apache HBase' + - id: mongodb + value: 'mongodb' + brief: 'MongoDB' + - id: redis + value: 'redis' + brief: 'Redis' + - id: couchbase + value: 'couchbase' + brief: 'Couchbase' + - id: couchdb + value: 'couchdb' + brief: 'CouchDB' + - id: cosmosdb + value: 'cosmosdb' + brief: 'Microsoft Azure Cosmos DB' + - id: dynamodb + value: 'dynamodb' + brief: 'Amazon DynamoDB' + - id: neo4j + value: 'neo4j' + brief: 'Neo4j' + - id: geode + value: 'geode' + brief: 'Apache Geode' + - id: elasticsearch + value: 'elasticsearch' + brief: 'Elasticsearch' + - id: memcached + value: 'memcached' + brief: 'Memcached' + - id: cockroachdb + value: 'cockroachdb' + brief: 'CockroachDB' + - id: opensearch + value: 'opensearch' + brief: 'OpenSearch' + - id: clickhouse + value: 'clickhouse' + brief: 'ClickHouse' + - id: spanner + value: 'spanner' + brief: 'Cloud Spanner' + - id: trino + value: 'trino' + brief: 'Trino' + tag: db-generic + - id: user + type: string + brief: > + Username for accessing the database. + examples: ['readonly_user', 'reporting_user'] + tag: db-generic + - id: instance.id + tag: db-generic + type: string + brief: > + An identifier (address, unique name, or any other identifier) of the database instance that is executing queries or mutations on the current connection. + This is useful in cases where the database is running in a clustered environment and the instrumentation is able to record the node executing the query. + The client may obtain this value in databases like MySQL using queries like `select @@hostname`. + examples: 'mysql-e26b99z.example.com' diff --git a/model/registry/deprecated/http.yaml b/model/registry/deprecated/http.yaml index f904126c67..9150328629 100644 --- a/model/registry/deprecated/http.yaml +++ b/model/registry/deprecated/http.yaml @@ -31,11 +31,41 @@ groups: examples: ['/search?q=OpenTelemetry#SemConv'] - id: request_content_length type: int - brief: 'Deprecated, use `http.request.body.size` instead.' + brief: 'Deprecated, use `http.request.header.content-length` instead.' stability: deprecated examples: 3495 - id: response_content_length type: int - brief: 'Deprecated, use `http.response.body.size` instead.' + brief: 'Deprecated, use `http.response.header.content-length` instead.' stability: deprecated examples: 3495 + - id: flavor + type: + allow_custom_values: true + members: + - id: http_1_0 + value: '1.0' + brief: 'HTTP/1.0' + - id: http_1_1 + value: '1.1' + brief: 'HTTP/1.1' + - id: http_2_0 + value: '2.0' + brief: 'HTTP/2' + - id: http_3_0 + value: '3.0' + brief: 'HTTP/3' + - id: spdy + value: 'SPDY' + brief: 'SPDY protocol.' + - id: quic + value: 'QUIC' + brief: 'QUIC protocol.' + brief: 'Deprecated, use `network.protocol.name` instead.' + stability: deprecated + - id: user_agent + type: string + brief: 'Deprecated, use `user_agent.original` instead.' + examples: ['CERN-LineMode/2.15 libwww/2.17b3', + 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1'] + stability: deprecated diff --git a/model/deprecated/network.yaml b/model/registry/deprecated/network.yaml similarity index 100% rename from model/deprecated/network.yaml rename to model/registry/deprecated/network.yaml diff --git a/model/destination.yaml b/model/registry/destination.yaml similarity index 63% rename from model/destination.yaml rename to model/registry/destination.yaml index bad57d5a22..595a1c67f9 100644 --- a/model/destination.yaml +++ b/model/registry/destination.yaml @@ -2,19 +2,20 @@ groups: - id: destination prefix: destination type: attribute_group - brief: These attributes may be used to describe the receiver of a network exchange/packet. These should be used + brief: > + These attributes may be used to describe the 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. + "user-facing" surface of the protocol / API doesn't expose a clear notion of client and server. attributes: - id: address type: string - brief: Destination address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. + brief: "Destination address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name." note: > When observed from the source side, and when communicating through an intermediary, `destination.address` SHOULD represent - the destination address behind any intermediaries (e.g. proxies) if it's available. + the destination address behind any intermediaries, for example proxies, if it's available. examples: ['destination.example.com', '10.1.2.80', '/tmp/my.sock'] - id: port type: int diff --git a/model/registry/device.yaml b/model/registry/device.yaml new file mode 100644 index 0000000000..6eaf8e3b5e --- /dev/null +++ b/model/registry/device.yaml @@ -0,0 +1,46 @@ +groups: + - id: registry.device + prefix: device + type: resource + brief: > + Describes device attributes. + attributes: + - id: id + type: string + brief: > + A unique identifier representing the device + note: > + 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. + examples: ['2ab2916d-a51f-4ac8-80ee-45ac31a28092'] + - id: manufacturer + type: string + brief: > + The name of the device manufacturer + note: > + The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). + iOS apps SHOULD hardcode the value `Apple`. + examples: ['Apple', 'Samsung'] + - id: model.identifier + type: string + brief: > + The model identifier for the device + note: > + 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. + examples: ['iPhone3,4', 'SM-G920F'] + - id: model.name + type: string + brief: > + The marketing name for the device model + note: > + It's recommended this value represents a human-readable version of the + device model rather than a machine-readable alternative. + examples: ['iPhone 6s Plus', 'Samsung Galaxy S6'] diff --git a/model/registry/disk.yaml b/model/registry/disk.yaml new file mode 100644 index 0000000000..90d6fb27d2 --- /dev/null +++ b/model/registry/disk.yaml @@ -0,0 +1,17 @@ +groups: + - id: registry.disk + prefix: disk + type: attribute_group + brief: > + These attributes may be used for any disk related operation. + attributes: + - id: io.direction + type: + allow_custom_values: false + members: + - id: read + value: 'read' + - id: write + value: 'write' + brief: "The disk IO operation direction." + examples: ["read"] diff --git a/model/error.yaml b/model/registry/error.yaml similarity index 58% rename from model/error.yaml rename to model/registry/error.yaml index 01b7b05f5f..683012e361 100644 --- a/model/error.yaml +++ b/model/registry/error.yaml @@ -1,31 +1,35 @@ groups: - - id: error + - id: registry.error type: attribute_group prefix: error brief: > - This document defines the shared attributes used to - report an error. + This document defines the shared attributes used to report an error. attributes: - id: type - brief: 'Describes a class of error the operation ended with.' + stability: stable + brief: > + Describes a class of error the operation ended with. type: allow_custom_values: true members: - id: other value: "_OTHER" - brief: 'A fallback error value to be used when the instrumentation does not define a custom value for it.' + brief: > + A fallback error value to be used when the instrumentation doesn't define a custom value. examples: ['timeout', 'java.net.UnknownHostException', 'server_certificate_invalid', '500'] note: | The `error.type` SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. - The cardinality of `error.type` within one instrumentation library SHOULD be low, but - telemetry consumers that aggregate data from multiple instrumentation libraries and applications - should be prepared for `error.type` to have high cardinality at query time, when no + The cardinality of `error.type` within one instrumentation library SHOULD be low. + Telemetry consumers that aggregate data from multiple instrumentation libraries and applications + should be prepared for `error.type` to have high cardinality at query time when no additional filters are applied. If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), - it's RECOMMENDED to use a domain-specific attribute and also set `error.type` to capture - all errors, regardless of whether they are defined within the domain-specific set or not. + it's RECOMMENDED to: + + * Use a domain-specific attribute + * Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. diff --git a/model/registry/host.yaml b/model/registry/host.yaml new file mode 100644 index 0000000000..3deb5f5707 --- /dev/null +++ b/model/registry/host.yaml @@ -0,0 +1,122 @@ +groups: + - id: registry.host + prefix: host + type: resource + brief: > + A host is defined as a computing instance. For example, physical servers, virtual machines, switches or disk array. + attributes: + - id: id + type: string + brief: > + 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. + examples: ['fdbf79e8af94cb7f9e8df36789187052'] + - id: name + type: string + brief: > + 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. + examples: ['opentelemetry-test'] + - id: type + type: string + brief: > + Type of host. For Cloud, this must be the machine type. + examples: ['n1-standard-1'] + - id: arch + type: + allow_custom_values: true + members: + - id: amd64 + value: 'amd64' + brief: "AMD64" + - id: arm32 + value: 'arm32' + brief: "ARM32" + - id: arm64 + value: 'arm64' + brief: "ARM64" + - id: ia64 + value: 'ia64' + brief: "Itanium" + - id: ppc32 + value: 'ppc32' + brief: "32-bit PowerPC" + - id: ppc64 + value: 'ppc64' + brief: "64-bit PowerPC" + - id: s390x + value: 's390x' + brief: "IBM z/Architecture" + - id: x86 + value: 'x86' + brief: "32-bit x86" + brief: > + The CPU architecture the host system is running on. + - id: image.name + type: string + brief: > + Name of the VM image or OS install the host was instantiated from. + examples: ['infra-ami-eks-worker-node-7d4ec78312', 'CentOS-8-x86_64-1905'] + - id: image.id + type: string + brief: > + VM image ID or host OS image ID. For Cloud, this value is from the provider. + examples: ['ami-07b06b442921831e5'] + - id: image.version + type: string + brief: > + The version string of the VM image or host OS as defined in + [Version Attributes](/docs/resource/README.md#version-attributes). + examples: ['0.1'] + - id: ip + type: string[] + brief: > + Available IP addresses of the host, excluding loopback interfaces. + note: > + IPv4 Addresses MUST be specified in dotted-quad notation. IPv6 addresses + MUST be specified in the [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952.html) format. + examples: ["192.168.1.140", "fe80::abc2:4a28:737a:609e"] + - id: mac + type: string[] + brief: > + Available MAC addresses of the host, excluding loopback interfaces. + note: > + MAC Addresses MUST be represented in [IEEE RA hexadecimal form](https://standards.ieee.org/wp-content/uploads/import/documents/tutorials/eui.pdf): + as hyphen-separated octets in uppercase hexadecimal form from most to least significant. + examples: ['AC-DE-48-23-45-67', 'AC-DE-48-23-45-67-01-9F'] + - id: cpu.vendor.id + type: string + brief: > + Processor manufacturer identifier. A maximum 12-character string. + note: > + [CPUID](https://wiki.osdev.org/CPUID) command returns the vendor ID string in EBX, EDX and ECX registers. + Writing these to memory in this order results in a 12-character string. + examples: [ 'GenuineIntel' ] + - id: cpu.family + type: string + brief: > + Family or generation of the CPU. + examples: [ '6', 'PA-RISC 1.1e' ] + - id: cpu.model.id + type: string + brief: > + Model identifier. It provides more granular information about the CPU, distinguishing it from + other CPUs within the same family. + examples: [ '6', '9000/778/B180L' ] + - id: cpu.model.name + type: string + brief: > + Model designation of the processor. + examples: [ '11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz' ] + - id: cpu.stepping + type: int + brief: > + Stepping or core revisions. + examples: [ 1 ] + - id: cpu.cache.l2.size + type: int + brief: > + The amount of level 2 memory cache available to the processor (in Bytes). + examples: [ 12288000 ] diff --git a/model/registry/http.yaml b/model/registry/http.yaml index 1d6f0192fa..2cb8e8b894 100644 --- a/model/registry/http.yaml +++ b/model/registry/http.yaml @@ -11,10 +11,12 @@ groups: 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. examples: 3495 + stability: experimental # this should not be marked stable with other HTTP attributes - id: request.header + stability: stable type: template[string[]] brief: > - HTTP request headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. + HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. note: > Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information. @@ -25,8 +27,9 @@ groups: 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. - examples: ['http.request.header.content_type=["application/json"]', 'http.request.header.x_forwarded_for=["1.2.3.4", "1.2.3.5"]'] + examples: ['http.request.header.content-type=["application/json"]', 'http.request.header.x-forwarded-for=["1.2.3.4", "1.2.3.5"]'] - id: request.method + stability: stable type: allow_custom_values: true members: @@ -78,10 +81,12 @@ groups: Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. - id: request.method_original + stability: stable type: string brief: Original HTTP method sent by the client in the request line. examples: ["GeT", "ACL", "foo"] - - id: resend_count + - id: request.resend_count + stability: stable type: int brief: > The ordinal number of request resending attempt (for any reason, including redirects). @@ -97,10 +102,12 @@ groups: 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. examples: 3495 + stability: experimental # this should not be marked stable with other HTTP attributes - id: response.header + stability: stable type: template[string[]] brief: > - HTTP response headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. + HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. note: > Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. @@ -110,15 +117,17 @@ groups: 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. - examples: ['http.response.header.content_type=["application/json"]', 'http.response.header.my_custom_header=["abc", "def"]'] + examples: ['http.response.header.content-type=["application/json"]', 'http.response.header.my-custom-header=["abc", "def"]'] - id: response.status_code + stability: stable type: int brief: '[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).' examples: [200] - id: route + stability: stable type: string brief: > - The matched route (path template in the format used by the respective server framework). See note below + The matched route, that is, the path template in the format used by the respective server framework. examples: ['/users/:userID?', '{controller}/{action}/{id?}'] note: > 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. diff --git a/model/registry/k8s.yaml b/model/registry/k8s.yaml new file mode 100644 index 0000000000..9c453fb691 --- /dev/null +++ b/model/registry/k8s.yaml @@ -0,0 +1,145 @@ +groups: + - id: registry.k8s + prefix: k8s + type: resource + brief: > + Kubernetes resource attributes. + attributes: + - id: cluster.name + type: string + brief: > + The name of the cluster. + examples: ['opentelemetry-cluster'] + - id: cluster.uid + type: string + brief: > + A pseudo-ID for the cluster, set to the UID of the `kube-system` + namespace. + note: | + K8s doesn't 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. + examples: ['218fc5a9-a5f1-4b54-aa05-46717d0ab26d'] + - id: node.name + type: string + brief: > + The name of the Node. + examples: ['node-1'] + - id: node.uid + type: string + brief: > + The UID of the Node. + examples: ['1eb3a0c6-0477-4080-a9cb-0cb7db65c6a2'] + - id: namespace.name + type: string + brief: > + The name of the namespace that the pod is running in. + examples: ['default'] + - id: pod.uid + type: string + brief: > + The UID of the Pod. + examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] + - id: pod.name + type: string + brief: > + The name of the Pod. + examples: ['opentelemetry-pod-autoconf'] + - id: pod.labels + type: template[string] + brief: > + The labels placed on the Pod, the `` being the label name, the value being the label value. + examples: ['k8s.pod.labels.app=my-app', 'k8s.pod.labels.mycompany.io/arch=x64', 'k8s.pod.labels.data='] + - id: container.name + type: string + brief: > + The name of the Container from Pod specification, must be unique + within a Pod. Container runtime usually uses different globally unique + name (`container.name`). + examples: ['redis'] + - id: container.restart_count + type: int + brief: > + Number of times the container was restarted. This attribute can be + used to identify a particular container (running or stopped) within a + container spec. + examples: [0, 2] + - id: replicaset.uid + type: string + brief: > + The UID of the ReplicaSet. + examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] + - id: replicaset.name + type: string + brief: > + The name of the ReplicaSet. + examples: ['opentelemetry'] + - id: deployment.uid + type: string + brief: > + The UID of the Deployment. + examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] + - id: deployment.name + type: string + brief: > + The name of the Deployment. + examples: ['opentelemetry'] + - id: statefulset.uid + type: string + brief: > + The UID of the StatefulSet. + examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] + - id: statefulset.name + type: string + brief: > + The name of the StatefulSet. + examples: ['opentelemetry'] + - id: daemonset.uid + type: string + brief: > + The UID of the DaemonSet. + examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] + - id: daemonset.name + type: string + brief: > + The name of the DaemonSet. + examples: ['opentelemetry'] + - id: job.uid + type: string + brief: > + The UID of the Job. + examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] + - id: job.name + type: string + brief: > + The name of the Job. + examples: ['opentelemetry'] + - id: cronjob.uid + type: string + brief: > + The UID of the CronJob. + examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] + - id: cronjob.name + type: string + brief: > + The name of the CronJob. + examples: ['opentelemetry'] diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml new file mode 100644 index 0000000000..c7ba8fd457 --- /dev/null +++ b/model/registry/messaging.yaml @@ -0,0 +1,245 @@ +groups: + - id: registry.messaging + prefix: messaging + type: attribute_group + brief: 'Attributes describing telemetry around messaging systems and messaging activities.' + attributes: + - id: batch.message_count + type: int + brief: The number of messages sent, received, or processed in the scope of the batching operation. + note: > + 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. + examples: [0, 1, 2] + - id: client_id + type: string + brief: > + A unique identifier for the client that consumes or produces a message. + examples: ['client-5', 'myhost@8742@s8083jm'] + - id: destination.name + type: string + brief: 'The message destination name' + note: | + Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If + the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker. + examples: ['MyQueue', 'MyTopic'] + - id: destination.template + type: string + brief: Low cardinality representation of the messaging destination name + note: > + 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. + examples: ['/customers/{customerId}'] + - id: destination.anonymous + type: boolean + brief: 'A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name).' + - id: destination.temporary + type: boolean + brief: 'A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed.' + - id: destination_publish.anonymous + type: boolean + brief: 'A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name).' + - id: destination_publish.name + type: string + brief: 'The name of the original destination the message was published to' + note: | + The name SHOULD uniquely identify a specific queue, topic, or other entity within the broker. If + the broker doesn't have such notion, the original destination name SHOULD uniquely identify the broker. + examples: ['MyQueue', 'MyTopic'] + - id: kafka.consumer.group + type: string + brief: > + Name of the Kafka Consumer Group that is handling the message. + Only applies to consumers, not producers. + examples: 'my-group' + - id: kafka.destination.partition + type: int + brief: > + Partition the message is sent to. + examples: 2 + - id: kafka.message.key + type: string + brief: > + 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. + note: > + 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. + examples: 'myKey' + - id: kafka.message.offset + type: int + brief: > + The offset of a record in the corresponding Kafka partition. + examples: 42 + - id: kafka.message.tombstone + type: boolean + brief: 'A boolean that is true if the message is a tombstone.' + - id: message.conversation_id + type: string + brief: > + The conversation ID identifying the conversation to which the message belongs, + represented as a string. Sometimes called "Correlation ID". + examples: 'MyConversationId' + - id: message.envelope.size + type: int + brief: > + The size of the message body and metadata in bytes. + note: | + This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed + size should be used. + examples: 2738 + - id: message.id + type: string + brief: 'A value used by the messaging system as an identifier for the message, represented as a string.' + examples: '452a7c7c7c7048c2f887f61572b18fc2' + - id: message.body.size + type: int + brief: > + The size of the message body in bytes. + note: | + This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed + body size should be used. + examples: 1439 + - id: operation + type: + allow_custom_values: true + members: + - id: publish + value: "publish" + brief: > + One or more messages are provided for publishing to an intermediary. + If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. + - id: create + value: "create" + brief: > + A message is created. + "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. + - id: receive + value: "receive" + brief: > + One or more messages are requested by a consumer. + This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. + - id: deliver + value: "deliver" + brief: > + One or more messages are passed to a consumer. + This operation refers to push-based scenarios, where consumer register callbacks which get called by messaging SDKs. + brief: > + A string identifying the kind of messaging operation. + note: If a custom value is used, it MUST be of low cardinality. + - id: rabbitmq.destination.routing_key + type: string + brief: > + RabbitMQ message routing key. + examples: 'myKey' + - id: rocketmq.client_group + type: string + brief: > + Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. + examples: 'myConsumerGroup' + - id: rocketmq.consumption_model + type: + allow_custom_values: false + members: + - id: clustering + value: 'clustering' + brief: 'Clustering consumption model' + - id: broadcasting + value: 'broadcasting' + brief: 'Broadcasting consumption model' + brief: > + Model of message consumption. This only applies to consumer spans. + - id: rocketmq.message.delay_time_level + type: int + brief: > + The delay time level for delay message, which determines the message delay time. + examples: 3 + - id: rocketmq.message.delivery_timestamp + type: int + brief: > + The timestamp in milliseconds that the delay message is expected to be delivered to consumer. + examples: 1665987217045 + - id: rocketmq.message.group + type: string + brief: > + 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. + examples: 'myMessageGroup' + - id: rocketmq.message.keys + type: string[] + brief: > + Key(s) of message, another way to mark message besides message id. + examples: ['keyA', 'keyB'] + - id: rocketmq.message.tag + type: string + brief: > + The secondary classifier of message besides topic. + examples: tagA + - id: rocketmq.message.type + type: + allow_custom_values: false + members: + - id: normal + value: 'normal' + brief: "Normal message" + - id: fifo + value: 'fifo' + brief: 'FIFO message' + - id: delay + value: 'delay' + brief: 'Delay message' + - id: transaction + value: 'transaction' + brief: 'Transaction message' + brief: > + Type of message. + - id: rocketmq.namespace + type: string + brief: > + Namespace of RocketMQ resources, resources in different namespaces are individual. + examples: 'myNamespace' + - id: gcp_pubsub.message.ordering_key + type: string + brief: > + The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. + examples: 'ordering_key' + - id: system + brief: > + An identifier for the messaging system being used. See below for a list of well-known identifiers. + type: + allow_custom_values: true + members: + - id: activemq + value: 'activemq' + brief: 'Apache ActiveMQ' + - id: aws_sqs + value: 'aws_sqs' + brief: 'Amazon Simple Queue Service (SQS)' + - id: azure_eventgrid + value: 'azure_eventgrid' + brief: 'Azure Event Grid' + - id: azure_eventhubs + value: 'azure_eventhubs' + brief: 'Azure Event Hubs' + - id: azure_servicebus + value: 'azure_servicebus' + brief: 'Azure Service Bus' + - id: gcp_pubsub + value: 'gcp_pubsub' + brief: 'Google Cloud Pub/Sub' + - id: jms + value: 'jms' + brief: 'Java Message Service' + - id: kafka + value: 'kafka' + brief: 'Apache Kafka' + - id: rabbitmq + value: 'rabbitmq' + brief: 'RabbitMQ' + - id: rocketmq + value: 'rocketmq' + brief: 'Apache RocketMQ' diff --git a/model/registry/network.yaml b/model/registry/network.yaml new file mode 100644 index 0000000000..7715506bcc --- /dev/null +++ b/model/registry/network.yaml @@ -0,0 +1,194 @@ +groups: + - id: registry.network + prefix: network + type: attribute_group + brief: > + These attributes may be used for any network related operation. + attributes: + - id: carrier.icc + type: string + brief: "The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network." + examples: "DE" + - id: carrier.mcc + type: string + brief: "The mobile carrier country code." + examples: "310" + - id: carrier.mnc + type: string + brief: "The mobile carrier network code." + examples: "001" + - id: carrier.name + type: string + brief: "The name of the mobile carrier." + examples: "sprint" + - id: connection.subtype + type: + allow_custom_values: true + members: + - id: gprs + brief: GPRS + value: "gprs" + - id: edge + brief: EDGE + value: "edge" + - id: umts + brief: UMTS + value: "umts" + - id: cdma + brief: CDMA + value: "cdma" + - id: evdo_0 + brief: EVDO Rel. 0 + value: "evdo_0" + - id: evdo_a + brief: "EVDO Rev. A" + value: "evdo_a" + - id: cdma2000_1xrtt + brief: CDMA2000 1XRTT + value: "cdma2000_1xrtt" + - id: hsdpa + brief: HSDPA + value: "hsdpa" + - id: hsupa + brief: HSUPA + value: "hsupa" + - id: hspa + brief: HSPA + value: "hspa" + - id: iden + brief: IDEN + value: "iden" + - id: evdo_b + brief: "EVDO Rev. B" + value: "evdo_b" + - id: lte + brief: LTE + value: "lte" + - id: ehrpd + brief: EHRPD + value: "ehrpd" + - id: hspap + brief: HSPAP + value: "hspap" + - id: gsm + brief: GSM + value: "gsm" + - id: td_scdma + brief: TD-SCDMA + value: "td_scdma" + - id: iwlan + brief: IWLAN + value: "iwlan" + - id: nr + brief: "5G NR (New Radio)" + value: "nr" + - id: nrnsa + brief: "5G NRNSA (New Radio Non-Standalone)" + value: "nrnsa" + - id: lte_ca + brief: LTE CA + value: "lte_ca" + brief: '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.' + examples: 'LTE' + - id: connection.type + type: + allow_custom_values: true + members: + - id: wifi + value: "wifi" + - id: wired + value: "wired" + - id: cell + value: "cell" + - id: unavailable + value: "unavailable" + - id: unknown + value: "unknown" + brief: 'The internet connection type.' + examples: 'wifi' + - id: local.address + stability: stable + type: string + brief: Local address of the network connection - IP address or Unix domain socket name. + examples: ['10.1.2.80', '/tmp/my.sock'] + - id: local.port + stability: stable + type: int + brief: Local port number of the network connection. + examples: [65123] + - id: peer.address + stability: stable + type: string + brief: Peer address of the network connection - IP address or Unix domain socket name. + examples: ['10.1.2.80', '/tmp/my.sock'] + - id: peer.port + stability: stable + type: int + brief: Peer port number of the network connection. + examples: [65123] + - id: protocol.name + stability: stable + type: string + brief: '[OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent.' + note: The value SHOULD be normalized to lowercase. + examples: ['amqp', 'http', 'mqtt'] + - id: protocol.version + stability: stable + type: string + brief: Version of the protocol specified in `network.protocol.name`. + examples: '3.1.1' + note: > + `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 has a version + of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + - id: transport + stability: stable + type: + allow_custom_values: true + members: + - id: tcp + value: 'tcp' + brief: "TCP" + - id: udp + value: 'udp' + brief: "UDP" + - id: pipe + value: "pipe" + brief: 'Named or anonymous pipe.' + - id: unix + value: 'unix' + brief: "Unix domain socket" + brief: > + [OSI transport layer](https://osi-model.com/transport-layer/) or + [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). + note: | + The value SHOULD be normalized to lowercase. + + Consider always setting the transport when setting a port number, since + a port number is ambiguous without knowing the transport. For example + different processes could be listening on TCP port 12345 and UDP port 12345. + examples: ['tcp', 'udp'] + - id: type + stability: stable + type: + allow_custom_values: true + members: + - id: ipv4 + value: 'ipv4' + brief: "IPv4" + - id: ipv6 + value: 'ipv6' + brief: "IPv6" + brief: '[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent.' + note: The value SHOULD be normalized to lowercase. + examples: ['ipv4', 'ipv6'] + - id: io.direction + type: + allow_custom_values: false + members: + - id: transmit + value: 'transmit' + - id: receive + value: 'receive' + brief: "The network IO operation direction." + examples: ["transmit"] diff --git a/model/resource/oci.yaml b/model/registry/oci.yaml similarity index 96% rename from model/resource/oci.yaml rename to model/registry/oci.yaml index fc1ff2ebb3..45e2838796 100644 --- a/model/resource/oci.yaml +++ b/model/registry/oci.yaml @@ -1,5 +1,5 @@ groups: - - id: oci.manifest + - id: registry.oci.manifest prefix: oci.manifest type: resource brief: > diff --git a/model/registry/os.yaml b/model/registry/os.yaml new file mode 100644 index 0000000000..5b699b1faf --- /dev/null +++ b/model/registry/os.yaml @@ -0,0 +1,69 @@ +groups: + - id: registry.os + prefix: os + type: resource + brief: > + The operating system (OS) on which the process represented by this resource is running. + note: > + 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. + attributes: + - id: type + type: + allow_custom_values: true + members: + - id: windows + value: 'windows' + brief: "Microsoft Windows" + - id: linux + value: 'linux' + brief: "Linux" + - id: darwin + value: 'darwin' + brief: "Apple Darwin" + - id: freebsd + value: 'freebsd' + brief: "FreeBSD" + - id: netbsd + value: 'netbsd' + brief: "NetBSD" + - id: openbsd + value: 'openbsd' + brief: "OpenBSD" + - id: dragonflybsd + value: 'dragonflybsd' + brief: "DragonFly BSD" + - id: hpux + value: 'hpux' + brief: "HP-UX (Hewlett Packard Unix)" + - id: aix + value: 'aix' + brief: "AIX (Advanced Interactive eXecutive)" + - id: solaris + value: 'solaris' + brief: "SunOS, Oracle Solaris" + - id: z_os + value: 'z_os' + brief: "IBM z/OS" + brief: > + The operating system type. + - id: description + type: string + brief: > + Human readable (not intended to be parsed) OS version information, + like e.g. reported by `ver` or `lsb_release -a` commands. + examples: ['Microsoft Windows [Version 10.0.18363.778]', 'Ubuntu 18.04.1 LTS'] + - id: name + type: string + brief: 'Human readable operating system name.' + examples: ['iOS', 'Android', 'Ubuntu'] + - id: version + type: string + brief: > + The version string of the operating system as defined in + [Version Attributes](/docs/resource/README.md#version-attributes). + examples: ['14.2.1', '18.04.1'] + - id: build_id + type: string + brief: 'Unique identifier for a particular build or compilation of the operating system.' + examples: ['TQ3C.230805.001.B2', '20E247', '22621'] diff --git a/model/registry/process.yaml b/model/registry/process.yaml new file mode 100644 index 0000000000..dd26c09b77 --- /dev/null +++ b/model/registry/process.yaml @@ -0,0 +1,78 @@ +groups: + - id: registry.process + prefix: process + type: resource + brief: > + An operating system process. + attributes: + - id: pid + type: int + brief: > + Process identifier (PID). + examples: [1234] + - id: parent_pid + type: int + brief: > + Parent Process identifier (PID). + examples: [111] + - id: executable.name + type: string + brief: > + 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`. + examples: ['otelcol'] + - id: executable.path + type: string + brief: > + 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`. + examples: ['/usr/bin/cmd/otelcol'] + - id: command + type: string + brief: > + 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`. + examples: ['cmd/otelcol'] + - id: command_line + type: string + brief: > + 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. + examples: ['C:\cmd\otecol --config="my directory\config.yaml"'] + - id: command_args + type: string[] + brief: > + 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`. + examples: ['cmd/otecol', '--config=config.yaml'] + - id: owner + type: string + brief: > + The username of the user that owns the process. + examples: 'root' + - id: runtime.name + type: string + brief: > + The name of the runtime of this process. For compiled native binaries, + this SHOULD be the name of the compiler. + examples: ['OpenJDK Runtime Environment'] + - id: runtime.version + type: string + brief: > + The version of the runtime of this process, as returned by the runtime + without modification. + examples: '14.0.2' + - id: runtime.description + type: string + brief: > + An additional description about the runtime of the process, for example + a specific vendor customization of the runtime environment. + examples: 'Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0' diff --git a/model/registry/rpc.yaml b/model/registry/rpc.yaml new file mode 100644 index 0000000000..64f1f9a667 --- /dev/null +++ b/model/registry/rpc.yaml @@ -0,0 +1,190 @@ +groups: + - id: registry.rpc + prefix: rpc + type: attribute_group + brief: 'This document defines attributes for remote procedure calls.' + attributes: + - id: connect_rpc.error_code + type: + members: + - id: cancelled + value: cancelled + - id: unknown + value: unknown + - id: invalid_argument + value: invalid_argument + - id: deadline_exceeded + value: deadline_exceeded + - id: not_found + value: not_found + - id: already_exists + value: already_exists + - id: permission_denied + value: permission_denied + - id: resource_exhausted + value: resource_exhausted + - id: failed_precondition + value: failed_precondition + - id: aborted + value: aborted + - id: out_of_range + value: out_of_range + - id: unimplemented + value: unimplemented + - id: internal + value: internal + - id: unavailable + value: unavailable + - id: data_loss + value: data_loss + - id: unauthenticated + value: unauthenticated + brief: "The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values." + - id: connect_rpc.request.metadata + type: template[string[]] + brief: > + Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + note: > + Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. + Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + examples: ['rpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]'] + - id: connect_rpc.response.metadata + type: template[string[]] + brief: > + Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. + note: > + Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. + Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + examples: ['rpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]'] + - id: grpc.status_code + type: + members: + - id: ok + brief: OK + value: 0 + - id: cancelled + brief: CANCELLED + value: 1 + - id: unknown + brief: UNKNOWN + value: 2 + - id: invalid_argument + brief: INVALID_ARGUMENT + value: 3 + - id: deadline_exceeded + brief: DEADLINE_EXCEEDED + value: 4 + - id: not_found + brief: NOT_FOUND + value: 5 + - id: already_exists + brief: ALREADY_EXISTS + value: 6 + - id: permission_denied + brief: PERMISSION_DENIED + value: 7 + - id: resource_exhausted + brief: RESOURCE_EXHAUSTED + value: 8 + - id: failed_precondition + brief: FAILED_PRECONDITION + value: 9 + - id: aborted + brief: ABORTED + value: 10 + - id: out_of_range + brief: OUT_OF_RANGE + value: 11 + - id: unimplemented + brief: UNIMPLEMENTED + value: 12 + - id: internal + brief: INTERNAL + value: 13 + - id: unavailable + brief: UNAVAILABLE + value: 14 + - id: data_loss + brief: DATA_LOSS + value: 15 + - id: unauthenticated + brief: UNAUTHENTICATED + value: 16 + brief: "The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request." + - id: grpc.request.metadata + type: template[string[]] + brief: > + gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + note: > + Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. + Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + examples: ['rpc.grpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]'] + - id: grpc.response.metadata + type: template[string[]] + brief: > + gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. + note: > + Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. + Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + examples: ['rpc.grpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]'] + - id: jsonrpc.error_code + type: int + brief: "`error.code` property of response if it is an error response." + examples: [-32700, 100] + - id: jsonrpc.error_message + type: string + brief: "`error.message` property of response if it is an error response." + examples: ['Parse error', 'User already exists'] + - id: jsonrpc.request_id + type: string + brief: > + `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. + examples: ['10', 'request-7', ''] + - id: jsonrpc.version + type: string + brief: "Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted." + examples: ['2.0', '1.0'] + - id: method + type: string + brief: 'The name of the (logical) method being called, must be equal to the $method part in the span name.' + note: > + 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). + examples: "exampleMethod" + - id: service + type: string + brief: 'The full (logical) name of the service being called, including its package name, if applicable.' + note: > + 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). + examples: "myservice.EchoService" + - id: system + brief: 'A string identifying the remoting system. See below for a list of well-known identifiers.' + type: + allow_custom_values: true + members: + - id: grpc + value: 'grpc' + brief: 'gRPC' + - id: java_rmi + value: 'java_rmi' + brief: 'Java RMI' + - id: dotnet_wcf + value: 'dotnet_wcf' + brief: '.NET WCF' + - id: apache_dubbo + value: 'apache_dubbo' + brief: 'Apache Dubbo' + - id: connect_rpc + value: 'connect_rpc' + brief: 'Connect RPC' diff --git a/model/server.yaml b/model/registry/server.yaml similarity index 71% rename from model/server.yaml rename to model/registry/server.yaml index 8f10470221..f47174dda2 100644 --- a/model/server.yaml +++ b/model/registry/server.yaml @@ -7,20 +7,22 @@ groups: 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). + protocol / API doesn't 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. attributes: - id: address + stability: stable type: string - brief: Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. - note: | + brief: "Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name." + note: > When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent - the server address behind any intermediaries (e.g. proxies) if it's available. + the server address behind any intermediaries, for example proxies, if it's available. examples: ['example.com', '10.1.2.80', '/tmp/my.sock'] - id: port + stability: stable type: int brief: Server port number. note: > When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent - the server port behind any intermediaries (e.g. proxies) if it's available. + the server port behind any intermediaries, for example proxies, if it's available. examples: [80, 8080, 443] diff --git a/model/source.yaml b/model/registry/source.yaml similarity index 63% rename from model/source.yaml rename to model/registry/source.yaml index 9c0aa30a28..263a491cab 100644 --- a/model/source.yaml +++ b/model/registry/source.yaml @@ -2,19 +2,20 @@ groups: - id: source prefix: source type: attribute_group - brief: These attributes may be used to describe the sender of a network exchange/packet. These should be used + brief: > + These attributes may be used to describe the sender 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. + "user-facing" surface of the protocol / API doesn't expose a clear notion of client and server. attributes: - id: address type: string - brief: Source address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. + brief: "Source address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name." note: > When observed from the destination side, and when communicating through an intermediary, `source.address` SHOULD represent - the source address behind any intermediaries (e.g. proxies) if it's available. + the source address behind any intermediaries, for example proxies, if it's available. examples: ['source.example.com', '10.1.2.80', '/tmp/my.sock'] - id: port type: int diff --git a/model/registry/thread.yaml b/model/registry/thread.yaml new file mode 100644 index 0000000000..f6b5b5a509 --- /dev/null +++ b/model/registry/thread.yaml @@ -0,0 +1,17 @@ +groups: + - id: registry.thread + prefix: thread + type: span + brief: > + These attributes may be used for any operation to store information about a thread that started a span. + attributes: + - id: id + type: int + brief: > + Current "managed" thread ID (as opposed to OS thread ID). + examples: 42 + - id: name + type: string + brief: > + Current thread name. + examples: main diff --git a/model/registry/tls.yaml b/model/registry/tls.yaml new file mode 100644 index 0000000000..421479d18a --- /dev/null +++ b/model/registry/tls.yaml @@ -0,0 +1,165 @@ +groups: + - id: registry.tls + prefix: tls + type: attribute_group + brief: "This document defines semantic convention attributes in the TLS namespace." + attributes: + - id: cipher + brief: > + String indicating the [cipher](https://datatracker.ietf.org/doc/html/rfc5246#appendix-A.5) used during the current connection. + type: string + note: > + The values allowed for `tls.cipher` MUST be one of the `Descriptions` of the + [registered TLS Cipher Suits](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#table-tls-parameters-4). + examples: + [ + "TLS_RSA_WITH_3DES_EDE_CBC_SHA", + "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256", + ] + - id: client.certificate + type: string + brief: > + PEM-encoded stand-alone certificate offered by the client. This is usually mutually-exclusive of `client.certificate_chain` since this value also exists in that list. + examples: ["MII..."] + - id: client.certificate_chain + type: string[] + brief: > + Array of PEM-encoded certificates that make up the certificate chain offered by the client. + This is usually mutually-exclusive of `client.certificate` since that value should be the first certificate in the chain. + examples: ["MII...", "MI..."] + - id: client.hash.md5 + type: string + brief: > + Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the client. + For consistency with other hash values, this value should be formatted as an uppercase hash. + examples: ["0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC"] + - id: client.hash.sha1 + type: string + brief: > + Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the client. + For consistency with other hash values, this value should be formatted as an uppercase hash. + examples: ["9E393D93138888D288266C2D915214D1D1CCEB2A"] + - id: client.hash.sha256 + type: string + brief: > + Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the client. + For consistency with other hash values, this value should be formatted as an uppercase hash. + examples: + ["0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0"] + - id: client.issuer + type: string + brief: "Distinguished name of [subject](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.6) of the issuer of the x.509 certificate presented by the client." + examples: + ["CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com"] + - id: client.ja3 + type: string + brief: "A hash that identifies clients based on how they perform an SSL/TLS handshake." + examples: ["d4e5b18d6b55c71272893221c96ba240"] + - id: client.not_after + type: string + brief: "Date/Time indicating when client certificate is no longer considered valid." + examples: ["2021-01-01T00:00:00.000Z"] + - id: client.not_before + type: string + brief: "Date/Time indicating when client certificate is first considered valid." + examples: ["1970-01-01T00:00:00.000Z"] + - id: client.server_name + type: string + brief: "Also called an SNI, this tells the server which hostname to which the client is attempting to connect to." + examples: ["opentelemetry.io"] + - id: client.subject + type: string + brief: "Distinguished name of subject of the x.509 certificate presented by the client." + examples: ["CN=myclient, OU=Documentation Team, DC=example, DC=com"] + - id: client.supported_ciphers + type: string[] + brief: Array of ciphers offered by the client during the client hello. + examples: + [ + '"TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", "..."', + ] + - id: curve + brief: "String indicating the curve used for the given cipher, when applicable" + type: string + examples: ["secp256r1"] + - id: established + brief: "Boolean flag indicating if the TLS negotiation was successful and transitioned to an encrypted tunnel." + type: boolean + examples: [true] + - id: next_protocol + brief: > + String indicating the protocol being tunneled. + Per the values in the [IANA registry](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids), + this string should be lower case. + type: string + examples: ["http/1.1"] + - id: protocol.name + brief: > + Normalized lowercase protocol name parsed from original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES) + type: + allow_custom_values: true + members: + - id: ssl + value: ssl + - id: tls + value: tls + - id: protocol.version + brief: > + Numeric part of the version parsed from the original string of the negotiated [SSL/TLS protocol version](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html#RETURN-VALUES) + type: string + examples: ["1.2", "3"] + - id: resumed + brief: "Boolean flag indicating if this TLS connection was resumed from an existing TLS negotiation." + type: boolean + examples: [true] + - id: server.certificate + type: string + brief: > + PEM-encoded stand-alone certificate offered by the server. This is usually mutually-exclusive of `server.certificate_chain` since this value also exists in that list. + examples: ["MII..."] + - id: server.certificate_chain + type: string[] + brief: > + Array of PEM-encoded certificates that make up the certificate chain offered by the server. + This is usually mutually-exclusive of `server.certificate` since that value should be the first certificate in the chain. + examples: ["MII...", "MI..."] + - id: server.hash.md5 + type: string + brief: > + Certificate fingerprint using the MD5 digest of DER-encoded version of certificate offered by the server. + For consistency with other hash values, this value should be formatted as an uppercase hash. + examples: ["0F76C7F2C55BFD7D8E8B8F4BFBF0C9EC"] + - id: server.hash.sha1 + type: string + brief: > + Certificate fingerprint using the SHA1 digest of DER-encoded version of certificate offered by the server. + For consistency with other hash values, this value should be formatted as an uppercase hash. + examples: ["9E393D93138888D288266C2D915214D1D1CCEB2A"] + - id: server.hash.sha256 + type: string + brief: > + Certificate fingerprint using the SHA256 digest of DER-encoded version of certificate offered by the server. + For consistency with other hash values, this value should be formatted as an uppercase hash. + examples: + ["0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0"] + - id: server.issuer + type: string + brief: "Distinguished name of [subject](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.6) of the issuer of the x.509 certificate presented by the client." + examples: + ["CN=Example Root CA, OU=Infrastructure Team, DC=example, DC=com"] + - id: server.ja3s + type: string + brief: "A hash that identifies servers based on how they perform an SSL/TLS handshake." + examples: ["d4e5b18d6b55c71272893221c96ba240"] + - id: server.not_after + type: string + brief: "Date/Time indicating when server certificate is no longer considered valid." + examples: ["2021-01-01T00:00:00.000Z"] + - id: server.not_before + type: string + brief: "Date/Time indicating when server certificate is first considered valid." + examples: ["1970-01-01T00:00:00.000Z"] + - id: server.subject + type: string + brief: "Distinguished name of subject of the x.509 certificate presented by the server." + examples: ["CN=myserver, OU=Documentation Team, DC=example, DC=com"] diff --git a/model/registry/url.yaml b/model/registry/url.yaml new file mode 100644 index 0000000000..985ca9123f --- /dev/null +++ b/model/registry/url.yaml @@ -0,0 +1,41 @@ +groups: + - id: registry.url + brief: Attributes describing URL. + type: attribute_group + prefix: url + attributes: + - id: scheme + stability: stable + type: string + brief: 'The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol.' + examples: ["https", "ftp", "telnet"] + - id: full + stability: stable + type: string + brief: Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) + note: > + 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. + examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv', '//localhost'] + - id: path + stability: stable + type: string + brief: 'The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component' + examples: ['/search'] + - id: query + stability: stable + type: string + brief: 'The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component' + examples: ["q=OpenTelemetry"] + note: Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. + - id: fragment + stability: stable + type: string + brief: 'The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component' + examples: ["SemConv"] diff --git a/model/registry/user-agent.yaml b/model/registry/user-agent.yaml new file mode 100644 index 0000000000..0fbc5c9f2a --- /dev/null +++ b/model/registry/user-agent.yaml @@ -0,0 +1,13 @@ +groups: + - id: registry.user_agent + prefix: user_agent + type: attribute_group + brief: "Describes user-agent attributes." + attributes: + - id: original + stability: stable + type: string + brief: > + Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. + examples: ['CERN-LineMode/2.15 libwww/2.17b3', + 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1'] diff --git a/model/resource/cloud.yaml b/model/resource/cloud.yaml index c24e474855..4699f84842 100644 --- a/model/resource/cloud.yaml +++ b/model/resource/cloud.yaml @@ -5,175 +5,9 @@ groups: brief: > A cloud environment (e.g. GCP, Azure, AWS) attributes: - - id: provider - type: - allow_custom_values: true - members: - - id: 'alibaba_cloud' - value: 'alibaba_cloud' - brief: 'Alibaba Cloud' - - id: 'aws' - value: 'aws' - brief: 'Amazon Web Services' - - id: 'azure' - value: 'azure' - brief: 'Microsoft Azure' - - id: 'gcp' - value: 'gcp' - brief: 'Google Cloud Platform' - - id: 'heroku' - value: 'heroku' - brief: 'Heroku Platform as a Service' - - id: 'ibm_cloud' - value: 'ibm_cloud' - brief: 'IBM Cloud' - - id: 'tencent_cloud' - value: 'tencent_cloud' - brief: 'Tencent Cloud' - - brief: > - Name of the cloud provider. - - id: account.id - type: string - brief: > - The cloud account ID the resource is assigned to. - examples: ['111111111111', 'opentelemetry'] - - id: region - type: string - brief: > - The geographical region the resource is running. - note: > - 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). - examples: ['us-central1', 'us-east-1'] - - id: resource_id - type: string - brief: > - 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) - note: | - 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. - examples: - - '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/' - - id: availability_zone - type: string - brief: > - Cloud regions often have multiple, isolated locations known as zones - to increase availability. Availability zone represents the - zone where the resource is running. - note: > - Availability zones are called "zones" on Alibaba Cloud and Google Cloud. - examples: ['us-east-1c'] - - id: platform - type: - allow_custom_values: true - members: - - id: alibaba_cloud_ecs - value: 'alibaba_cloud_ecs' - brief: Alibaba Cloud Elastic Compute Service - - id: alibaba_cloud_fc - value: 'alibaba_cloud_fc' - brief: Alibaba Cloud Function Compute - - id: alibaba_cloud_openshift - value: 'alibaba_cloud_openshift' - brief: Red Hat OpenShift on Alibaba Cloud - - id: aws_ec2 - value: 'aws_ec2' - brief: AWS Elastic Compute Cloud - - id: aws_ecs - value: 'aws_ecs' - brief: AWS Elastic Container Service - - id: aws_eks - value: 'aws_eks' - brief: AWS Elastic Kubernetes Service - - id: aws_lambda - value: 'aws_lambda' - brief: AWS Lambda - - id: aws_elastic_beanstalk - value: 'aws_elastic_beanstalk' - brief: AWS Elastic Beanstalk - - id: aws_app_runner - value: 'aws_app_runner' - brief: AWS App Runner - - id: aws_openshift - value: 'aws_openshift' - brief: Red Hat OpenShift on AWS (ROSA) - - id: azure_vm - value: 'azure_vm' - brief: Azure Virtual Machines - - id: azure_container_instances - value: 'azure_container_instances' - brief: Azure Container Instances - - id: azure_aks - value: 'azure_aks' - brief: Azure Kubernetes Service - - id: azure_functions - value: 'azure_functions' - brief: Azure Functions - - id: azure_app_service - value: 'azure_app_service' - brief: Azure App Service - - id: azure_openshift - value: 'azure_openshift' - brief: Azure Red Hat OpenShift - - id: gcp_bare_metal_solution - value: 'gcp_bare_metal_solution' - brief: Google Bare Metal Solution (BMS) - - id: gcp_compute_engine - value: 'gcp_compute_engine' - brief: Google Cloud Compute Engine (GCE) - - id: gcp_cloud_run - value: 'gcp_cloud_run' - brief: Google Cloud Run - - id: gcp_kubernetes_engine - value: 'gcp_kubernetes_engine' - brief: Google Cloud Kubernetes Engine (GKE) - - id: gcp_cloud_functions - value: 'gcp_cloud_functions' - brief: Google Cloud Functions (GCF) - - id: gcp_app_engine - value: 'gcp_app_engine' - brief: Google Cloud App Engine (GAE) - - id: gcp_openshift - value: 'gcp_openshift' - brief: Red Hat OpenShift on Google Cloud - - id: ibm_cloud_openshift - value: 'ibm_cloud_openshift' - brief: Red Hat OpenShift on IBM Cloud - - id: tencent_cloud_cvm - value: 'tencent_cloud_cvm' - brief: Tencent Cloud Cloud Virtual Machine (CVM) - - id: tencent_cloud_eks - value: 'tencent_cloud_eks' - brief: Tencent Cloud Elastic Kubernetes Service (EKS) - - id: tencent_cloud_scf - value: 'tencent_cloud_scf' - brief: Tencent Cloud Serverless Cloud Function (SCF) - brief: > - The cloud platform in use. - note: > - The prefix of the service SHOULD match the one specified in `cloud.provider`. + - ref: cloud.provider + - ref: cloud.account.id + - ref: cloud.region + - ref: cloud.resource_id + - ref: cloud.availability_zone + - ref: cloud.platform diff --git a/model/resource/container.yaml b/model/resource/container.yaml index 2080b7b9c6..97923e440e 100644 --- a/model/resource/container.yaml +++ b/model/resource/container.yaml @@ -5,85 +5,18 @@ groups: brief: > A container instance. attributes: - - id: name - type: string - brief: > - Container name used by container runtime. - examples: ['opentelemetry-autoconf'] - - id: id - type: string - brief: > - 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. - examples: ['a3bf90e006b2'] - - id: runtime - type: string - brief: > - The container runtime managing this container. - examples: ['docker', 'containerd', 'rkt'] - - id: image.name - type: string - brief: > - Name of the image the container was built on. - examples: ['gcr.io/opentelemetry/operator'] - - id: image.tags - type: string[] - brief: > - Container image tags. An example can be found in - [Docker Image Inspect](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect). - Should be only the `` section of the full name for example - from `registry.example.com/my-org/my-image:`. - examples: ['v1.27.1', '3.5.7-0'] - - id: image.id - type: string - brief: > - Runtime specific image identifier. Usually a hash algorithm followed by a UUID. - note: > - Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker - container inspect [API](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerInspect) - endpoint. - - K8s defines a link to the container registry repository with digest `"imageID": "registry.azurecr.io - /namespace/service/dockerfile@sha256:bdeabd40c3a8a492eaf9e8e44d0ebbb84bac7ee25ac0cf8a7159d25f62555625"`. - - The ID is assinged by the container runtime and can vary in different environments. - Consider using `oci.manifest.digest` if it is important to identify the same - image in different environments/runtimes. - examples: ['sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f'] - - id: image.repo_digests - type: string[] - brief: > - Repo digests of the container image as provided by the container runtime. - note: > - [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and - [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) - report those under the `RepoDigests` field. - examples: - - 'example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb' - - 'internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578' - - id: command - type: string + - ref: container.name + - ref: container.id + - ref: container.runtime + - ref: container.image.name + - ref: container.image.tags + - ref: container.image.id + - ref: container.image.repo_digests + - ref: container.command requirement_level: opt_in - note: > - If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage. - brief: > - The command used to run the container (i.e. the command name). - examples: [ 'otelcontribcol' ] - - id: command_line - type: string + - ref: container.command_line requirement_level: opt_in - brief: > - The full command run by the container as a single string representing the full command. [2] - examples: [ 'otelcontribcol --config config.yaml' ] - - id: command_args - type: string[] + - ref: container.command_args requirement_level: opt_in - brief: > - All the command arguments (including the command/executable itself) run by the container. [2] - examples: [ 'otelcontribcol, --config, config.yaml' ] - - id: labels - type: template[string] - brief: > - Container labels, `` being the label name, the value being the label value. - examples: [ 'container.labels.app=nginx' ] + - ref: container.labels + - ref: oci.manifest.digest diff --git a/model/resource/deployment_environment.yaml b/model/resource/deployment_environment.yaml index 336cabeced..7ada3f9798 100644 --- a/model/resource/deployment_environment.yaml +++ b/model/resource/deployment_environment.yaml @@ -8,6 +8,14 @@ groups: - id: environment type: string brief: > - Name of the [deployment environment](https://en.wikipedia.org/wiki/Deployment_environment) + Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). + note: | + `deployment.environment` does not affect the uniqueness constraints defined through + the `service.namespace`, `service.name` and `service.instance.id` resource attributes. + This implies that resources carrying the following attribute combinations MUST be + considered to be identifying the same service: + + * `service.name=frontend`, `deployment.environment=production` + * `service.name=frontend`, `deployment.environment=staging`. examples: ['staging', 'production'] diff --git a/model/resource/device.yaml b/model/resource/device.yaml index 3df0a4d6a8..8fab02a8e4 100644 --- a/model/resource/device.yaml +++ b/model/resource/device.yaml @@ -5,37 +5,7 @@ groups: brief: > The device on which the process represented by this resource is running. attributes: - - id: id - type: string - brief: 'A unique identifier representing the device' - note: > - 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. - examples: ['2ab2916d-a51f-4ac8-80ee-45ac31a28092'] - - id: model.identifier - type: string - brief: 'The model identifier for the device' - note: > - 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. - examples: ['iPhone3,4', 'SM-G920F'] - - id: model.name - type: string - brief: 'The marketing name for the device model' - note: > - It's recommended this value represents a human readable version of the - device model rather than a machine readable alternative. - examples: ['iPhone 6s Plus', 'Samsung Galaxy S6'] - - id: manufacturer - type: string - brief: 'The name of the device manufacturer' - note: > - The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`. - examples: ['Apple', 'Samsung'] + - ref: device.id + - ref: device.manufacturer + - ref: device.model.identifier + - ref: device.model.name diff --git a/model/resource/host.yaml b/model/resource/host.yaml index 141ccd76bf..b90b90dcf7 100644 --- a/model/resource/host.yaml +++ b/model/resource/host.yaml @@ -5,80 +5,17 @@ groups: brief: > A host is defined as a computing instance. For example, physical servers, virtual machines, switches or disk array. attributes: - - id: id - type: string - brief: > - 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. - examples: ['fdbf79e8af94cb7f9e8df36789187052'] - - id: name - type: string - brief: > - 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. - examples: ['opentelemetry-test'] - - id: type - type: string - brief: > - Type of host. For Cloud, this must be the machine type. - examples: ['n1-standard-1'] - - id: arch - type: - allow_custom_values: true - members: - - id: amd64 - value: 'amd64' - brief: "AMD64" - - id: arm32 - value: 'arm32' - brief: "ARM32" - - id: arm64 - value: 'arm64' - brief: "ARM64" - - id: ia64 - value: 'ia64' - brief: "Itanium" - - id: ppc32 - value: 'ppc32' - brief: "32-bit PowerPC" - - id: ppc64 - value: 'ppc64' - brief: "64-bit PowerPC" - - id: s390x - value: 's390x' - brief: "IBM z/Architecture" - - id: x86 - value: 'x86' - brief: "32-bit x86" - brief: > - The CPU architecture the host system is running on. - - id: image.name - type: string - brief: > - Name of the VM image or OS install the host was instantiated from. - examples: ['infra-ami-eks-worker-node-7d4ec78312', 'CentOS-8-x86_64-1905'] - - id: image.id - type: string - brief: > - VM image ID or host OS image ID. For Cloud, this value is from the provider. - examples: ['ami-07b06b442921831e5'] - - id: image.version - type: string - brief: > - The version string of the VM image or host OS as defined in - [Version Attributes](README.md#version-attributes). - examples: ['0.1'] - - id: ip - type: string[] + - ref: host.id + - ref: host.name + - ref: host.type + - ref: host.arch + - ref: host.image.name + - ref: host.image.id + - ref: host.image.version + - ref: host.ip + requirement_level: opt_in + - ref: host.mac requirement_level: opt_in - brief: > - Available IP addresses of the host, excluding loopback interfaces. - note: > - IPv4 Addresses MUST be specified in dotted-quad notation. IPv6 addresses - MUST be specified in the [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952.html) format. - examples: ["192.168.1.140", "fe80::abc2:4a28:737a:609e"] - id: host.cpu prefix: host.cpu @@ -86,43 +23,15 @@ groups: brief: > A host's CPU information attributes: - - id: vendor.id + - ref: host.cpu.vendor.id requirement_level: opt_in - type: string - brief: > - Processor manufacturer identifier. A maximum 12-character string. - note: > - [CPUID](https://wiki.osdev.org/CPUID) command returns the vendor ID string in EBX, EDX and ECX registers. - Writing these to memory in this order results in a 12-character string. - examples: [ 'GenuineIntel' ] - - id: family + - ref: host.cpu.family requirement_level: opt_in - type: int - brief: > - Numeric value specifying the family or generation of the CPU. - examples: [ 6 ] - - id: model.id + - ref: host.cpu.model.id requirement_level: opt_in - type: int - brief: > - Model identifier. It provides more granular information about the CPU, distinguishing it from - other CPUs within the same family. - examples: [ 6 ] - - id: model.name + - ref: host.cpu.model.name requirement_level: opt_in - type: string - brief: > - Model designation of the processor. - examples: [ '11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz' ] - - id: stepping + - ref: host.cpu.stepping requirement_level: opt_in - type: int - brief: > - Stepping or core revisions. - examples: [ 1 ] - - id: cache.l2.size + - ref: host.cpu.cache.l2.size requirement_level: opt_in - type: int - brief: > - The amount of level 2 memory cache available to the processor (in Bytes). - examples: [ 12288000 ] diff --git a/model/resource/k8s.yaml b/model/resource/k8s.yaml index 32a9716dbe..f0752f0f09 100644 --- a/model/resource/k8s.yaml +++ b/model/resource/k8s.yaml @@ -5,40 +5,8 @@ groups: brief: > A Kubernetes Cluster. attributes: - - id: name - type: string - brief: > - The name of the cluster. - examples: ['opentelemetry-cluster'] - - id: uid - type: string - brief: > - A pseudo-ID for the cluster, set to the UID of the `kube-system` - namespace. - note: | - 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. - examples: ['218fc5a9-a5f1-4b54-aa05-46717d0ab26d'] + - ref: k8s.cluster.name + - ref: k8s.cluster.uid - id: k8s.node prefix: k8s.node @@ -46,16 +14,8 @@ groups: brief: > A Kubernetes Node object. attributes: - - id: name - type: string - brief: > - The name of the Node. - examples: ['node-1'] - - id: uid - type: string - brief: > - The UID of the Node. - examples: ['1eb3a0c6-0477-4080-a9cb-0cb7db65c6a2'] + - ref: k8s.node.name + - ref: k8s.node.uid - id: k8s.namespace prefix: k8s.namespace @@ -63,11 +23,7 @@ groups: brief: > A Kubernetes Namespace. attributes: - - id: name - type: string - brief: > - The name of the namespace that the pod is running in. - examples: ['default'] + - ref: k8s.namespace.name - id: k8s.pod prefix: k8s.pod @@ -75,16 +31,9 @@ groups: brief: > A Kubernetes Pod object. attributes: - - id: uid - type: string - brief: > - The UID of the Pod. - examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - - id: name - type: string - brief: > - The name of the Pod. - examples: ['opentelemetry-pod-autoconf'] + - ref: k8s.pod.uid + - ref: k8s.pod.name + - ref: k8s.pod.labels - id: k8s.container prefix: k8s.container @@ -92,20 +41,8 @@ groups: brief: > A container in a [PodTemplate](https://kubernetes.io/docs/concepts/workloads/pods/#pod-templates). attributes: - - id: name - type: string - brief: > - The name of the Container from Pod specification, must be unique - within a Pod. Container runtime usually uses different globally unique - name (`container.name`). - examples: ['redis'] - - id: restart_count - type: int - brief: > - Number of times the container was restarted. This attribute can be - used to identify a particular container (running or stopped) within a - container spec. - examples: [0, 2] + - ref: k8s.container.name + - ref: k8s.container.restart_count - id: k8s.replicaset prefix: k8s.replicaset @@ -113,16 +50,8 @@ groups: brief: > A Kubernetes ReplicaSet object. attributes: - - id: uid - type: string - brief: > - The UID of the ReplicaSet. - examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - - id: name - type: string - brief: > - The name of the ReplicaSet. - examples: ['opentelemetry'] + - ref: k8s.replicaset.uid + - ref: k8s.replicaset.name - id: k8s.deployment prefix: k8s.deployment @@ -130,16 +59,8 @@ groups: brief: > A Kubernetes Deployment object. attributes: - - id: uid - type: string - brief: > - The UID of the Deployment. - examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - - id: name - type: string - brief: > - The name of the Deployment. - examples: ['opentelemetry'] + - ref: k8s.deployment.uid + - ref: k8s.deployment.name - id: k8s.statefulset prefix: k8s.statefulset @@ -147,16 +68,8 @@ groups: brief: > A Kubernetes StatefulSet object. attributes: - - id: uid - type: string - brief: > - The UID of the StatefulSet. - examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - - id: name - type: string - brief: > - The name of the StatefulSet. - examples: ['opentelemetry'] + - ref: k8s.statefulset.uid + - ref: k8s.statefulset.name - id: k8s.daemonset prefix: k8s.daemonset @@ -164,16 +77,8 @@ groups: brief: > A Kubernetes DaemonSet object. attributes: - - id: uid - type: string - brief: > - The UID of the DaemonSet. - examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - - id: name - type: string - brief: > - The name of the DaemonSet. - examples: ['opentelemetry'] + - ref: k8s.daemonset.uid + - ref: k8s.daemonset.name - id: k8s.job prefix: k8s.job @@ -181,16 +86,8 @@ groups: brief: > A Kubernetes Job object. attributes: - - id: uid - type: string - brief: > - The UID of the Job. - examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - - id: name - type: string - brief: > - The name of the Job. - examples: ['opentelemetry'] + - ref: k8s.job.uid + - ref: k8s.job.name - id: k8s.cronjob prefix: k8s.cronjob @@ -198,13 +95,5 @@ groups: brief: > A Kubernetes CronJob object. attributes: - - id: uid - type: string - brief: > - The UID of the CronJob. - examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - - id: name - type: string - brief: > - The name of the CronJob. - examples: ['opentelemetry'] + - ref: k8s.cronjob.uid + - ref: k8s.cronjob.name diff --git a/model/resource/os.yaml b/model/resource/os.yaml index 78636f8461..772fdde3a0 100644 --- a/model/resource/os.yaml +++ b/model/resource/os.yaml @@ -8,62 +8,9 @@ groups: 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. attributes: - - id: type - type: - allow_custom_values: true - members: - - id: windows - value: 'windows' - brief: "Microsoft Windows" - - id: linux - value: 'linux' - brief: "Linux" - - id: darwin - value: 'darwin' - brief: "Apple Darwin" - - id: freebsd - value: 'freebsd' - brief: "FreeBSD" - - id: netbsd - value: 'netbsd' - brief: "NetBSD" - - id: openbsd - value: 'openbsd' - brief: "OpenBSD" - - id: dragonflybsd - value: 'dragonflybsd' - brief: "DragonFly BSD" - - id: hpux - value: 'hpux' - brief: "HP-UX (Hewlett Packard Unix)" - - id: aix - value: 'aix' - brief: "AIX (Advanced Interactive eXecutive)" - - id: solaris - value: 'solaris' - brief: "SunOS, Oracle Solaris" - - id: z_os - value: 'z_os' - brief: "IBM z/OS" + - ref: os.type requirement_level: required - brief: 'The operating system type.' - - id: description - type: string - brief: > - Human readable (not intended to be parsed) OS version information, - like e.g. reported by `ver` or `lsb_release -a` commands. - examples: ['Microsoft Windows [Version 10.0.18363.778]', 'Ubuntu 18.04.1 LTS'] - - id: name - type: string - brief: 'Human readable operating system name.' - examples: ['iOS', 'Android', 'Ubuntu'] - - id: version - type: string - brief: > - The version string of the operating system as defined in - [Version Attributes](/docs/resource/README.md#version-attributes). - examples: ['14.2.1', '18.04.1'] - - id: build_id - type: string - brief: 'Unique identifier for a particular build or compilation of the operating system.' - examples: ['TQ3C.230805.001.B2', '20E247', '22621'] + - ref: os.description + - ref: os.name + - ref: os.version + - ref: os.build_id diff --git a/model/resource/process.yaml b/model/resource/process.yaml index d7d3b25b56..61223d61ce 100644 --- a/model/resource/process.yaml +++ b/model/resource/process.yaml @@ -5,69 +5,24 @@ groups: brief: > An operating system process. attributes: - - id: pid - type: int - brief: > - Process identifier (PID). - examples: [1234] - - id: parent_pid - type: int - brief: > - Parent Process identifier (PID). - examples: [111] - - id: executable.name - type: string + - ref: process.pid + - ref: process.parent_pid + - ref: process.executable.name requirement_level: conditionally_required: See alternative attributes below. - brief: > - 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`. - examples: ['otelcol'] - - id: executable.path - type: string + - ref: process.executable.path requirement_level: conditionally_required: See alternative attributes below. - brief: > - 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`. - examples: ['/usr/bin/cmd/otelcol'] - - id: command - type: string + - ref: process.command requirement_level: conditionally_required: See alternative attributes below. - brief: > - 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`. - examples: ['cmd/otelcol'] - - id: command_line - type: string + - ref: process.command_line requirement_level: conditionally_required: See alternative attributes below. - brief: > - 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. - examples: ['C:\cmd\otecol --config="my directory\config.yaml"'] - - id: command_args - type: string[] + - ref: process.command_args requirement_level: conditionally_required: See alternative attributes below. - brief: > - 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`. - examples: ['cmd/otecol', '--config=config.yaml'] - - id: owner - type: string - brief: > - The username of the user that owns the process. - examples: 'root' + - ref: process.owner constraints: - any_of: - process.executable.name @@ -82,21 +37,6 @@ groups: brief: > The single (language) runtime instance which is monitored. attributes: - - id: name - type: string - brief: > - The name of the runtime of this process. For compiled native binaries, - this SHOULD be the name of the compiler. - examples: ['OpenJDK Runtime Environment'] - - id: version - type: string - brief: > - The version of the runtime of this process, as returned by the runtime - without modification. - examples: '14.0.2' - - id: description - type: string - brief: > - An additional description about the runtime of the process, for example - a specific vendor customization of the runtime environment. - examples: 'Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0' + - ref: process.runtime.name + - ref: process.runtime.version + - ref: process.runtime.description diff --git a/model/session.yaml b/model/session.yaml index eacda8416d..f221265338 100644 --- a/model/session.yaml +++ b/model/session.yaml @@ -9,9 +9,18 @@ groups: Consequently, a Session is represented as a collection of Logs, Events, and Spans emitted by the Client Application throughout the Session's duration. Each Session is assigned a unique identifier, which is included as an attribute in the Logs, Events, and Spans generated during the Session's lifecycle. + + When a session reaches end of life, typically due to user inactivity or session timeout, a new session identifier + will be assigned. The previous session identifier may be provided by the instrumentation so that telemetry + backends can link the two sessions. attributes: - id: id type: string brief: "A unique id to identify a session." examples: "00112233-4455-6677-8899-aabbccddeeff" requirement_level: opt_in + - id: previous_id + type: string + brief: "The previous `session.id` for this user, when known." + examples: "00112233-4455-6677-8899-aabbccddeeff" + requirement_level: opt_in diff --git a/model/trace/compatibility.yaml b/model/trace/compatibility.yaml index 62f85e5c08..2e3fe12dc7 100644 --- a/model/trace/compatibility.yaml +++ b/model/trace/compatibility.yaml @@ -15,7 +15,7 @@ groups: members: - id: child_of value: 'child_of' - brief: 'The parent Span depends on the child Span in some capacity' + brief: "The parent Span depends on the child Span in some capacity" - id: follows_from value: 'follows_from' - brief: 'The parent Span does not depend in any way on the result of the child Span' + brief: "The parent Span doesn't depend in any way on the result of the child Span" diff --git a/model/trace/database.yaml b/model/trace/database.yaml index e7e1659505..9df75ee20f 100644 --- a/model/trace/database.yaml +++ b/model/trace/database.yaml @@ -1,233 +1,33 @@ groups: - id: db - prefix: db type: span brief: > This document defines the attributes used to perform database client calls. span_kind: client attributes: - - id: system + - ref: db.system tag: connection-level - brief: An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. requirement_level: required - type: - allow_custom_values: true - members: - - id: other_sql - value: 'other_sql' - brief: 'Some other SQL database. Fallback only. See notes.' - - id: mssql - value: 'mssql' - brief: 'Microsoft SQL Server' - - id: mssqlcompact - value: 'mssqlcompact' - brief: 'Microsoft SQL Server Compact' - - id: mysql - value: 'mysql' - brief: 'MySQL' - - id: oracle - value: 'oracle' - brief: 'Oracle Database' - - id: db2 - value: 'db2' - brief: 'IBM Db2' - - id: postgresql - value: 'postgresql' - brief: 'PostgreSQL' - - id: redshift - value: 'redshift' - brief: 'Amazon Redshift' - - id: hive - value: 'hive' - brief: 'Apache Hive' - - id: cloudscape - value: 'cloudscape' - brief: 'Cloudscape' - - id: hsqldb - value: 'hsqldb' - brief: 'HyperSQL DataBase' - - id: progress - value: 'progress' - brief: 'Progress Database' - - id: maxdb - value: 'maxdb' - brief: 'SAP MaxDB' - - id: hanadb - value: 'hanadb' - brief: 'SAP HANA' - - id: ingres - value: 'ingres' - brief: 'Ingres' - - id: firstsql - value: 'firstsql' - brief: 'FirstSQL' - - id: edb - value: 'edb' - brief: 'EnterpriseDB' - - id: cache - value: 'cache' - brief: 'InterSystems Caché' - - id: adabas - value: 'adabas' - brief: 'Adabas (Adaptable Database System)' - - id: firebird - value: 'firebird' - brief: 'Firebird' - - id: derby - value: 'derby' - brief: 'Apache Derby' - - id: filemaker - value: 'filemaker' - brief: 'FileMaker' - - id: informix - value: 'informix' - brief: 'Informix' - - id: instantdb - value: 'instantdb' - brief: 'InstantDB' - - id: interbase - value: 'interbase' - brief: 'InterBase' - - id: mariadb - value: 'mariadb' - brief: 'MariaDB' - - id: netezza - value: 'netezza' - brief: 'Netezza' - - id: pervasive - value: 'pervasive' - brief: 'Pervasive PSQL' - - id: pointbase - value: 'pointbase' - brief: 'PointBase' - - id: sqlite - value: 'sqlite' - brief: 'SQLite' - - id: sybase - value: 'sybase' - brief: 'Sybase' - - id: teradata - value: 'teradata' - brief: 'Teradata' - - id: vertica - value: 'vertica' - brief: 'Vertica' - - id: h2 - value: 'h2' - brief: 'H2' - - id: coldfusion - value: 'coldfusion' - brief: 'ColdFusion IMQ' - - id: cassandra - value: 'cassandra' - brief: 'Apache Cassandra' - - id: hbase - value: 'hbase' - brief: 'Apache HBase' - - id: mongodb - value: 'mongodb' - brief: 'MongoDB' - - id: redis - value: 'redis' - brief: 'Redis' - - id: couchbase - value: 'couchbase' - brief: 'Couchbase' - - id: couchdb - value: 'couchdb' - brief: 'CouchDB' - - id: cosmosdb - value: 'cosmosdb' - brief: 'Microsoft Azure Cosmos DB' - - id: dynamodb - value: 'dynamodb' - brief: 'Amazon DynamoDB' - - id: neo4j - value: 'neo4j' - brief: 'Neo4j' - - id: geode - value: 'geode' - brief: 'Apache Geode' - - id: elasticsearch - value: 'elasticsearch' - brief: 'Elasticsearch' - - id: memcached - value: 'memcached' - brief: 'Memcached' - - id: cockroachdb - value: 'cockroachdb' - brief: 'CockroachDB' - - id: opensearch - value: 'opensearch' - brief: 'OpenSearch' - - id: clickhouse - value: 'clickhouse' - brief: 'ClickHouse' - - id: spanner - value: 'spanner' - brief: 'Cloud Spanner' - - id: trino - value: 'trino' - brief: 'Trino' - - id: connection_string + + - ref: db.connection_string tag: connection-level - type: string - brief: > - The connection string used to connect to the database. - It is recommended to remove embedded credentials. - examples: 'Server=(localdb)\v11.0;Integrated Security=true;' - - id: user + - ref: db.user tag: connection-level - type: string - brief: > - Username for accessing the database. - examples: ['readonly_user', 'reporting_user'] - - id: jdbc.driver_classname + - ref: db.jdbc.driver_classname tag: connection-level-tech-specific - type: string - brief: > - 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. - examples: ['org.postgresql.Driver', 'com.microsoft.sqlserver.jdbc.SQLServerDriver'] - - id: name + - ref: db.name tag: call-level - type: string requirement_level: conditionally_required: If applicable. - brief: > - 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). - note: > - 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). - examples: [ 'customers', 'main' ] - - id: statement + - ref: db.statement tag: call-level - type: string requirement_level: recommended: > Should be collected by default only if there is sanitization that excludes sensitive information. - brief: > - The database statement being executed. - examples: ['SELECT * FROM wuser_table', 'SET mykey "WuValue"'] - - id: operation + - ref: db.operation tag: call-level - type: string requirement_level: conditionally_required: If `db.statement` is not applicable. - brief: > - 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. - note: > - 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. - examples: ['findAndModify', 'HMSET', 'SELECT'] - ref: server.address tag: connection-level brief: > @@ -237,8 +37,6 @@ groups: requirement_level: conditionally_required: If using a port other than the default port for this DBMS and if `server.address` is set. - ref: network.peer.address - requirement_level: - recommended: If different than `server.address`. tag: connection-level - ref: network.peer.port requirement_level: @@ -248,27 +46,21 @@ groups: tag: connection-level - ref: network.type tag: connection-level + - ref: db.instance.id + tag: connection-level + requirement_level: + recommended: If different from the `server.address` - id: db.mssql - prefix: db.mssql type: span extends: db brief: > Connection-level attributes for Microsoft SQL Server attributes: - - id: instance_name + - ref: db.mssql.instance_name tag: connection-level-tech-specific - type: string - note: > - If setting a `db.mssql.instance_name`, `server.port` is no longer - required (but still recommended if non-standard). - brief: > - 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. - examples: 'MSSQLSERVER' - id: db.cassandra - prefix: db.cassandra type: span extends: db brief: > @@ -280,79 +72,22 @@ groups: The keyspace name in Cassandra. examples: ["mykeyspace"] note: For Cassandra the `db.name` should be set to the Cassandra keyspace name. - - id: page_size - type: int + - ref: db.cassandra.page_size tag: call-level-tech-specific-cassandra - brief: > - The fetch size used for paging, i.e. how many rows will be returned at once. - examples: [5000] - - id: consistency_level + - ref: db.cassandra.consistency_level tag: call-level-tech-specific-cassandra - brief: > - 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). - type: - members: - - id: all - value: 'all' - - id: each_quorum - value: 'each_quorum' - - id: quorum - value: 'quorum' - - id: local_quorum - value: 'local_quorum' - - id: one - value: 'one' - - id: two - value: 'two' - - id: three - value: 'three' - - id: local_one - value: 'local_one' - - id: any - value: 'any' - - id: serial - value: 'serial' - - id: local_serial - value: 'local_serial' - - id: table - type: string + - ref: db.cassandra.table tag: call-level-tech-specific-cassandra - requirement_level: recommended - brief: The name of the primary table that the operation is acting upon, including the keyspace name (if applicable). - note: > - 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. - examples: 'mytable' - - id: idempotence - type: boolean + - ref: db.cassandra.idempotence tag: call-level-tech-specific-cassandra - brief: > - Whether or not the query is idempotent. - - id: speculative_execution_count - type: int + - ref: db.cassandra.speculative_execution_count tag: call-level-tech-specific-cassandra - brief: > - The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. - examples: [0, 2] - - id: coordinator.id - type: string + - ref: db.cassandra.coordinator.id tag: call-level-tech-specific-cassandra - brief: > - The ID of the coordinating node for a query. - examples: 'be13faa2-8574-4d71-926d-27f16cf8a7af' - - id: coordinator.dc - type: string + - ref: db.cassandra.coordinator.dc tag: call-level-tech-specific-cassandra - brief: > - The data center of the coordinating node for a query. - examples: 'us-west-2' - id: db.hbase - prefix: db.hbase type: span extends: db brief: > @@ -366,7 +101,6 @@ groups: note: For HBase the `db.name` should be set to the HBase namespace. - id: db.couchdb - prefix: db.couchdb type: span extends: db brief: > @@ -385,21 +119,15 @@ groups: [`GET /{db}/{docid}`](http://docs.couchdb.org/en/stable/api/document/common.html#get--db-docid). - id: db.redis - prefix: db.redis type: span extends: db brief: > Call-level attributes for Redis attributes: - - id: database_index - type: int + - ref: db.redis.database_index requirement_level: conditionally_required: If other than the default database (`0`). tag: call-level-tech-specific - brief: > - 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. - examples: [0, 1, 15] - ref: db.statement tag: call-level-tech-specific brief: > @@ -410,22 +138,16 @@ groups: If, for example, the [`HMSET` command](https://redis.io/commands/hmset) is invoked, `"HMSET myhash field1 'Hello' field2 'World'"` would be a suitable value for `db.statement`. - id: db.mongodb - prefix: db.mongodb type: span extends: db brief: > Call-level attributes for MongoDB attributes: - - id: collection - type: string + - ref: db.mongodb.collection requirement_level: required tag: call-level-tech-specific - brief: > - The collection being accessed within the database stated in `db.name`. - examples: [ 'customers', 'products' ] - id: db.elasticsearch - prefix: db.elasticsearch type: span extends: db brief: > @@ -433,13 +155,16 @@ groups: attributes: - ref: http.request.method requirement_level: required + tag: call-level-tech-specific - ref: db.operation requirement_level: required brief: The endpoint identifier for the request. examples: [ 'search', 'ml.close_job', 'cat.aliases' ] + tag: call-level-tech-specific - ref: url.full requirement_level: required examples: [ 'https://localhost:9200/index/_search?q=user.id:kimchy' ] + tag: call-level-tech-specific - ref: db.statement requirement_level: recommended: > @@ -447,59 +172,34 @@ groups: sensitive information. brief: The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. examples: [ '"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"' ] + tag: call-level-tech-specific - ref: server.address + tag: call-level-tech-specific - ref: server.port - - id: cluster.name - type: string + tag: call-level-tech-specific + - ref: db.elasticsearch.cluster.name requirement_level: recommended: > When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. tag: call-level-tech-specific - brief: > - Represents the identifier of an Elasticsearch cluster. - examples: ["e9106fc68e3044f0b1475b04bf4ffd5f"] - - id: node.name - type: string + - ref: db.elasticsearch.node.name requirement_level: recommended: > When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header. tag: call-level-tech-specific - brief: > - Represents the human-readable identifier of the node/instance to which a request was routed. - examples: ["instance-0000000001"] - - id: path_parts - type: template[string] + - ref: db.elasticsearch.path_parts requirement_level: conditionally_required: when the url has dynamic values tag: call-level-tech-specific - brief: > - A dynamic value in the url path. - note: > - Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format - `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD - reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) - in order to map the path part values to their names. - examples: ['db.elasticsearch.path_parts.index=test-index', 'db.elasticsearch.path_parts.doc_id=123'] - id: db.sql - prefix: 'db.sql' type: span extends: 'db' brief: > Call-level attributes for SQL databases attributes: - - id: table + - ref: db.sql.table tag: call-level-tech-specific - type: string - requirement_level: recommended - brief: The name of the primary table that the operation is acting upon, including the database name (if applicable). - note: > - 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. - examples: ['public.users', 'customers'] - id: db.cosmosdb type: span @@ -508,47 +208,12 @@ groups: brief: > Call-level attributes for Cosmos DB. attributes: - - id: client_id - type: string - brief: Unique Cosmos client instance id. - examples: '3ba4827d-4422-483f-b59f-85b74211c11d' - - id: operation_type - type: - allow_custom_values: true - members: - - id: invalid - value: 'Invalid' - - id: create - value: 'Create' - - id: patch - value: 'Patch' - - id: read - value: 'Read' - - id: read_feed - value: 'ReadFeed' - - id: delete - value: 'Delete' - - id: replace - value: 'Replace' - - id: execute - value: 'Execute' - - id: query - value: 'Query' - - id: head - value: 'Head' - - id: head_feed - value: 'HeadFeed' - - id: upsert - value: 'Upsert' - - id: batch - value: 'Batch' - - id: query_plan - value: 'QueryPlan' - - id: execute_javascript - value: 'ExecuteJavaScript' - brief: CosmosDB Operation Type. + - ref: db.cosmosdb.client_id + tag: call-level-tech-specific + - ref: db.cosmosdb.operation_type requirement_level: conditionally_required: when performing one of the operations in this list + tag: call-level-tech-specific - ref: user_agent.original brief: 'Full user-agent string is generated by Cosmos DB SDK' note: > @@ -563,46 +228,29 @@ groups: Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it). Default value is "NS". examples: ['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\|'] - - id: connection_mode - type: - allow_custom_values: false - members: - - id: gateway - value: 'gateway' - brief: Gateway (HTTP) connections mode - - id: direct - value: 'direct' - brief: Direct connection. - brief: Cosmos client connection mode. + tag: call-level-tech-specific + - ref: db.cosmosdb.connection_mode requirement_level: conditionally_required: if not `direct` (or pick gw as default) - - id: container - type: string - brief: Cosmos DB container name. + tag: call-level-tech-specific + - ref: db.cosmosdb.container requirement_level: conditionally_required: if available - examples: 'anystring' - - id: request_content_length - type: int - brief: Request payload size in bytes - - id: status_code - type: int - brief: Cosmos DB status code. - examples: [200, 201] + tag: call-level-tech-specific + - ref: db.cosmosdb.request_content_length + tag: call-level-tech-specific + - ref: db.cosmosdb.status_code requirement_level: conditionally_required: if response was received - - id: sub_status_code - type: int - brief: Cosmos DB sub status code. - examples: [1000, 1002] + tag: call-level-tech-specific + - ref: db.cosmosdb.sub_status_code requirement_level: conditionally_required: when response was received and contained sub-code. - - id: request_charge - type: double - brief: RU consumed for that operation - examples: [46.18, 1.0] + tag: call-level-tech-specific + - ref: db.cosmosdb.request_charge requirement_level: conditionally_required: when available + tag: call-level-tech-specific - id: db.tech type: span diff --git a/model/trace/exporter/exporter.yaml b/model/trace/exporter/exporter.yaml index bba71aac9b..2989475d71 100644 --- a/model/trace/exporter/exporter.yaml +++ b/model/trace/exporter/exporter.yaml @@ -17,5 +17,5 @@ groups: brief: Name of the code, either "OK" or "ERROR". MUST NOT be set if the status code is UNSET. - id: status_description type: string - brief: Description of the Status if it has a value, otherwise not set. + brief: "Description of the Status if it has a value, otherwise not set." examples: ['resource not found'] diff --git a/model/trace/http.yaml b/model/trace/http.yaml index adb3534875..1e5667ad4f 100644 --- a/model/trace/http.yaml +++ b/model/trace/http.yaml @@ -10,20 +10,20 @@ groups: - ref: http.request.method_original requirement_level: conditionally_required: If and only if it's different than `http.request.method`. - - ref: http.request.body.size - - ref: http.request.header - requirement_level: opt_in - - ref: http.response.body.size - ref: http.response.header requirement_level: opt_in - ref: http.request.method sampling_relevant: true requirement_level: required - - ref: network.transport + - ref: network.peer.address + - ref: network.peer.port requirement_level: - conditionally_required: If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`). - - ref: network.type - - ref: user_agent.original + recommended: If `network.peer.address` is set. + - ref: network.transport + requirement_level: opt_in + note: > + Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. + Other obscure implementations are possible. - id: trace.http.client type: span @@ -31,22 +31,21 @@ groups: span_kind: client brief: 'Semantic Convention for HTTP Client' attributes: - - ref: http.resend_count + - ref: http.request.resend_count requirement_level: recommended: if and only if request was retried. + - ref: http.request.header + requirement_level: opt_in - ref: server.address sampling_relevant: true - ref: server.port sampling_relevant: true - - ref: network.peer.address - requirement_level: - recommended: If different than `server.address`. - - ref: network.peer.port - requirement_level: - recommended: If `network.peer.address` is set. - ref: url.full sampling_relevant: true requirement_level: required + - ref: user_agent.original + requirement_level: opt_in + - ref: url.scheme - id: trace.http.server type: span @@ -55,6 +54,9 @@ groups: brief: 'Semantic Convention for HTTP Server' attributes: - ref: http.route + - ref: http.request.header + sampling_relevant: true + requirement_level: opt_in - ref: server.address sampling_relevant: true - ref: server.port @@ -66,19 +68,16 @@ groups: requirement_level: opt_in brief: Local socket port. Useful in case of a multi-port host. - ref: client.address + sampling_relevant: true note: > 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). + known (e.g. from [Forwarded#for](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#for), + [X-Forwarded-For](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-For), or a similar header). Otherwise, the immediate client peer address. examples: ['83.164.160.102'] - ref: client.port - brief: > - 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. - - ref: network.peer.address - - ref: network.peer.port + requirement_level: opt_in + brief: The port of whichever client was captured in `client.address`. - ref: url.path requirement_level: required sampling_relevant: true @@ -88,3 +87,5 @@ groups: sampling_relevant: true - ref: url.scheme sampling_relevant: true + - ref: user_agent.original + sampling_relevant: true diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index 3313d95f55..be7a4441c7 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -1,39 +1,15 @@ groups: - id: messaging.message - prefix: messaging type: attribute_group brief: 'Semantic convention describing per-message attributes populated on messaging spans or links.' attributes: - ref: messaging.destination.name - - id: message.id - type: string - brief: 'A value used by the messaging system as an identifier for the message, represented as a string.' - examples: '452a7c7c7c7048c2f887f61572b18fc2' - - id: message.conversation_id - type: string - brief: > - The [conversation ID](#conversations) identifying the conversation to which the message belongs, - represented as a string. Sometimes called "Correlation ID". - examples: 'MyConversationId' - - id: message.envelope.size - type: int - brief: > - The size of the message body and metadata in bytes. - note: | - This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed - size should be used. - examples: 2738 - - id: message.body.size - type: int - brief: > - The size of the message body in bytes. - note: | - This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed - body size should be used. - examples: 1439 + - ref: messaging.message.id + - ref: messaging.message.conversation_id + - ref: messaging.message.envelope.size + - ref: messaging.message.body.size - id: messaging.destination - prefix: messaging.destination type: attribute_group brief: 'Semantic convention for attributes that describe messaging destination on broker' note: | @@ -46,29 +22,10 @@ groups: applies to all messages in the batch. In other cases, destination attributes may be set on links. attributes: - - id: name - type: string - brief: 'The message destination name' - note: | - 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. - examples: ['MyQueue', 'MyTopic'] - - id: template - type: string - brief: Low cardinality representation of the messaging destination name - note: > - 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. - examples: ['/customers/{customerId}'] - - id: temporary - type: boolean - brief: 'A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed.' - - id: anonymous - type: boolean - brief: 'A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name).' + - ref: messaging.destination.name + - ref: messaging.destination.template + - ref: messaging.destination.temporary + - ref: messaging.destination.anonymous - id: messaging.destination_publish prefix: messaging.destination_publish @@ -87,61 +44,24 @@ groups: applies to all messages in the batch. In other cases, destination attributes may be set on links. attributes: - - id: name - type: string - brief: 'The name of the original destination the message was published to' - note: | - The name SHOULD uniquely identify a specific queue, topic, or other entity within the broker. If - the broker does not have such notion, the original destination name SHOULD uniquely identify the broker. - examples: ['MyQueue', 'MyTopic'] - - id: anonymous - type: boolean - brief: 'A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name).' + - ref: messaging.destination_publish.name + - ref: messaging.destination_publish.anonymous - id: messaging - prefix: messaging type: span brief: > This document defines general attributes used in messaging systems. + extends: messaging.attributes.common attributes: - - id: system - type: string + - ref: messaging.operation requirement_level: required - brief: 'A string identifying the messaging system.' - examples: ['kafka', 'rabbitmq', 'rocketmq', 'activemq', 'AmazonSQS'] - - id: operation - type: - allow_custom_values: true - members: - - id: publish - value: "publish" - - id: receive - value: "receive" - - id: process - value: "process" - requirement_level: required - brief: > - A string identifying the kind of messaging operation as defined in the - [Operation names](#operation-names) section above. - note: If a custom value is used, it MUST be of low cardinality. - - id: batch.message_count - type: int - brief: The number of messages sent, received, or processed in the scope of the batching operation. + - ref: messaging.batch.message_count requirement_level: conditionally_required: If the span describes an operation on a batch of messages. - note: > - 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. - examples: [0, 1, 2] - - id: client_id - type: string + - ref: messaging.client_id requirement_level: recommended: If a client id is available - brief: > - A unique identifier for the client that consumes or produces a message. - examples: ['client-5', 'myhost@8742@s8083jm'] - ref: messaging.destination.name requirement_level: conditionally_required: If span describes operation on a single message or if the value applies to all messages in the batch. @@ -169,13 +89,7 @@ groups: requirement_level: recommended: Only if span represents operation on a single message. - ref: server.address - note: > - This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. - requirement_level: - conditionally_required: If available. - ref: network.peer.address - requirement_level: - recommended: If different than `server.address`. tag: connection-level - ref: network.peer.port requirement_level: @@ -185,141 +99,76 @@ groups: tag: connection-level - ref: network.type tag: connection-level - - ref: network.protocol.name - examples: ['amqp', 'mqtt'] - - ref: network.protocol.version - id: messaging.rabbitmq - prefix: messaging.rabbitmq type: attribute_group extends: messaging brief: > Attributes for RabbitMQ attributes: - - id: destination.routing_key - type: string + - ref: messaging.rabbitmq.destination.routing_key requirement_level: conditionally_required: If not empty. - brief: > - RabbitMQ message routing key. - examples: 'myKey' + tag: tech-specific-rabbitmq - id: messaging.kafka - prefix: messaging.kafka type: attribute_group extends: messaging brief: > Attributes for Apache Kafka attributes: - - id: message.key - type: string - brief: > - 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. - note: > - 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. - examples: 'myKey' - - id: consumer.group - type: string - brief: > - Name of the Kafka Consumer Group that is handling the message. - Only applies to consumers, not producers. - examples: 'my-group' - - id: destination.partition - type: int - brief: > - Partition the message is sent to. - examples: 2 - - id: message.offset - type: int - brief: > - The offset of a record in the corresponding Kafka partition. - examples: 42 - - id: message.tombstone - type: boolean + - ref: messaging.kafka.message.key + tag: tech-specific-kafka + - ref: messaging.kafka.consumer.group + tag: tech-specific-kafka + - ref: messaging.kafka.destination.partition + tag: tech-specific-kafka + - ref: messaging.kafka.message.offset + tag: tech-specific-kafka + - ref: messaging.kafka.message.tombstone requirement_level: conditionally_required: If value is `true`. When missing, the value is assumed to be `false`. - brief: 'A boolean that is true if the message is a tombstone.' + tag: tech-specific-kafka - id: messaging.rocketmq - prefix: messaging.rocketmq type: attribute_group extends: messaging brief: > Attributes for Apache RocketMQ attributes: - - id: namespace - type: string + - ref: messaging.rocketmq.namespace requirement_level: required - brief: > - Namespace of RocketMQ resources, resources in different namespaces are individual. - examples: 'myNamespace' - - id: client_group - type: string + tag: tech-specific-rocketmq + - ref: messaging.rocketmq.client_group requirement_level: required - brief: > - Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. - examples: 'myConsumerGroup' - - id: message.delivery_timestamp - type: int + tag: tech-specific-rocketmq + - ref: messaging.rocketmq.message.delivery_timestamp requirement_level: conditionally_required: If the message type is delay and delay time level is not specified. - brief: > - The timestamp in milliseconds that the delay message is expected to be delivered to consumer. - examples: 1665987217045 - - id: message.delay_time_level - type: int + tag: tech-specific-rocketmq + - ref: messaging.rocketmq.message.delay_time_level requirement_level: conditionally_required: If the message type is delay and delivery timestamp is not specified. - brief: > - The delay time level for delay message, which determines the message delay time. - examples: 3 - - id: message.group - type: string + tag: tech-specific-rocketmq + - ref: messaging.rocketmq.message.group requirement_level: conditionally_required: If the message type is FIFO. - brief: > - 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. - examples: 'myMessageGroup' - - id: message.type - type: - allow_custom_values: false - members: - - id: normal - value: 'normal' - brief: "Normal message" - - id: fifo - value: 'fifo' - brief: 'FIFO message' - - id: delay - value: 'delay' - brief: 'Delay message' - - id: transaction - value: 'transaction' - brief: 'Transaction message' - brief: > - Type of message. - - id: message.tag - type: string - brief: > - The secondary classifier of message besides topic. - examples: tagA - - id: message.keys - type: string[] - brief: > - Key(s) of message, another way to mark message besides message id. - examples: ['keyA', 'keyB'] - - id: consumption_model - type: - allow_custom_values: false - members: - - id: clustering - value: 'clustering' - brief: 'Clustering consumption model' - - id: broadcasting - value: 'broadcasting' - brief: 'Broadcasting consumption model' - brief: > - Model of message consumption. This only applies to consumer spans. + tag: tech-specific-rocketmq + - ref: messaging.rocketmq.message.type + tag: tech-specific-rocketmq + - ref: messaging.rocketmq.message.tag + tag: tech-specific-rocketmq + - ref: messaging.rocketmq.message.keys + tag: tech-specific-rocketmq + - ref: messaging.rocketmq.consumption_model + tag: tech-specific-rocketmq + - id: messaging.gcp_pubsub + type: attribute_group + extends: messaging + brief: > + Attributes for Google Cloud Pub/Sub + attributes: + - ref: messaging.gcp_pubsub.message.ordering_key + tag: tech-specific-gcp-pubsub + requirement_level: + conditionally_required: If the message type has an ordering key set. diff --git a/model/trace/rpc.yaml b/model/trace/rpc.yaml index 8cee3efc39..de36d6767a 100644 --- a/model/trace/rpc.yaml +++ b/model/trace/rpc.yaml @@ -5,50 +5,10 @@ groups: brief: 'This document defines semantic conventions for remote procedure calls.' events: [rpc.message] attributes: - - id: system + - ref: rpc.system requirement_level: required - brief: 'A string identifying the remoting system. See below for a list of well-known identifiers.' - type: - allow_custom_values: true - members: - - id: grpc - value: 'grpc' - brief: 'gRPC' - - id: java_rmi - value: 'java_rmi' - brief: 'Java RMI' - - id: dotnet_wcf - value: 'dotnet_wcf' - brief: '.NET WCF' - - id: apache_dubbo - value: 'apache_dubbo' - brief: 'Apache Dubbo' - - id: connect_rpc - value: 'connect_rpc' - brief: 'Connect RPC' - - id: service - type: string - requirement_level: recommended - brief: 'The full (logical) name of the service being called, including its package name, if applicable.' - note: > - 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). - examples: "myservice.EchoService" - - id: method - type: string - requirement_level: recommended - brief: 'The name of the (logical) method being called, must be equal to the $method part in the span name.' - note: > - 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). - examples: "exampleMethod" + - ref: rpc.service + - ref: rpc.method - ref: network.transport - ref: network.type - ref: server.address @@ -61,7 +21,7 @@ groups: `server.address` to the IP address provided in the host component. - ref: server.port requirement_level: - conditionally_required: See below + conditionally_required: if the port is supported by the network transport used for communication. - id: rpc.client type: span @@ -69,14 +29,11 @@ groups: extends: rpc attributes: - ref: network.peer.address - requirement_level: - recommended: If different than `server.address`. - ref: network.peer.port requirement_level: recommended: If `network.peer.address` is set. - id: rpc.server - prefix: rpc type: span extends: rpc span_kind: server @@ -85,8 +42,6 @@ groups: - ref: client.address - ref: client.port - ref: network.peer.address - requirement_level: - recommended: If different than `client.address`. - ref: network.peer.port requirement_level: recommended: If `network.peer.address` is set. @@ -94,85 +49,19 @@ groups: - ref: network.type - id: rpc.grpc - prefix: rpc.grpc type: span extends: rpc brief: 'Tech-specific attributes for gRPC.' attributes: - - id: status_code - type: - members: - - id: ok - brief: OK - value: 0 - - id: cancelled - brief: CANCELLED - value: 1 - - id: unknown - brief: UNKNOWN - value: 2 - - id: invalid_argument - brief: INVALID_ARGUMENT - value: 3 - - id: deadline_exceeded - brief: DEADLINE_EXCEEDED - value: 4 - - id: not_found - brief: NOT_FOUND - value: 5 - - id: already_exists - brief: ALREADY_EXISTS - value: 6 - - id: permission_denied - brief: PERMISSION_DENIED - value: 7 - - id: resource_exhausted - brief: RESOURCE_EXHAUSTED - value: 8 - - id: failed_precondition - brief: FAILED_PRECONDITION - value: 9 - - id: aborted - brief: ABORTED - value: 10 - - id: out_of_range - brief: OUT_OF_RANGE - value: 11 - - id: unimplemented - brief: UNIMPLEMENTED - value: 12 - - id: internal - brief: INTERNAL - value: 13 - - id: unavailable - brief: UNAVAILABLE - value: 14 - - id: data_loss - brief: DATA_LOSS - value: 15 - - id: unauthenticated - brief: UNAUTHENTICATED - value: 16 + - ref: rpc.grpc.status_code + tag: grpc-tech-specific requirement_level: required - brief: "The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request." - - id: request.metadata - type: template[string[]] + - ref: rpc.grpc.request.metadata + tag: grpc-tech-specific requirement_level: opt_in - brief: > - gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. - note: > - Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. - Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. - examples: ['rpc.grpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]'] - - id: response.metadata - type: template[string[]] + - ref: rpc.grpc.response.metadata + tag: grpc-tech-specific requirement_level: opt_in - brief: > - gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. - note: > - Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. - Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. - examples: ['rpc.grpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]'] - id: rpc.jsonrpc prefix: rpc.jsonrpc @@ -180,31 +69,20 @@ groups: extends: rpc brief: 'Tech-specific attributes for [JSON RPC](https://www.jsonrpc.org/).' attributes: - - id: version - type: string + - ref: rpc.jsonrpc.version + tag: jsonrpc-tech-specific requirement_level: conditionally_required: If other than the default version (`1.0`) - brief: "Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 does not specify this, the value can be omitted." - examples: ['2.0', '1.0'] - - id: request_id - type: string - brief: > - `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. - examples: ['10', 'request-7', ''] - - id: error_code - type: int + - ref: rpc.jsonrpc.request_id + tag: jsonrpc-tech-specific + - ref: rpc.jsonrpc.error_code + tag: jsonrpc-tech-specific requirement_level: conditionally_required: If response is not successful. - brief: "`error.code` property of response if it is an error response." - examples: [-32700, 100] - - id: error_message - type: string - brief: "`error.message` property of response if it is an error response." - examples: ['Parse error', 'User already exists'] + - ref: rpc.jsonrpc.error_message + tag: jsonrpc-tech-specific - ref: rpc.method + tag: jsonrpc-tech-specific requirement_level: required note: > This is always required for jsonrpc. See the note in the general @@ -235,64 +113,17 @@ groups: brief: "Uncompressed size of the message in bytes." - id: rpc.connect_rpc - prefix: rpc.connect_rpc type: span extends: rpc brief: 'Tech-specific attributes for Connect RPC.' attributes: - - id: error_code - type: - members: - - id: cancelled - value: cancelled - - id: unknown - value: unknown - - id: invalid_argument - value: invalid_argument - - id: deadline_exceeded - value: deadline_exceeded - - id: not_found - value: not_found - - id: already_exists - value: already_exists - - id: permission_denied - value: permission_denied - - id: resource_exhausted - value: resource_exhausted - - id: failed_precondition - value: failed_precondition - - id: aborted - value: aborted - - id: out_of_range - value: out_of_range - - id: unimplemented - value: unimplemented - - id: internal - value: internal - - id: unavailable - value: unavailable - - id: data_loss - value: data_loss - - id: unauthenticated - value: unauthenticated + - ref: rpc.connect_rpc.error_code + tag: connect_rpc-tech-specific requirement_level: conditionally_required: If response is not successful and if error code available. - brief: "The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values." - - id: request.metadata - type: template[string[]] + - ref: rpc.connect_rpc.request.metadata + tag: connect_rpc-tech-specific requirement_level: opt_in - brief: > - Connect request metadata, `` being the normalized Connect Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. - note: > - Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. - Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. - examples: ['rpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]'] - - id: response.metadata - type: template[string[]] + - ref: rpc.connect_rpc.response.metadata + tag: connect_rpc-tech-specific requirement_level: opt_in - brief: > - Connect response metadata, `` being the normalized Connect Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. - note: > - Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. - Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. - examples: ['rpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]'] diff --git a/model/url.yaml b/model/url.yaml index 6e839fc394..bb27dc4e6d 100644 --- a/model/url.yaml +++ b/model/url.yaml @@ -4,36 +4,10 @@ groups: type: attribute_group prefix: url attributes: - - id: scheme - type: string - brief: 'The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol.' - examples: ["https", "ftp", "telnet"] - - id: full - type: string - brief: Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) - note: > - 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. - examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv', '//localhost'] + - ref: url.scheme + - ref: url.full tag: sensitive-information - - id: path - type: string - brief: 'The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component' - examples: ['/search'] - note: When missing, the value is assumed to be `/` - - id: query - type: string - brief: 'The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component' - examples: ["q=OpenTelemetry"] - note: Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. + - ref: url.path + - ref: url.query tag: sensitive-information - - id: fragment - type: string - brief: 'The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component' - examples: ["SemConv"] + - ref: url.fragment diff --git a/model/user-agent.yaml b/model/user-agent.yaml deleted file mode 100644 index 2f43b1af3e..0000000000 --- a/model/user-agent.yaml +++ /dev/null @@ -1,10 +0,0 @@ -groups: - - id: attributes.user_agent - type: attribute_group - brief: "Describes user-agent attributes." - prefix: user_agent - attributes: - - id: original - type: string - brief: 'Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client.' - examples: ['CERN-LineMode/2.15 libwww/2.17b3'] diff --git a/schema-next.yaml b/schema-next.yaml index b238dd19c5..834bff8780 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -2,6 +2,24 @@ file_format: 1.1.0 schema_url: https://opentelemetry.io/schemas/next versions: next: + # https://github.com/open-telemetry/semantic-conventions/pull/536 + - rename_metrics: + jvm.memory.usage: jvm.memory.used + jvm.memory.usage_after_last_gc: jvm.memory.used_after_last_gc + # https://github.com/open-telemetry/semantic-conventions/pull/530 + - rename_attributes: + attribute_map: + system.network.io.direction: network.io.direction + system.disk.io.direction: disk.io.direction + 1.23.0: + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/20 + - rename_attributes: + attribute_map: + thread.daemon: jvm.thread.daemon + apply_to_metrics: + - jvm.thread.count 1.22.0: spans: changes: @@ -9,6 +27,10 @@ versions: - rename_attributes: attribute_map: messaging.message.payload_size_bytes: messaging.message.body.size + # https://github.com/open-telemetry/opentelemetry-specification/pull/374 + - rename_attributes: + attribute_map: + http.resend_count: http.request.resend_count metrics: changes: # https://github.com/open-telemetry/semantic-conventions/pull/224 diff --git a/schemas/1.23.0 b/schemas/1.23.0 new file mode 100644 index 0000000000..a6e29937d0 --- /dev/null +++ b/schemas/1.23.0 @@ -0,0 +1,293 @@ +file_format: 1.1.0 +schema_url: https://opentelemetry.io/schemas/1.23.0 +versions: + 1.23.0: + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/20 + - rename_attributes: + attribute_map: + thread.daemon: jvm.thread.daemon + apply_to_metrics: + - jvm.thread.count + 1.22.0: + spans: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/229 + - rename_attributes: + attribute_map: + messaging.message.payload_size_bytes: messaging.message.body.size + # https://github.com/open-telemetry/opentelemetry-specification/pull/374 + - rename_attributes: + attribute_map: + http.resend_count: http.request.resend_count + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/224 + - rename_metrics: + http.client.duration: http.client.request.duration + http.server.duration: http.server.request.duration + # https://github.com/open-telemetry/semantic-conventions/pull/241 + - rename_metrics: + process.runtime.jvm.memory.usage: jvm.memory.usage + process.runtime.jvm.memory.committed: jvm.memory.committed + process.runtime.jvm.memory.limit: jvm.memory.limit + process.runtime.jvm.memory.usage_after_last_gc: jvm.memory.usage_after_last_gc + process.runtime.jvm.gc.duration: jvm.gc.duration + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.threads.count: jvm.thread.count + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.classes.loaded: jvm.class.loaded + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + process.runtime.jvm.classes.unloaded: jvm.class.unloaded + # also https://github.com/open-telemetry/semantic-conventions/pull/252 + # and https://github.com/open-telemetry/semantic-conventions/pull/60 + process.runtime.jvm.classes.current_loaded: jvm.class.count + process.runtime.jvm.cpu.time: jvm.cpu.time + process.runtime.jvm.cpu.recent_utilization: jvm.cpu.recent_utilization + process.runtime.jvm.memory.init: jvm.memory.init + process.runtime.jvm.system.cpu.utilization: jvm.system.cpu.utilization + process.runtime.jvm.system.cpu.load_1m: jvm.system.cpu.load_1m + # https://github.com/open-telemetry/semantic-conventions/pull/253 + process.runtime.jvm.buffer.usage: jvm.buffer.memory.usage + # https://github.com/open-telemetry/semantic-conventions/pull/253 + process.runtime.jvm.buffer.limit: jvm.buffer.memory.limit + process.runtime.jvm.buffer.count: jvm.buffer.count + # https://github.com/open-telemetry/semantic-conventions/pull/20 + - rename_attributes: + attribute_map: + type: jvm.memory.type + pool: jvm.memory.pool.name + apply_to_metrics: + - jvm.memory.usage + - jvm.memory.committed + - jvm.memory.limit + - jvm.memory.usage_after_last_gc + - jvm.memory.init + - rename_attributes: + attribute_map: + name: jvm.gc.name + action: jvm.gc.action + apply_to_metrics: + - jvm.gc.duration + - rename_attributes: + attribute_map: + daemon: thread.daemon + apply_to_metrics: + - jvm.threads.count + - rename_attributes: + attribute_map: + pool: jvm.buffer.pool.name + apply_to_metrics: + - jvm.buffer.usage + - jvm.buffer.limit + - jvm.buffer.count + # https://github.com/open-telemetry/semantic-conventions/pull/89 + - rename_attributes: + attribute_map: + state: system.cpu.state + cpu: system.cpu.logical_number + apply_to_metrics: + - system.cpu.time + - system.cpu.utilization + - rename_attributes: + attribute_map: + state: system.memory.state + apply_to_metrics: + - system.memory.usage + - system.memory.utilization + - rename_attributes: + attribute_map: + state: system.paging.state + apply_to_metrics: + - system.paging.usage + - system.paging.utilization + - rename_attributes: + attribute_map: + type: system.paging.type + direction: system.paging.direction + apply_to_metrics: + - system.paging.faults + - system.paging.operations + - rename_attributes: + attribute_map: + device: system.device + direction: system.disk.direction + apply_to_metrics: + - system.disk.io + - system.disk.operations + - system.disk.io_time + - system.disk.operation_time + - system.disk.merged + - rename_attributes: + attribute_map: + device: system.device + state: system.filesystem.state + type: system.filesystem.type + mode: system.filesystem.mode + mountpoint: system.filesystem.mountpoint + apply_to_metrics: + - system.filesystem.usage + - system.filesystem.utilization + - rename_attributes: + attribute_map: + device: system.device + direction: system.network.direction + protocol: network.protocol + state: system.network.state + apply_to_metrics: + - system.network.dropped + - system.network.packets + - system.network.errors + - system.network.io + - system.network.connections + - rename_attributes: + attribute_map: + status: system.processes.status + apply_to_metrics: + - system.processes.count + # https://github.com/open-telemetry/semantic-conventions/pull/247 + - rename_metrics: + http.server.request.size: http.server.request.body.size + http.server.response.size: http.server.response.body.size + resources: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/178 + - rename_attributes: + attribute_map: + telemetry.auto.version: telemetry.distro.version + 1.21.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3336 + - rename_attributes: + attribute_map: + messaging.kafka.client_id: messaging.client_id + messaging.rocketmq.client_id: messaging.client_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3402 + - rename_attributes: + attribute_map: + # net.peer.(name|port) attributes were usually populated on client side + # so they should be usually translated to server.(address|port) + # net.host.* attributes were only populated on server side + net.host.name: server.address + net.host.port: server.port + # was only populated on client side + net.sock.peer.name: server.socket.domain + # net.sock.peer.(addr|port) mapping is not possible + # since they applied to both client and server side + # were only populated on server side + net.sock.host.addr: server.socket.address + net.sock.host.port: server.socket.port + http.client_ip: client.address + # https://github.com/open-telemetry/opentelemetry-specification/pull/3426 + - rename_attributes: + attribute_map: + net.protocol.name: network.protocol.name + net.protocol.version: network.protocol.version + net.host.connection.type: network.connection.type + net.host.connection.subtype: network.connection.subtype + net.host.carrier.name: network.carrier.name + net.host.carrier.mcc: network.carrier.mcc + net.host.carrier.mnc: network.carrier.mnc + net.host.carrier.icc: network.carrier.icc + # https://github.com/open-telemetry/opentelemetry-specification/pull/3355 + - rename_attributes: + attribute_map: + http.method: http.request.method + http.status_code: http.response.status_code + http.scheme: url.scheme + http.url: url.full + http.request_content_length: http.request.body.size + http.response_content_length: http.response.body.size + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/53 + - rename_metrics: + process.runtime.jvm.cpu.utilization: process.runtime.jvm.cpu.recent_utilization + 1.20.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3272 + - rename_attributes: + attribute_map: + net.app.protocol.name: net.protocol.name + net.app.protocol.version: net.protocol.version + 1.19.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3209 + - rename_attributes: + attribute_map: + faas.execution: faas.invocation_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3188 + - rename_attributes: + attribute_map: + faas.id: cloud.resource_id + # https://github.com/open-telemetry/opentelemetry-specification/pull/3190 + - rename_attributes: + attribute_map: + http.user_agent: user_agent.original + resources: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3190 + - rename_attributes: + attribute_map: + browser.user_agent: user_agent.original + 1.18.0: + 1.17.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2957 + - rename_attributes: + attribute_map: + messaging.consumer_id: messaging.consumer.id + messaging.protocol: net.app.protocol.name + messaging.protocol_version: net.app.protocol.version + messaging.destination: messaging.destination.name + messaging.temp_destination: messaging.destination.temporary + messaging.destination_kind: messaging.destination.kind + messaging.message_id: messaging.message.id + messaging.conversation_id: messaging.message.conversation_id + messaging.message_payload_size_bytes: messaging.message.payload_size_bytes + messaging.message_payload_compressed_size_bytes: messaging.message.payload_compressed_size_bytes + messaging.rabbitmq.routing_key: messaging.rabbitmq.destination.routing_key + messaging.kafka.message_key: messaging.kafka.message.key + messaging.kafka.partition: messaging.kafka.destination.partition + messaging.kafka.tombstone: messaging.kafka.message.tombstone + messaging.rocketmq.message_type: messaging.rocketmq.message.type + messaging.rocketmq.message_tag: messaging.rocketmq.message.tag + messaging.rocketmq.message_keys: messaging.rocketmq.message.keys + messaging.kafka.consumer_group: messaging.kafka.consumer.group + 1.16.0: + 1.15.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2743 + - rename_attributes: + attribute_map: + http.retry_count: http.resend_count + 1.14.0: + 1.13.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2614 + - rename_attributes: + attribute_map: + net.peer.ip: net.sock.peer.addr + net.host.ip: net.sock.host.addr + 1.12.0: + 1.11.0: + 1.10.0: + 1.9.0: + 1.8.0: + spans: + changes: + - rename_attributes: + attribute_map: + db.cassandra.keyspace: db.name + db.hbase.namespace: db.name + 1.7.0: + 1.6.1: + 1.5.0: + 1.4.0: