From 4362b16491184db55fa30c456a20a567d62d8249 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Fri, 23 Feb 2024 09:51:10 -0500 Subject: [PATCH 01/22] Add Alexandra to approver list. (#766) --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index f2b46980c0..89c9df4055 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) Approvers ([@open-telemetry/specs-semconv-approvers](https://github.com/orgs/open-telemetry/teams/specs-semconv-approvers)): +- [Alexandra Konrad](https://github.com/trisch-me), Elastic - [Christian Neumüller](https://github.com/Oberon00), Dynatrace - [James Moessis](https://github.com/jamesmoessis), Atlassian - [Johannes Tax](https://github.com/pyohannes), Grafana Labs From b825ce1b93c39abd628345d792f4e09ece8d2c63 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juraci=20Paix=C3=A3o=20Kr=C3=B6hling?= Date: Fri, 23 Feb 2024 20:02:08 +0100 Subject: [PATCH 02/22] Define a common algorithm for service.instance.id (#312) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Juraci Paixão Kröhling Co-authored-by: Josh Suereth --- .chloggen/service-instance-id.yaml | 4 +++ docs/resource/README.md | 29 +++++++++++++++-- model/resource/service_experimental.yaml | 41 ++++++++++++++++-------- 3 files changed, 59 insertions(+), 15 deletions(-) create mode 100644 .chloggen/service-instance-id.yaml diff --git a/.chloggen/service-instance-id.yaml b/.chloggen/service-instance-id.yaml new file mode 100644 index 0000000000..34acc9cf03 --- /dev/null +++ b/.chloggen/service-instance-id.yaml @@ -0,0 +1,4 @@ +change_type: 'enhancement' +component: resource +note: Define a common algorithm for `service.instance.id`. +issues: [312] diff --git a/docs/resource/README.md b/docs/resource/README.md index c67b8f3517..5dd529d264 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -99,10 +99,35 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `service.instance.id` | string | The string ID of the service instance. [1] | `my-k8s-pod-deployment-1`; `627cc493-f310-47de-96bd-71410b7dec09` | Recommended | +| `service.instance.id` | string | The string ID of the service instance. [1] | `627cc493-f310-47de-96bd-71410b7dec09` | Recommended | | `service.namespace` | string | A namespace for `service.name`. [2] | `Shop` | Recommended | -**[1]:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words `service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled service). It is preferable for the ID to be persistent and stay the same for the lifetime of the service instance, however it is acceptable that the ID is ephemeral and changes during important lifetime events for the service (e.g. service restarts). If the service has no inherent unique ID that can be used as the value of this attribute it is recommended to generate a random Version 1 or Version 4 RFC 4122 UUID (services aiming for reproducible UUIDs may also use Version 5, see RFC 4122 for more recommendations). +**[1]:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words +`service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to +distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled +service). + +Implementations, such as SDKs, are recommended to generate a random Version 1 or Version 4 [RFC +4122](https://www.ietf.org/rfc/rfc4122.txt) UUID, but are free to use an inherent unique ID as the source of +this value if stability is desirable. In that case, the ID SHOULD be used as source of a UUID Version 5 and +SHOULD use the following UUID as the namespace: `4d63009a-8d0f-11ee-aad7-4c796ed8e320`. + +UUIDs are typically recommended, as only an opaque value for the purposes of identifying a service instance is +needed. Similar to what can be seen in the man page for the +[`/etc/machine-id`](https://www.freedesktop.org/software/systemd/man/machine-id.html) file, the underlying +data, such as pod name and namespace should be treated as confidential, being the user's choice to expose it +or not via another resource attribute. + +For applications running behind an application server (like unicorn), we do not recommend using one identifier +for all processes participating in the application. Instead, it's recommended each division (e.g. a worker +thread in unicorn) to have its own instance.id. + +It's not recommended for a Collector to set `service.instance.id` if it can't unambiguously determine the +service instance that is generating that telemetry. For instance, creating an UUID based on `pod.name` will +likely be wrong, as the Collector might not know from which container within that pod the telemetry originated. +However, Collectors can set the `service.instance.id` if they can unambiguously determine the service instance +for that telemetry. This is typically the case for scraping receivers, as they know the target address and +port. **[2]:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. diff --git a/model/resource/service_experimental.yaml b/model/resource/service_experimental.yaml index 43c869ee35..99ed64f024 100644 --- a/model/resource/service_experimental.yaml +++ b/model/resource/service_experimental.yaml @@ -22,16 +22,31 @@ groups: type: string brief: > The string ID of the service instance. - note: > - MUST be unique for each instance of the same `service.namespace,service.name` pair - (in other words `service.namespace,service.name,service.instance.id` triplet MUST be globally unique). - The ID helps to distinguish instances of the same service that exist at the same time - (e.g. instances of a horizontally scaled service). It is preferable for the ID to be persistent - and stay the same for the lifetime of the service instance, however it is acceptable that - the ID is ephemeral and changes during important lifetime events for the service - (e.g. service restarts). - If the service has no inherent unique ID that can be used as the value of this attribute - it is recommended to generate a random Version 1 or Version 4 RFC 4122 UUID - (services aiming for reproducible UUIDs may also use Version 5, see RFC 4122 - for more recommendations). - examples: ["my-k8s-pod-deployment-1", "627cc493-f310-47de-96bd-71410b7dec09"] + note: | + MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words + `service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to + distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled + service). + + Implementations, such as SDKs, are recommended to generate a random Version 1 or Version 4 [RFC + 4122](https://www.ietf.org/rfc/rfc4122.txt) UUID, but are free to use an inherent unique ID as the source of + this value if stability is desirable. In that case, the ID SHOULD be used as source of a UUID Version 5 and + SHOULD use the following UUID as the namespace: `4d63009a-8d0f-11ee-aad7-4c796ed8e320`. + + UUIDs are typically recommended, as only an opaque value for the purposes of identifying a service instance is + needed. Similar to what can be seen in the man page for the + [`/etc/machine-id`](https://www.freedesktop.org/software/systemd/man/machine-id.html) file, the underlying + data, such as pod name and namespace should be treated as confidential, being the user's choice to expose it + or not via another resource attribute. + + For applications running behind an application server (like unicorn), we do not recommend using one identifier + for all processes participating in the application. Instead, it's recommended each division (e.g. a worker + thread in unicorn) to have its own instance.id. + + It's not recommended for a Collector to set `service.instance.id` if it can't unambiguously determine the + service instance that is generating that telemetry. For instance, creating an UUID based on `pod.name` will + likely be wrong, as the Collector might not know from which container within that pod the telemetry originated. + However, Collectors can set the `service.instance.id` if they can unambiguously determine the service instance + for that telemetry. This is typically the case for scraping receivers, as they know the target address and + port. + examples: ["627cc493-f310-47de-96bd-71410b7dec09"] From 4f434da570cda9c6ab7af3b5cfb797cfd2cbcd97 Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Mon, 26 Feb 2024 16:18:54 +0100 Subject: [PATCH 03/22] [chore] Attempt two: Avoid running stale bot on issues (#771) --- .github/workflows/stale-pr.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/stale-pr.yml b/.github/workflows/stale-pr.yml index c1b7f9370e..d5259a6140 100644 --- a/.github/workflows/stale-pr.yml +++ b/.github/workflows/stale-pr.yml @@ -14,5 +14,9 @@ jobs: close-pr-message: 'Closed as inactive. Feel free to reopen if this PR is still being worked on.' exempt-pr-labels: 'bug,work in progress,experts needed' exempt-draft-pr: true + # opt out of defaults to avoid marking issues as stale + days-before-stale: -1 + days-before-close: -1 + # overrides the above only for pull requests days-before-pr-stale: 15 days-before-pr-close: 7 From 399978fb27615d7751964b79bc43ad87fe290728 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Tue, 27 Feb 2024 11:36:26 -0500 Subject: [PATCH 04/22] Add Liudmila to semconv maintainers. (#776) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 89c9df4055..c200f36972 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,6 @@ Approvers ([@open-telemetry/specs-semconv-approvers](https://github.com/orgs/ope - [Christian Neumüller](https://github.com/Oberon00), Dynatrace - [James Moessis](https://github.com/jamesmoessis), Atlassian - [Johannes Tax](https://github.com/pyohannes), Grafana Labs -- [Liudmila Molkova](https://github.com/lmolkova), Microsoft - [Sean Marciniak](https://github.com/MovieStoreGuy), Atlassian - [Ted Young](https://github.com/tedsuo), Lightstep @@ -34,6 +33,7 @@ Maintainers ([@open-telemetry/specs-semconv-maintainers](https://github.com/orgs - [Armin Ruech](https://github.com/arminru), Dynatrace - [Joao Grassi](https://github.com/joaopgrassi), Dynatrace - [Josh Suereth](https://github.com/jsuereth), Google +- [Liudmila Molkova](https://github.com/lmolkova), Microsoft - [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)._ From f98fc43b1806e5a150a9a0fe266069e83b1b3af6 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 28 Feb 2024 07:24:34 -0800 Subject: [PATCH 05/22] [chore] Bring a few attributes that were removed back (as deprecated) (#770) --- docs/attributes-registry/network.md | 2 +- model/registry/deprecated/container.yaml | 10 ++++++++++ model/registry/deprecated/k8s.yaml | 10 ++++++++++ model/registry/deprecated/network.yaml | 2 +- model/registry/deprecated/system.yaml | 20 ++++++++++++++++++++ 5 files changed, 42 insertions(+), 2 deletions(-) create mode 100644 model/registry/deprecated/container.yaml create mode 100644 model/registry/deprecated/k8s.yaml create mode 100644 model/registry/deprecated/system.yaml diff --git a/docs/attributes-registry/network.md b/docs/attributes-registry/network.md index 9c388f4d75..a06417c9dc 100644 --- a/docs/attributes-registry/network.md +++ b/docs/attributes-registry/network.md @@ -100,7 +100,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. ## Deprecated Network Attributes - + | Attribute | Type | Description | Examples | |---|---|---|---| | `net.host.name` | string | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, use `server.address`. | `example.com` | diff --git a/model/registry/deprecated/container.yaml b/model/registry/deprecated/container.yaml new file mode 100644 index 0000000000..8c19e64f8b --- /dev/null +++ b/model/registry/deprecated/container.yaml @@ -0,0 +1,10 @@ +groups: + - id: attributes.container.deprecated + type: attribute_group + brief: "Describes deprecated container attributes." + attributes: + - id: container.labels + type: template[string] + examples: [ 'container.label.app=nginx' ] + brief: "Deprecated, use `container.label` instead." + deprecated: "Replaced by `container.label`." diff --git a/model/registry/deprecated/k8s.yaml b/model/registry/deprecated/k8s.yaml new file mode 100644 index 0000000000..5793257d7f --- /dev/null +++ b/model/registry/deprecated/k8s.yaml @@ -0,0 +1,10 @@ +groups: + - id: attributes.k8s.deprecated + type: attribute_group + brief: "Describes deprecated k8s attributes." + attributes: + - id: k8s.pod.labels + type: template[string] + examples: ['k8s.pod.label.app=my-app'] + brief: "Deprecated, use `k8s.pod.label` instead." + deprecated: "Replaced by `k8s.pod.label`." diff --git a/model/registry/deprecated/network.yaml b/model/registry/deprecated/network.yaml index 135373fa09..63e3959d7e 100644 --- a/model/registry/deprecated/network.yaml +++ b/model/registry/deprecated/network.yaml @@ -1,5 +1,5 @@ groups: - - id: network-deprecated + - id: attributes.network.deprecated prefix: net type: attribute_group brief: > diff --git a/model/registry/deprecated/system.yaml b/model/registry/deprecated/system.yaml new file mode 100644 index 0000000000..2356ebc562 --- /dev/null +++ b/model/registry/deprecated/system.yaml @@ -0,0 +1,20 @@ +groups: + - id: attributes.system.deprecated + type: attribute_group + brief: "Deprecated system attributes." + attributes: + - id: system.processes.status + type: + allow_custom_values: true + members: + - id: running + value: 'running' + - id: sleeping + value: 'sleeping' + - id: stopped + value: 'stopped' + - id: defunct + value: 'defunct' + brief: "Deprecated, use `system.process.status` instead." + deprecated: "Replaced by `system.process.status`." + examples: ["running"] From bdbcf68a9b29246948b69f7db42b9fbf70510a7b Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 28 Feb 2024 07:34:24 -0800 Subject: [PATCH 06/22] Double backslash -> Single backslash (#779) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- docs/resource/host.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/resource/host.md b/docs/resource/host.md index 9dfdd5d2b5..da04a28970 100644 --- a/docs/resource/host.md +++ b/docs/resource/host.md @@ -63,12 +63,12 @@ When collecting `host.id` for non-containerized systems non-privileged lookups of the machine id are preferred. SDK detector implementations MUST use the sources listed below to obtain the machine id. -| OS | Primary | Fallback | -|---------|-------------------------------------------------------------------------------------|----------------------------------------| -| Linux | contents of `/etc/machine-id` | contents of `/var/lib/dbus/machine-id` | -| BSD | contents of `/etc/hostid` | output of `kenv -q smbios.system.uuid` | -| MacOS | `IOPlatformUUID` line from the output of `ioreg -rd1 -c "IOPlatformExpertDevice"` | - | -| Windows | `MachineGuid` from registry `HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Cryptography` | - | +| OS | Primary | Fallback | +|---------|-----------------------------------------------------------------------------------|----------------------------------------| +| Linux | contents of `/etc/machine-id` | contents of `/var/lib/dbus/machine-id` | +| BSD | contents of `/etc/hostid` | output of `kenv -q smbios.system.uuid` | +| MacOS | `IOPlatformUUID` line from the output of `ioreg -rd1 -c "IOPlatformExpertDevice"` | - | +| Windows | `MachineGuid` from registry `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography` | - | ### Privileged Machine ID Lookup From b8e5dada01b345d6dea186b5c5aec0bdafafc038 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 28 Feb 2024 16:50:21 -0500 Subject: [PATCH 07/22] [chore] URL attributes: consistently use code font for URLs and URL parts (#783) --- docs/attributes-registry/url.md | 4 ++-- model/registry/url.yaml | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/attributes-registry/url.md b/docs/attributes-registry/url.md index 8c161e6648..b33926756b 100644 --- a/docs/attributes-registry/url.md +++ b/docs/attributes-registry/url.md @@ -35,9 +35,9 @@ linkTitle: URL **[5]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. -**[6]:** This value can be determined precisely with the [public suffix list](http://publicsuffix.org). For example, the registered domain for "foo.example.com" is "example.com". Trying to approximate this by simply taking the last two labels will not work well for TLDs such as "co.uk". +**[6]:** This value can be determined precisely with the [public suffix list](http://publicsuffix.org). For example, the registered domain for `foo.example.com` is `example.com`. Trying to approximate this by simply taking the last two labels will not work well for TLDs such as `co.uk`. -**[7]:** The subdomain portion of "www.east.mydomain.co.uk" is "east". If the domain has multiple levels of subdomain, such as "sub2.sub1.example.com", the subdomain field should contain "sub2.sub1", with no trailing period. +**[7]:** The subdomain portion of `www.east.mydomain.co.uk` is `east`. If the domain has multiple levels of subdomain, such as `sub2.sub1.example.com`, the subdomain field should contain `sub2.sub1`, with no trailing period. **[8]:** This value can be determined precisely with the [public suffix list](http://publicsuffix.org). \ No newline at end of file diff --git a/model/registry/url.yaml b/model/registry/url.yaml index 65dc2602bc..fdde8d2de0 100644 --- a/model/registry/url.yaml +++ b/model/registry/url.yaml @@ -79,8 +79,8 @@ groups: examples: ["example.com", "foo.co.uk"] note: > This value can be determined precisely with the [public suffix list](http://publicsuffix.org). - For example, the registered domain for "foo.example.com" is "example.com". - Trying to approximate this by simply taking the last two labels will not work well for TLDs such as "co.uk". + For example, the registered domain for `foo.example.com` is `example.com`. + Trying to approximate this by simply taking the last two labels will not work well for TLDs such as `co.uk`. - id: scheme stability: stable type: string @@ -95,8 +95,8 @@ groups: full name cannot be determined, subdomain contains all of the names below the registered domain. examples: ["east", "sub2.sub1"] note: > - The subdomain portion of "www.east.mydomain.co.uk" is "east". If the domain has multiple levels of subdomain, - such as "sub2.sub1.example.com", the subdomain field should contain "sub2.sub1", with no trailing period. + The subdomain portion of `www.east.mydomain.co.uk` is `east`. If the domain has multiple levels of subdomain, + such as `sub2.sub1.example.com`, the subdomain field should contain `sub2.sub1`, with no trailing period. - id: top_level_domain type: string brief: > From ca61ac1b2ba652ec21155676172c777e1979eb7b Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 29 Feb 2024 07:31:12 -0800 Subject: [PATCH 08/22] [chore] Mark otel.* attributes as stable in yaml (#784) --- model/scope/exporter/exporter.yaml | 2 ++ model/trace/exporter/exporter.yaml | 2 ++ 2 files changed, 4 insertions(+) diff --git a/model/scope/exporter/exporter.yaml b/model/scope/exporter/exporter.yaml index 3bbf3fe073..0a47d625a9 100644 --- a/model/scope/exporter/exporter.yaml +++ b/model/scope/exporter/exporter.yaml @@ -8,10 +8,12 @@ groups: type: string brief: The name of the instrumentation scope - (`InstrumentationScope.Name` in OTLP). examples: ['io.opentelemetry.contrib.mongodb'] + stability: stable - id: version type: string brief: The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). examples: ['1.0.0'] + stability: stable - id: otel.library prefix: otel.library type: resource diff --git a/model/trace/exporter/exporter.yaml b/model/trace/exporter/exporter.yaml index 2989475d71..23b5f921b3 100644 --- a/model/trace/exporter/exporter.yaml +++ b/model/trace/exporter/exporter.yaml @@ -15,7 +15,9 @@ groups: value: ERROR brief: 'The operation contains an error.' brief: Name of the code, either "OK" or "ERROR". MUST NOT be set if the status code is UNSET. + stability: stable - id: status_description type: string brief: "Description of the Status if it has a value, otherwise not set." examples: ['resource not found'] + stability: stable From 6659dfabfe35ce3f96a470eaa6a3678fbfb0a4d6 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Thu, 29 Feb 2024 20:24:31 -0500 Subject: [PATCH 09/22] Fix problem in `xray-lambda` propagator definition (#778) Co-authored-by: Raphael Philipe Mendes da Silva Co-authored-by: Trask Stalnaker Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/778.yaml | 22 +++++++++++++++++++++ docs/faas/aws-lambda.md | 42 ++++++++++++++++++++++++++--------------- 2 files changed, 49 insertions(+), 15 deletions(-) create mode 100644 .chloggen/778.yaml diff --git a/.chloggen/778.yaml b/.chloggen/778.yaml new file mode 100644 index 0000000000..03c1db8225 --- /dev/null +++ b/.chloggen/778.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: bug_fix + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: aws-lambda + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Fix problem in `xray-lambda` propagator definition + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [778] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index c8a568b378..45b68d67f3 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -70,37 +70,49 @@ Users MUST be able to [configure the propagator](#xray-lambda-propagator-configu SDK's that have instrumentation for AWS Lambda SHOULD provide an additional propagator alongside the X-Ray propagator that can [be configured](#xray-lambda-propagator-configuration) via the `OTEL_PROPAGATORS` environment variable setting as `xray-lambda`. -This propagator ignores the provided carrier instance and instead attempts to propagate the span context from the `_X_AMZN_TRACE_ID` environment variable -(and the `com.amazonaws.xray.traceHeader` system property for Java Lambda functions with priority given to the system property if set). - -To avoid potential issues when extracting with an active span context, the `xray-lambda` propagator SHOULD check if the provided context already has an active span context. If found, the propagator SHOULD return the provided context unmodified. - -Example pseudo implementation: +This propagator is expected to replace the `xray` propagator in the `OTEL_PROPAGATORS` list. The behavior for this propagator is described in pseudo code below. ``` extract(context, carrier) { + xrayContext = xrayPropagator.extract(context, carrier) + + // To avoid potential issues when extracting with an active span context (such as with a span link), + // the `xray-lambda` propagator SHOULD check if the provided context already has an active span context. + // If found, the propagator SHOULD just return the extract result of the `xray` propagator. if (Span.fromContext(context).getSpanContext().isValid()) - return context + return xrayContext - traceHeader = getEnvironment("_X_AMZN_TRACE_ID"); + // If xray-lambda environment variable not set, return the xray extract result. + traceHeader = getEnvironment("_X_AMZN_TRACE_ID") if (isEmptyOrNull(traceHeader)) - return context + return xrayContext - return xrayPropagator.extract(context, ["_X_AMZN_TRACE_ID": traceHeader]) + // Apply the xray propagator using the span context contained in the xray-lambda environment variable. + return xrayPropagator.extract(xrayContext, ["X-Amzn-Trace-Id": traceHeader]) } ``` +*Note:* Java implementations should use the system property value of the key `com.amazonaws.xray.traceHeader` +instead of the environment variable if the system property is not empty. + #### `xray-lambda` Propagator Configuration -Since propagators are invoked in order, users would give priority to X-Ray's "Active Tracing" span context by setting the environment variable: +**When reporting spans to AWS X-Ray** from AWS Lambda, the `xray-lambda` propagator SHOULD replace the `xray` propagator in the `OTEL_PROPAGATORS` configuration. Including both will prevent `xray-lambda` from functioning properly. + +Example valid configuration when reporting spans to AWS X-Ray: + +- `OTEL_PROPAGATORS=tracecontext,baggage,xray-lambda` + +Example invalid configurations: -`OTEL_PROPAGATORS=tracecontext,baggage,xray,xray-lambda` +- `OTEL_PROPAGATORS=tracecontext,baggage,xray,xray-lambda` +- `OTEL_PROPAGATORS=tracecontext,baggage,xray-lambda,xray` -To avoid broken traces, if OpenTelemetry is reporting traces to another system besides AWS X-Ray, users should either omit `xray-lambda` or add it to the beginning: +**When OpenTelemetry is reporting traces to another system besides AWS X-Ray**, users SHOULD NOT use `xray-lambda` or reported traces will be broken. -`OTEL_PROPAGATORS=xray-lambda,tracecontext,baggage,xray` +Example valid configuration when OpenTelemetry is reporting traces to another system besides AWS X-Ray: -*Note: The `xray-lambda` propagator can only `extract` context. The `inject` operation MUST be a no-op.* +- `OTEL_PROPAGATORS=tracecontext,baggage,xray` ## API Gateway From e4930d38613994ce6df0a88bcd5adbe4245c34dc Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 1 Mar 2024 00:42:58 -0800 Subject: [PATCH 10/22] Update Azure messaging: settlement attributes and span names (#697) Co-authored-by: Johannes Tax Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/697.yaml | 7 +++++++ docs/attributes-registry/messaging.md | 10 ++++++++++ docs/messaging/azure-messaging.md | 19 +++++++++++++++++++ model/registry/messaging.yaml | 20 ++++++++++++++++++++ model/trace/messaging.yaml | 3 +++ 5 files changed, 59 insertions(+) create mode 100644 .chloggen/697.yaml diff --git a/.chloggen/697.yaml b/.chloggen/697.yaml new file mode 100644 index 0000000000..e6bb861718 --- /dev/null +++ b/.chloggen/697.yaml @@ -0,0 +1,7 @@ +change_type: enhancement + +component: messaging + +note: Clarifies span names for Azure messaging systems and adds `messaging.servicebus.disposition_status attribute`. + +issues: [697] diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index e53250e0c4..c94f5aa3cb 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -157,6 +157,16 @@ size should be used. | Attribute | Type | Description | Examples | |---|---|---|---| | `messaging.servicebus.destination.subscription_name` | string | The name of the subscription in the topic messages are received from. | `mySubscription` | +| `messaging.servicebus.disposition_status` | string | Describes the [settlement type](https://learn.microsoft.com/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). | `complete` | | `messaging.servicebus.message.delivery_count` | int | Number of deliveries that have been attempted for this message. | `2` | | `messaging.servicebus.message.enqueued_time` | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | + +`messaging.servicebus.disposition_status` 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 | +|---|---| +| `complete` | Message is completed | +| `abandon` | Message is abandoned | +| `dead_letter` | Message is sent to dead letter queue | +| `defer` | Message is deferred | diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md index 35e17ec2c3..e7317d7b3a 100644 --- a/docs/messaging/azure-messaging.md +++ b/docs/messaging/azure-messaging.md @@ -12,6 +12,15 @@ The Semantic Conventions for [Azure Service Bus](https://learn.microsoft.com/azu `messaging.system` MUST be set to `"servicebus"`. +### Span names + +The span name SHOULD follow [the general messaging span name pattern](../messaging/azure-messaging.md): it SHOULD start with the messaging destination name (Event Hubs queue or topic name) and contain a low-cardinality name of the operation the span describes: + +- Spans names for `settle` operations SHOULD follow the ` {messaging.servicebus.disposition_status}` pattern. + For example, `my-queue complete` or `my-queue abandon`. +- Spans names for `publish` operations SHOULD follow the ` send` pattern. +- Spans for `create`, `receive`, and `publish` operations SHOULD follow the general ` ` pattern. + ### Span attributes The following additional attributes are defined: @@ -19,6 +28,7 @@ The following additional attributes are defined: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`messaging.servicebus.destination.subscription_name`](../attributes-registry/messaging.md) | string | The name of the subscription in the topic messages are received from. | `mySubscription` | Conditionally Required: If messages are received from the subscription. | +| [`messaging.servicebus.disposition_status`](../attributes-registry/messaging.md) | string | Describes the [settlement type](https://learn.microsoft.com/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). | `complete` | Conditionally Required: if and only if `messaging.operation` is `settle`. | | [`messaging.servicebus.message.delivery_count`](../attributes-registry/messaging.md) | int | Number of deliveries that have been attempted for this message. | `2` | Conditionally Required: [1] | | [`messaging.servicebus.message.enqueued_time`](../attributes-registry/messaging.md) | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | Recommended | @@ -29,6 +39,15 @@ The following additional attributes are defined: `messaging.system` MUST be set to `"eventhubs"`. +### Span names + +The span name SHOULD follow the [general messaging span name pattern](../messaging/azure-messaging.md): it SHOULD start with the messaging destination name (Event Hubs namespace) and +contain a low-cardinality name of an operation the span describes: + +- Spans for `settle` operations SHOULD follow the ` checkpoint` pattern (matching Event Hubs terminology). +- Spans names for `publish` operations SHOULD follow the ` send` pattern. +- Spans for `create`, `receive`, and `publish` operations SHOULD follow the general ` ` pattern. + ### Span attributes The following additional attributes are defined: diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index 33d2d2ac4f..d05b5cc71d 100644 --- a/model/registry/messaging.yaml +++ b/model/registry/messaging.yaml @@ -298,6 +298,26 @@ groups: The name of the subscription in the topic messages are received from. examples: "mySubscription" tag: tech-specific-servicebus + - id: servicebus.disposition_status + brief: > + Describes the [settlement type](https://learn.microsoft.com/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). + type: + allow_custom_values: true + members: + - id: complete + value: 'complete' + brief: 'Message is completed' + - id: abandon + value: 'abandon' + brief: 'Message is abandoned' + - id: dead_letter + value: 'dead_letter' + brief: 'Message is sent to dead letter queue' + - id: defer + value: 'defer' + brief: 'Message is deferred' + stability: experimental + tag: tech-specific-servicebus - id: eventhubs.message.enqueued_time type: int brief: > diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index 6252c0830b..f5b08b74f8 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -181,6 +181,9 @@ groups: - ref: messaging.servicebus.destination.subscription_name requirement_level: conditionally_required: If messages are received from the subscription. + - ref: messaging.servicebus.disposition_status + requirement_level: + conditionally_required: if and only if `messaging.operation` is `settle`. - id: messaging.eventhubs type: attribute_group extends: messaging From 9e90894cfac44045f1bcddb6169023af01204ad4 Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Fri, 1 Mar 2024 09:53:51 +0100 Subject: [PATCH 11/22] [chore] Add recommendation for lowercase attribute names (#788) --- docs/general/attribute-naming.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/general/attribute-naming.md b/docs/general/attribute-naming.md index b84f71f03e..f0eec71dbb 100644 --- a/docs/general/attribute-naming.md +++ b/docs/general/attribute-naming.md @@ -31,6 +31,8 @@ particular programming language or wire format._ Names SHOULD follow these rules: +- Names SHOULD be lowercase. + - 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. From 58c2705b7c93ea529d11db991e7ae4ad175473e1 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 1 Mar 2024 04:42:23 -0800 Subject: [PATCH 12/22] Merge DB connection-level and call-level attributes (#780) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/780.yaml | 4 + docs/database/cassandra.md | 4 +- docs/database/cosmosdb.md | 4 +- docs/database/couchdb.md | 4 +- docs/database/database-metrics.md | 18 ++--- docs/database/database-spans.md | 57 ++++++-------- docs/database/elasticsearch.md | 4 +- docs/database/hbase.md | 4 +- docs/database/mongodb.md | 4 +- docs/database/mssql.md | 7 +- docs/database/redis.md | 4 +- docs/database/sql.md | 5 +- model/messaging-common.yaml | 2 - model/metrics/database-metrics.yaml | 2 +- model/trace/database.yaml | 113 +++++++++++----------------- model/trace/messaging.yaml | 4 - 16 files changed, 106 insertions(+), 134 deletions(-) create mode 100644 .chloggen/780.yaml diff --git a/.chloggen/780.yaml b/.chloggen/780.yaml new file mode 100644 index 0000000000..626e967153 --- /dev/null +++ b/.chloggen/780.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: db +note: Merge DB connection-level and call-level attributes tables +issues: [780] diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index 0fcc385c82..6193ee0d21 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -12,9 +12,9 @@ described on this page. `db.system` MUST be set to `"cassandra"`. -## Call-level attributes +## Attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`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 | diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 1862a1efa7..51fc4ba2f9 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -11,13 +11,13 @@ extend and override the [Database Semantic Conventions](database-spans.md) that describe common database operations attributes in addition to the Semantic Conventions described on this page. -## Call-level attributes +## Attributes `db.system` MUST be set to `"cosmosdb"`. 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`](../attributes-registry/db.md) | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` | Recommended | diff --git a/docs/database/couchdb.md b/docs/database/couchdb.md index 8025aacd08..5ad2aae166 100644 --- a/docs/database/couchdb.md +++ b/docs/database/couchdb.md @@ -12,9 +12,9 @@ described on this page. `db.system` MUST be set to `"couchdb"`. -## Call-level attributes +## Attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`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. | diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 54c9e92927..1f21ddf074 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -52,7 +52,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 doesn't 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#common-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: @@ -75,7 +75,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 doesn't 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#common-attributes) should be used | `myDataSource` | Required | ### Metric: `db.client.connections.idle.min` @@ -91,7 +91,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 doesn't 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#common-attributes) should be used | `myDataSource` | Required | ### Metric: `db.client.connections.max` @@ -107,7 +107,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 doesn't 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#common-attributes) should be used | `myDataSource` | Required | ### Metric: `db.client.connections.pending_requests` @@ -123,7 +123,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 doesn't 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#common-attributes) should be used | `myDataSource` | Required | ### Metric: `db.client.connections.timeouts` @@ -139,7 +139,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 doesn't 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#common-attributes) should be used | `myDataSource` | Required | ### Metric: `db.client.connections.create_time` @@ -155,7 +155,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 doesn't 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#common-attributes) should be used | `myDataSource` | Required | ### Metric: `db.client.connections.wait_time` @@ -171,7 +171,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 doesn't 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#common-attributes) should be used | `myDataSource` | Required | ### Metric: `db.client.connections.use_time` @@ -187,7 +187,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 doesn't 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#common-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 d5c2e54d32..e8e224fc74 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -10,9 +10,8 @@ linkTitle: Client Calls -- [Connection-level attributes](#connection-level-attributes) +- [Common attributes](#common-attributes) * [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem) -- [Call-level attributes](#call-level-attributes) - [Semantic Conventions for specific database technologies](#semantic-conventions-for-specific-database-technologies) @@ -62,38 +61,51 @@ It is not recommended to attempt any client-side parsing of `db.statement` just they should only be used if the library being instrumented already provides them. When it's otherwise impossible to get any meaningful span name, `db.name` or the tech-specific database name MAY be used. -## Connection-level attributes +Span that describes database call SHOULD cover the duration of the corresponding call as if it was observed by the caller (such as client application). +For example, if a transient issue happened and was retried within this database call, the corresponding span should cover the duration of the logical operation +with all retries. + +## Common attributes These attributes will usually be the same for all operations performed over the same database connection. Some database systems may allow a connection to switch to a different `db.user`, for example, and other database systems may not even have the concept of a connection at all. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`db.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.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] | | [`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] | +| [`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). [4] | `tcp`; `udp` | Recommended | +| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [5] | `ipv4`; `ipv6` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Name of the database host. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.md) | int | Server port number. [7] | `80`; `8080`; `443` | Conditionally Required: [8] | -**[1]:** The value SHOULD be normalized to lowercase. +**[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. + +**[3]:** Should be collected by default only if there is sanitization that excludes sensitive information. + +**[4]:** 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. -**[2]:** The value SHOULD be normalized to lowercase. +**[5]:** 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, for example proxies, if it's available. +**[6]:** 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, for example proxies, if it's available. +**[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. -**[5]:** If using a port other than the default port for this DBMS and if `server.address` is set. +**[8]:** If using a port other than the default port for this DBMS and if `server.address` is set. `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. @@ -187,25 +199,6 @@ Back ends could, for example, use the provided identifier to determine the appro When additional attributes are added that only apply to a specific DBMS, its identifier SHOULD be used as a namespace in the attribute key as for the attributes in the sections below. -## Call-level attributes - -These attributes may be different for each operation performed, even if the same connection is used for multiple operations. -Usually only one `db.name` will be used per connection though. - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`db.name`](../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). - -**[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. - -**[3]:** Should be collected by default only if there is sanitization that excludes sensitive information. - - ## Semantic Conventions for specific database technologies More specific Semantic Conventions are defined for the following database technologies: diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 156e7cb15f..ccea388ecc 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -21,9 +21,9 @@ name, as the path could contain dynamic values. The endpoint id is the `name` fi [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json). If the endpoint id is not available, the span name SHOULD be the `http.request.method`. -## Call-level attributes +## Attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`db.elasticsearch.cluster.name`](../attributes-registry/db.md) | string | Represents the identifier of an Elasticsearch cluster. | `e9106fc68e3044f0b1475b04bf4ffd5f` | Recommended: [1] | diff --git a/docs/database/hbase.md b/docs/database/hbase.md index 47b8acd2c5..50675d6b91 100644 --- a/docs/database/hbase.md +++ b/docs/database/hbase.md @@ -12,9 +12,9 @@ described on this page. `db.system` MUST be set to `"hbase"`. -## Call-level attributes +## Attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`db.name`](../attributes-registry/db.md) | string | The HBase namespace. [1] | `mynamespace` | Conditionally Required: If applicable. | diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index 10fdbb785e..ebb2a5a883 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -12,9 +12,9 @@ described on this page. `db.system` MUST be set to `"mongodb"`. -## Call-level attributes +## Attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`db.mongodb.collection`](../attributes-registry/db.md) | string | The MongoDB collection being accessed within the database stated in `db.name`. | `customers`; `products` | Required | diff --git a/docs/database/mssql.md b/docs/database/mssql.md index 239be3960b..6eeaf08030 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -12,15 +12,18 @@ described on this page. `db.system` MUST be set to `"mssql"`. -## Connection-level attributes +## Attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`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 | +| [`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). [2] | `public.users`; `customers` | Recommended | **[1]:** If setting a `db.mssql.instance_name`, `server.port` is no longer required (but still recommended if non-standard). + +**[2]:** 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. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/database/redis.md b/docs/database/redis.md index 2614e494fa..62637688e3 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -12,9 +12,9 @@ described on this page. `db.system` MUST be set to `"redis"`. -## Call-level attributes +## Attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`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`). | diff --git a/docs/database/sql.md b/docs/database/sql.md index 6483e36374..5eaddacf39 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -10,11 +10,12 @@ The SQL databases Semantic Conventions extend and override the [Database Semanti that describe common database operations attributes in addition to the Semantic Conventions described on this page. -## Call-level attributes +## Attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| [`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.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. diff --git a/model/messaging-common.yaml b/model/messaging-common.yaml index 92bddd7924..f5505a0baf 100644 --- a/model/messaging-common.yaml +++ b/model/messaging-common.yaml @@ -20,6 +20,4 @@ groups: examples: ['amqp', 'mqtt'] requirement_level: conditionally_required: Only for messaging systems and frameworks that support more than one protocol. - 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 3df6d86a2c..097ff79abf 100644 --- a/model/metrics/database-metrics.yaml +++ b/model/metrics/database-metrics.yaml @@ -20,7 +20,7 @@ groups: brief: > 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) + then the [db.connection_string](/docs/database/database-spans.md#common-attributes) should be used examples: ["myDataSource"] diff --git a/model/trace/database.yaml b/model/trace/database.yaml index a896527ac7..8637fbed28 100644 --- a/model/trace/database.yaml +++ b/model/trace/database.yaml @@ -6,95 +6,80 @@ groups: span_kind: client attributes: - ref: db.system - tag: connection-level requirement_level: required - ref: db.connection_string - tag: connection-level - ref: db.user - tag: connection-level - - ref: db.jdbc.driver_classname - tag: connection-level-tech-specific - ref: db.name - tag: call-level requirement_level: conditionally_required: If applicable. - ref: db.statement - tag: call-level requirement_level: recommended: > Should be collected by default only if there is sanitization that excludes sensitive information. - ref: db.operation - tag: call-level requirement_level: conditionally_required: If `db.statement` is not applicable. - ref: server.address - tag: connection-level brief: > Name of the database host. - ref: server.port - tag: connection-level 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 - tag: connection-level - ref: network.peer.port requirement_level: recommended: If `network.peer.address` is set. - tag: connection-level - ref: network.transport - 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 type: span - extends: db + extends: db.sql brief: > - Connection-level attributes for Microsoft SQL Server + Attributes for Microsoft SQL Server attributes: - ref: db.mssql.instance_name - tag: connection-level-tech-specific + tag: tech-specific - id: db.cassandra type: span extends: db brief: > - Call-level attributes for Cassandra + Attributes for Cassandra attributes: - ref: db.name - tag: call-level-tech-specific-cassandra + tag: tech-specific brief: > The keyspace name in Cassandra. examples: ["mykeyspace"] note: For Cassandra the `db.name` should be set to the Cassandra keyspace name. - ref: db.cassandra.page_size - tag: call-level-tech-specific-cassandra + tag: tech-specific - ref: db.cassandra.consistency_level - tag: call-level-tech-specific-cassandra + tag: tech-specific - ref: db.cassandra.table - tag: call-level-tech-specific-cassandra + tag: tech-specific - ref: db.cassandra.idempotence - tag: call-level-tech-specific-cassandra + tag: tech-specific - ref: db.cassandra.speculative_execution_count - tag: call-level-tech-specific-cassandra + tag: tech-specific - ref: db.cassandra.coordinator.id - tag: call-level-tech-specific-cassandra + tag: tech-specific - ref: db.cassandra.coordinator.dc - tag: call-level-tech-specific-cassandra + tag: tech-specific - id: db.hbase type: span extends: db brief: > - Call-level attributes for HBase + Attributes for HBase attributes: - ref: db.name - tag: call-level-tech-specific + tag: tech-specific brief: > The HBase namespace. examples: ['mynamespace'] @@ -104,10 +89,10 @@ groups: type: span extends: db brief: > - Call-level attributes for CouchDB + Attributes for CouchDB attributes: - ref: db.operation - tag: call-level-tech-specific + tag: tech-specific brief: > The HTTP method + the target REST route. examples: ['GET /{db}/{docid}'] @@ -122,14 +107,14 @@ groups: type: span extends: db brief: > - Call-level attributes for Redis + Attributes for Redis attributes: - ref: db.redis.database_index requirement_level: conditionally_required: If other than the default database (`0`). - tag: call-level-tech-specific + tag: tech-specific - ref: db.statement - tag: call-level-tech-specific + tag: tech-specific brief: > The full syntax of the Redis CLI command. examples: ["HMSET myhash field1 'Hello' field2 'World'"] @@ -141,30 +126,30 @@ groups: type: span extends: db brief: > - Call-level attributes for MongoDB + Attributes for MongoDB attributes: - ref: db.mongodb.collection requirement_level: required - tag: call-level-tech-specific + tag: tech-specific - id: db.elasticsearch type: span extends: db brief: > - Call-level attributes for Elasticsearch + Attributes for Elasticsearch attributes: - ref: http.request.method requirement_level: required - tag: call-level-tech-specific + tag: 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 + tag: tech-specific - ref: url.full requirement_level: required examples: [ 'https://localhost:9200/index/_search?q=user.id:kimchy' ] - tag: call-level-tech-specific + tag: tech-specific - ref: db.statement requirement_level: recommended: > @@ -172,48 +157,50 @@ 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 + tag: tech-specific - ref: server.address - tag: call-level-tech-specific + tag: tech-specific - ref: server.port - tag: call-level-tech-specific + tag: 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 + tag: tech-specific - 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 + tag: tech-specific - ref: db.elasticsearch.path_parts requirement_level: conditionally_required: when the url has dynamic values - tag: call-level-tech-specific + tag: tech-specific - id: db.sql type: span extends: 'db' brief: > - Call-level attributes for SQL databases + Attributes for SQL databases attributes: - ref: db.sql.table - tag: call-level-tech-specific + tag: tech-specific + - ref: db.jdbc.driver_classname + tag: tech-specific - id: db.cosmosdb type: span extends: db prefix: db.cosmosdb brief: > - Call-level attributes for Cosmos DB. + Attributes for Cosmos DB. attributes: - ref: db.cosmosdb.client_id - tag: call-level-tech-specific + tag: 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 + tag: tech-specific - ref: user_agent.original brief: 'Full user-agent string is generated by Cosmos DB SDK' note: > @@ -228,36 +215,26 @@ 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\|'] - tag: call-level-tech-specific + tag: tech-specific - ref: db.cosmosdb.connection_mode requirement_level: conditionally_required: if not `direct` (or pick gw as default) - tag: call-level-tech-specific + tag: tech-specific - ref: db.cosmosdb.container requirement_level: conditionally_required: if available - tag: call-level-tech-specific + tag: tech-specific - ref: db.cosmosdb.request_content_length - tag: call-level-tech-specific + tag: tech-specific - ref: db.cosmosdb.status_code requirement_level: conditionally_required: if response was received - tag: call-level-tech-specific + tag: tech-specific - ref: db.cosmosdb.sub_status_code requirement_level: conditionally_required: when response was received and contained sub-code. - tag: call-level-tech-specific + tag: tech-specific - ref: db.cosmosdb.request_charge requirement_level: conditionally_required: when available - tag: call-level-tech-specific - - - id: db.tech - type: span - brief: "Semantic convention group for specific technologies" - constraints: - - include: 'db.cassandra' - - include: 'db.redis' - - include: 'db.mongodb' - - include: 'db.sql' - - include: 'db.cosmosdb' + tag: tech-specific diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index f5b08b74f8..3a8543d540 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -82,15 +82,11 @@ groups: - ref: messaging.message.body.size - ref: server.address - ref: network.peer.address - tag: connection-level - ref: network.peer.port requirement_level: recommended: If `network.peer.address` is set. - tag: connection-level - ref: network.transport - tag: connection-level - ref: network.type - tag: connection-level - id: messaging.rabbitmq type: attribute_group From 44690f11c7edf9b916f8486f9a4440b841312cb0 Mon Sep 17 00:00:00 2001 From: klauco Date: Sat, 2 Mar 2024 01:03:01 +0100 Subject: [PATCH 13/22] Allow url.path sanitization (#676) Co-authored-by: Trask Stalnaker Co-authored-by: Liudmila Molkova --- .chloggen/allow-sanitizing-url-path.yaml | 22 ++++++++++++++++++++++ docs/attributes-registry/url.md | 22 ++++++++++++---------- docs/database/elasticsearch.md | 2 +- docs/http/http-spans.md | 14 ++++++++------ docs/url/url.md | 10 ++++++---- model/registry/url.yaml | 8 +++++--- 6 files changed, 54 insertions(+), 24 deletions(-) create mode 100644 .chloggen/allow-sanitizing-url-path.yaml diff --git a/.chloggen/allow-sanitizing-url-path.yaml b/.chloggen/allow-sanitizing-url-path.yaml new file mode 100644 index 0000000000..29d4311168 --- /dev/null +++ b/.chloggen/allow-sanitizing-url-path.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: url + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Sensitive content provided in `url.full`, `url.path`, and `url.query` SHOULD be scrubbed when instrumentations can identify it. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [676] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/attributes-registry/url.md b/docs/attributes-registry/url.md index b33926756b..d2aa233eeb 100644 --- a/docs/attributes-registry/url.md +++ b/docs/attributes-registry/url.md @@ -14,13 +14,13 @@ linkTitle: URL | `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) [3] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | | `url.original` | string | Unmodified original URL as seen in the event source. [4] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `search?q=OpenTelemetry` | -| `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.path` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [5] | `/search` | | `url.port` | int | Port extracted from the `url.full` | `443` | -| `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 [5] | `q=OpenTelemetry` | -| `url.registered_domain` | string | The highest registered url domain, stripped of the subdomain. [6] | `example.com`; `foo.co.uk` | +| `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 [6] | `q=OpenTelemetry` | +| `url.registered_domain` | string | The highest registered url domain, stripped of the subdomain. [7] | `example.com`; `foo.co.uk` | | `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` | -| `url.subdomain` | string | The subdomain portion of a fully qualified domain name includes all of the names except the host name under the registered_domain. In a partially qualified domain, or if the the qualification level of the full name cannot be determined, subdomain contains all of the names below the registered domain. [7] | `east`; `sub2.sub1` | -| `url.top_level_domain` | string | The effective top level domain (eTLD), also known as the domain suffix, is the last part of the domain name. For example, the top level domain for example.com is `com`. [8] | `com`; `co.uk` | +| `url.subdomain` | string | The subdomain portion of a fully qualified domain name includes all of the names except the host name under the registered_domain. In a partially qualified domain, or if the the qualification level of the full name cannot be determined, subdomain contains all of the names below the registered domain. [8] | `east`; `sub2.sub1` | +| `url.top_level_domain` | string | The effective top level domain (eTLD), also known as the domain suffix, is the last part of the domain name. For example, the top level domain for example.com is `com`. [9] | `com`; `co.uk` | **[1]:** In some cases a URL may refer to an IP and/or port directly, without a domain name. In this case, the IP address would go to the domain field. If the URL contains a [literal IPv6 address](https://www.rfc-editor.org/rfc/rfc2732#section-2) enclosed by `[` and `]`, the `[` and `]` characters should also be captured in the domain field. @@ -28,16 +28,18 @@ linkTitle: URL **[3]:** 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. +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. **[4]:** In network monitoring, the observed URL may be a full URL, whereas in access logs, the URL is often just represented as a path. This field is meant to represent the URL as it was observed, complete or not. `url.original` might contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case password and username SHOULD NOT be redacted and attribute's value SHOULD remain the same. -**[5]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. +**[5]:** Sensitive content provided in `url.path` SHOULD be scrubbed when instrumentations can identify it. -**[6]:** This value can be determined precisely with the [public suffix list](http://publicsuffix.org). For example, the registered domain for `foo.example.com` is `example.com`. Trying to approximate this by simply taking the last two labels will not work well for TLDs such as `co.uk`. +**[6]:** Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it. -**[7]:** The subdomain portion of `www.east.mydomain.co.uk` is `east`. If the domain has multiple levels of subdomain, such as `sub2.sub1.example.com`, the subdomain field should contain `sub2.sub1`, with no trailing period. +**[7]:** This value can be determined precisely with the [public suffix list](http://publicsuffix.org). For example, the registered domain for `foo.example.com` is `example.com`. Trying to approximate this by simply taking the last two labels will not work well for TLDs such as `co.uk`. -**[8]:** This value can be determined precisely with the [public suffix list](http://publicsuffix.org). +**[8]:** The subdomain portion of `www.east.mydomain.co.uk` is `east`. If the domain has multiple levels of subdomain, such as `sub2.sub1.example.com`, the subdomain field should contain `sub2.sub1`, with no trailing period. + +**[9]:** This value can be determined precisely with the [public suffix list](http://publicsuffix.org). \ No newline at end of file diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index ccea388ecc..e7bd336158 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -69,7 +69,7 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[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. +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. `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 3e11eb8704..4b5edb5b99 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -246,7 +246,7 @@ The attribute value MUST consist of either multiple header values as an array of **[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. +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): @@ -346,9 +346,9 @@ For an HTTP server span, `SpanKind` MUST be `Server`. | [`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 | +| [`url.path`](../attributes-registry/url.md) | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [7] | `/search` | Required | +| [`url.query`](../attributes-registry/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`](../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 | | [`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`; `YourApp/1.0.0 grpc-java-okhttp/1.27.2` | 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. @@ -366,9 +366,11 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin **[6]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). -**[7]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. +**[7]:** Sensitive content provided in `url.path` 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. +**[8]:** Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it. + +**[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. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): diff --git a/docs/url/url.md b/docs/url/url.md index f9605574ee..77cdbf1109 100644 --- a/docs/url/url.md +++ b/docs/url/url.md @@ -27,15 +27,17 @@ This document defines semantic conventions that describe URL and its components. |---|---|---|---|---| | [`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.path`](../attributes-registry/url.md) | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [2] | `/search` | Recommended | +| [`url.query`](../attributes-registry/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [3] | `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. +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. -**[2]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. +**[2]:** Sensitive content provided in `url.path` SHOULD be scrubbed when instrumentations can identify it. + +**[3]:** Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it. ## Sensitive information diff --git a/model/registry/url.yaml b/model/registry/url.yaml index fdde8d2de0..7e07ad7936 100644 --- a/model/registry/url.yaml +++ b/model/registry/url.yaml @@ -39,8 +39,8 @@ groups: `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. + `url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). + Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv', '//localhost'] - id: original type: string @@ -59,6 +59,8 @@ groups: brief: > The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component examples: ["/search"] + note: > + Sensitive content provided in `url.path` SHOULD be scrubbed when instrumentations can identify it. - id: port type: int brief: > @@ -71,7 +73,7 @@ groups: 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. + Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it. - id: registered_domain type: string brief: > From 19f2ba7d0c0b0adc1b9efb8ab189c5300e038e4d Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Mon, 4 Mar 2024 14:38:44 +0100 Subject: [PATCH 14/22] Add a "Process" operation for messaging (#700) Co-authored-by: Alex Hong <9397363+hongalex@users.noreply.github.com> Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/700.yaml | 22 +++++++++++++++ docs/attributes-registry/messaging.md | 3 ++- docs/messaging/messaging-metrics.md | 25 ++++++++--------- docs/messaging/messaging-spans.md | 39 +++++++++++++++------------ model/metrics/messaging.yaml | 12 ++++----- model/registry/messaging.yaml | 9 ++++--- 6 files changed, 71 insertions(+), 39 deletions(-) create mode 100644 .chloggen/700.yaml diff --git a/.chloggen/700.yaml b/.chloggen/700.yaml new file mode 100644 index 0000000000..5272119136 --- /dev/null +++ b/.chloggen/700.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: messaging + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add a "Process" spans and metrics for messaging + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [657] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index c94f5aa3cb..4d349029b7 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -60,7 +60,8 @@ size should be used. | `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. | +| `process` | One or more messages are delivered to or processed by a consumer. | +| `settle` | One or more messages are settled. | `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. diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md index 63bb6b384e..d715d1100d 100644 --- a/docs/messaging/messaging-metrics.md +++ b/docs/messaging/messaging-metrics.md @@ -13,8 +13,8 @@ - [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) + * [Metric: `messaging.process.duration`](#metric-messagingprocessduration) + * [Metric: `messaging.process.messages`](#metric-messagingprocessmessages) @@ -158,34 +158,35 @@ _Note: The need to report `messaging.receive.messages` depends on the messaging | `messaging.receive.messages` | Counter | `{message}` | Measures the number of received messages. | -### Metric: `messaging.deliver.duration` +### Metric: `messaging.process.duration` -This metric is [required][MetricRequired] for operations are not initiated by the application code (push-based deliver). +This metric is [required][MetricRequired] for operations that are not initiated by the application code (push-based deliver), and [recommended][MetricRecommended] for processing operations instrumented for pull-based scenarios. -When this metric is reported alongside a messaging deliver span, the metric value SHOULD be the same as the corresponding span duration. +When this metric is reported alongside a messaging process 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. | +| `messaging.process.duration` | Histogram | `s` | Measures the duration of process operation. | -### Metric: `messaging.deliver.messages` +### Metric: `messaging.process.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. +This metric is [required][MetricRequired] for batch process operations, and [recommended][MetricRecommended] for batch processing operations instrumented for pull-based scenarios. It's [opt-in][MetricOptIn] when the messaging system does not support batch processing since the message count can be derived from the `messaging.process.duration` histogram. -_Note: The need to report `messaging.deliver.messages` depends on the messaging system capabilities and not application scenarios or client library limitations._ +_Note: The need to report `messaging.process.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. | +| `messaging.process.messages` | Counter | `{message}` | Measures the number of processed 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 +[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/metrics/metric-requirement-level.md#recommended [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 14ee11002d..b93932c8b6 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -173,7 +173,7 @@ Examples: * `shop.orders receive` * `shop.orders settle` * `print_jobs publish` -* `topic with spaces deliver` +* `topic with spaces process` * `AuthenticationRequest-Conversations settle` * `(anonymous) publish` (`(anonymous)` being a stable identifier for an unnamed destination) @@ -188,7 +188,7 @@ The following operations related to messages are defined for these semantic conv | `create` | A message is created or passed to a client library for publishing. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. | | `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. | | `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. | +| `process` | One or more messages are delivered to or processed by a consumer. | | `settle` | One or more messages are settled. | ### Span kind @@ -201,7 +201,7 @@ SHOULD be set according to the following table, based on the operation a span de | `create` | `PRODUCER` | | `publish` | `PRODUCER` if the context of the "Publish" span is used as creation context. | | `receive` | `CONSUMER` | -| `deliver` | `CONSUMER` | +| `process` | `CONSUMER` for push-based scenarios where no `receive` span exists. | 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), @@ -237,22 +237,26 @@ into a message either from a "Create" span or as a custom creation context. #### 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 +"Process" 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). Such "Process" span covers the duration of such an +operation, which is usually a callback or handler. + +"Process" spans MAY be created in addition to "Receive" spans for pull-based +scenarios for operations of processing messages. Such spans could be created by +application code, or by abstraction layers built on top of messaging SDKs. + +"Receive" or "Process" 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 +A single "Process" 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 +messages were received). For each message it accounts for, the "Process" or "Receive" span SHOULD link to the message's creation context. "Settle" spans SHOULD be created for every manually or automatically triggered @@ -375,7 +379,8 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | `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. | +| `process` | One or more messages are delivered to or processed by a consumer. | +| `settle` | One or more messages are settled. | `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. @@ -479,11 +484,11 @@ flowchart LR; end subgraph CONSUMER1 direction TB - R1[Span Deliver A 1] + R1[Span Process A 1] end subgraph CONSUMER2 direction TB - R2[Span Deliver A 2] + R2[Span Process A 2] end P-. link .-R1; P-. link .-R2; @@ -493,9 +498,9 @@ flowchart LR; linkStyle 0,1 color:green,stroke:green ``` -| Field or Attribute | Span Publish A | Span Deliver A 1| Span Deliver A 2 | +| Field or Attribute | Span Publish A | Span Process A 1| Span Process A 2 | |-|-|-|-| -| Span name | `T publish` | `T deliver` | `T deliver` | +| Span name | `T publish` | `T process` | `T process` | | Parent | | | | | Links | | `T publish` | `T publish` | | SpanKind | `PRODUCER` | `CONSUMER` | `CONSUMER` | @@ -503,7 +508,7 @@ flowchart LR; | `server.port` | `1234` | `1234` | `1234` | | `messaging.system` | `"rabbitmq"` | `"rabbitmq"` | `"rabbitmq"` | | `messaging.destination.name` | `"T"` | `"T"` | `"T"` | -| `messaging.operation` | `"publish"` | `"deliver"` | `"deliver"` | +| `messaging.operation` | `"publish"` | `"process"` | `"process"` | | `messaging.message.id` | `"a"` | `"a"`| `"a"` | ### Batch receiving diff --git a/model/metrics/messaging.yaml b/model/metrics/messaging.yaml index 2d2f2a29ef..18079b3a52 100644 --- a/model/metrics/messaging.yaml +++ b/model/metrics/messaging.yaml @@ -28,10 +28,10 @@ groups: unit: "s" extends: metric.messaging.attributes - - id: metric.messaging.deliver.duration + - id: metric.messaging.process.duration type: metric - metric_name: messaging.deliver.duration - brief: "Measures the duration of deliver operation." + metric_name: messaging.process.duration + brief: "Measures the duration of process operation." instrument: histogram unit: "s" extends: metric.messaging.attributes @@ -53,10 +53,10 @@ groups: unit: "{message}" extends: metric.messaging.attributes - - id: metric.messaging.deliver.messages + - id: metric.messaging.process.messages type: metric - metric_name: messaging.deliver.messages - brief: "Measures the number of delivered messages." + metric_name: messaging.process.messages + brief: "Measures the number of processed messages." instrument: counter unit: "{message}" extends: metric.messaging.attributes diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index d05b5cc71d..fcd0c111bb 100644 --- a/model/registry/messaging.yaml +++ b/model/registry/messaging.yaml @@ -142,10 +142,13 @@ groups: 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" + value: "process" 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. + One or more messages are delivered to or processed by a consumer. + - id: settle + value: "settle" + brief: > + One or more messages are settled. brief: > A string identifying the kind of messaging operation. note: If a custom value is used, it MUST be of low cardinality. From 0d963c4016d96972bf0bfa51b23074d05bea8ec9 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 5 Mar 2024 17:28:09 -0800 Subject: [PATCH 15/22] [chore] Mark attributes and metrics as experimental explicitly (#781) --- model/faas-common.yaml | 4 ++ model/general.yaml | 4 ++ model/logs/events.yaml | 1 + model/logs/general.yaml | 1 + model/logs/media.yaml | 5 +++ model/logs/mobile-events.yaml | 2 + model/metrics/database-metrics.yaml | 11 +++++ model/metrics/faas-metrics.yaml | 9 +++++ model/metrics/http.yaml | 5 +++ model/metrics/jvm-metrics-experimental.yaml | 7 ++++ model/metrics/messaging.yaml | 7 ++++ model/metrics/process-metrics.yaml | 17 ++++++-- model/metrics/rpc-metrics.yaml | 10 +++++ model/metrics/system-metrics.yaml | 40 +++++++++++++++++++ model/registry/browser.yaml | 4 ++ model/registry/cloud.yaml | 7 +++- model/registry/code.yaml | 6 +++ model/registry/container.yaml | 11 +++++ model/registry/db.yaml | 30 ++++++++++++++ model/registry/destination.yaml | 2 + model/registry/device.yaml | 4 ++ model/registry/disk.yaml | 1 + model/registry/host.yaml | 15 +++++++ model/registry/k8s.yaml | 23 +++++++++++ model/registry/messaging.yaml | 37 +++++++++++++++++ model/registry/network.yaml | 7 ++++ model/registry/oci.yaml | 1 + model/registry/os.yaml | 5 +++ model/registry/process.yaml | 11 +++++ model/registry/rpc.yaml | 13 ++++++ model/registry/source.yaml | 2 + model/registry/thread.yaml | 2 + model/registry/tls.yaml | 29 ++++++++++++++ model/registry/url.yaml | 7 ++++ model/registry/user-agent.yaml | 2 + model/resource/android.yaml | 1 + model/resource/cloud_provider/aws/ecs.yaml | 7 ++++ model/resource/cloud_provider/aws/eks.yaml | 1 + model/resource/cloud_provider/aws/logs.yaml | 4 ++ .../cloud_provider/gcp/cloud_run.yaml | 2 + model/resource/cloud_provider/gcp/gce.yaml | 2 + model/resource/cloud_provider/heroku.yaml | 3 ++ model/resource/deployment_environment.yaml | 1 + model/resource/faas.yaml | 4 ++ model/resource/service_experimental.yaml | 2 + model/resource/telemetry_experimental.yaml | 2 + model/resource/webengine.yaml | 3 ++ model/scope/exporter/exporter.yaml | 8 ++-- model/session.yaml | 2 + model/trace/aws/lambda.yaml | 1 + model/trace/cloudevents.yaml | 5 +++ model/trace/compatibility.yaml | 1 + model/trace/faas.yaml | 10 ++++- model/trace/feature-flag.yaml | 3 ++ model/trace/instrumentation/aws-sdk.yml | 29 ++++++++++++++ model/trace/instrumentation/graphql.yml | 3 ++ model/trace/rpc.yaml | 4 ++ 57 files changed, 429 insertions(+), 11 deletions(-) diff --git a/model/faas-common.yaml b/model/faas-common.yaml index 7f903bb57f..11a8b430c0 100644 --- a/model/faas-common.yaml +++ b/model/faas-common.yaml @@ -24,8 +24,10 @@ groups: - id: other value: 'other' brief: 'If none of the others apply' + stability: experimental - id: invoked_name type: string + stability: experimental requirement_level: required brief: > The name of the invoked function. @@ -52,6 +54,7 @@ groups: - id: 'tencent_cloud' value: 'tencent_cloud' brief: 'Tencent Cloud' + stability: experimental requirement_level: required brief: > The cloud provider of the invoked function. @@ -60,6 +63,7 @@ groups: invoked function. - id: invoked_region type: string + stability: experimental requirement_level: conditionally_required: > For some cloud providers, like AWS or GCP, the region in which a diff --git a/model/general.yaml b/model/general.yaml index e3bad3d46a..ec38d6e8dd 100644 --- a/model/general.yaml +++ b/model/general.yaml @@ -34,6 +34,7 @@ groups: attributes: - id: service type: string + stability: experimental brief: > The [`service.name`](/docs/resource/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` @@ -47,6 +48,7 @@ groups: attributes: - id: id type: string + stability: experimental brief: > Username or client_id extracted from the access token or [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) @@ -54,10 +56,12 @@ groups: examples: 'username' - id: role type: string + stability: experimental brief: 'Actual/assumed role the client is making the request under extracted from token or application security context.' examples: 'admin' - id: scope type: string + stability: experimental brief: > Scopes or granted authorities the client currently possesses extracted from token or application security context. The value would come from the scope associated diff --git a/model/logs/events.yaml b/model/logs/events.yaml index 3942d432fd..a1ecf5f538 100644 --- a/model/logs/events.yaml +++ b/model/logs/events.yaml @@ -7,6 +7,7 @@ groups: attributes: - id: name type: string + stability: experimental requirement_level: required brief: > Identifies the class / type of event. diff --git a/model/logs/general.yaml b/model/logs/general.yaml index 48da970c13..e8f9ea5853 100644 --- a/model/logs/general.yaml +++ b/model/logs/general.yaml @@ -7,6 +7,7 @@ groups: attributes: - id: uid type: string + stability: experimental requirement_level: opt_in brief: > A unique identifier for the Log Record. diff --git a/model/logs/media.yaml b/model/logs/media.yaml index b8d1c29975..d2ac89f470 100644 --- a/model/logs/media.yaml +++ b/model/logs/media.yaml @@ -6,6 +6,7 @@ groups: attributes: - id: iostream requirement_level: opt_in + stability: experimental brief: > The stream associated with the log. See below for a list of well-known values. type: @@ -25,24 +26,28 @@ groups: attributes: - id: name type: string + stability: experimental requirement_level: recommended brief: > The basename of the file. examples: ["audit.log"] - id: path type: string + stability: experimental requirement_level: opt_in brief: > The full path to the file. examples: [ "/var/log/mysql/audit.log" ] - id: name_resolved type: string + stability: experimental requirement_level: opt_in brief: > The basename of the file, with symlinks resolved. examples: [ "uuid.log" ] - id: path_resolved type: string + stability: experimental requirement_level: opt_in brief: > The full path to the file, with symlinks resolved. diff --git a/model/logs/mobile-events.yaml b/model/logs/mobile-events.yaml index d6f49e70c5..0ae14ca975 100644 --- a/model/logs/mobile-events.yaml +++ b/model/logs/mobile-events.yaml @@ -7,6 +7,7 @@ groups: This event represents an occurrence of a lifecycle transition on the iOS platform. attributes: - id: state + stability: experimental requirement_level: "required" note: > The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#1656902), @@ -46,6 +47,7 @@ groups: This event represents an occurrence of a lifecycle transition on the Android platform. attributes: - id: state + stability: experimental requirement_level: required brief: > This attribute represents the state the application has transitioned into at the occurrence of the event. diff --git a/model/metrics/database-metrics.yaml b/model/metrics/database-metrics.yaml index 097ff79abf..0691e6c625 100644 --- a/model/metrics/database-metrics.yaml +++ b/model/metrics/database-metrics.yaml @@ -4,6 +4,7 @@ groups: brief: Describes Database attributes attributes: - id: state + stability: experimental type: allow_custom_values: false members: @@ -16,6 +17,7 @@ groups: examples: ["idle"] - id: pool.name type: string + stability: experimental requirement_level: required brief: > The name of the connection pool; unique within the instrumented application. @@ -27,6 +29,7 @@ groups: - id: metric.db.client.connections.usage type: metric metric_name: db.client.connections.usage + stability: experimental brief: "The number of connections that are currently in state described by the `state` attribute" instrument: updowncounter unit: "{connection}" @@ -37,6 +40,7 @@ groups: - id: metric.db.client.connections.idle.max type: metric metric_name: db.client.connections.idle.max + stability: experimental brief: "The maximum number of idle open connections allowed" instrument: updowncounter unit: "{connection}" @@ -46,6 +50,7 @@ groups: - id: metric.db.client.connections.idle.min type: metric metric_name: db.client.connections.idle.min + stability: experimental brief: "The minimum number of idle open connections allowed" instrument: updowncounter unit: "{connection}" @@ -55,6 +60,7 @@ groups: - id: metric.db.client.connections.max type: metric metric_name: db.client.connections.max + stability: experimental brief: "The maximum number of open connections allowed" instrument: updowncounter unit: "{connection}" @@ -64,6 +70,7 @@ groups: - id: metric.db.client.connections.pending_requests type: metric metric_name: db.client.connections.pending_requests + stability: experimental brief: "The number of pending requests for an open connection, cumulative for the entire pool" instrument: updowncounter unit: "{request}" @@ -73,6 +80,7 @@ groups: - id: metric.db.client.connections.timeouts type: metric metric_name: db.client.connections.timeouts + stability: experimental brief: "The number of connection timeouts that have occurred trying to obtain a connection from the pool" instrument: counter unit: "{timeout}" @@ -82,6 +90,7 @@ groups: - id: metric.db.client.connections.create_time type: metric metric_name: db.client.connections.create_time + stability: experimental brief: "The time it took to create a new connection" instrument: histogram unit: "ms" @@ -91,6 +100,7 @@ groups: - id: metric.db.client.connections.wait_time type: metric metric_name: db.client.connections.wait_time + stability: experimental brief: "The time it took to obtain an open connection from the pool" instrument: histogram unit: "ms" @@ -100,6 +110,7 @@ groups: - id: metric.db.client.connections.use_time type: metric metric_name: db.client.connections.use_time + stability: experimental brief: "The time between borrowing a connection and returning it to the pool" instrument: histogram unit: "ms" diff --git a/model/metrics/faas-metrics.yaml b/model/metrics/faas-metrics.yaml index d68119f320..238e49df77 100644 --- a/model/metrics/faas-metrics.yaml +++ b/model/metrics/faas-metrics.yaml @@ -2,6 +2,7 @@ groups: - id: metric.faas.invoke_duration type: metric metric_name: faas.invoke_duration + stability: experimental brief: "Measures the duration of the function's logic execution" instrument: histogram unit: "s" @@ -11,6 +12,7 @@ groups: - id: metric.faas.init_duration type: metric metric_name: faas.init_duration + stability: experimental brief: "Measures the duration of the function's initialization, such as a cold start" instrument: histogram unit: "s" @@ -20,6 +22,7 @@ groups: - id: metric.faas.coldstarts type: metric metric_name: faas.coldstarts + stability: experimental brief: "Number of invocation cold starts" instrument: counter unit: "{coldstart}" @@ -29,6 +32,7 @@ groups: - id: metric.faas.errors type: metric metric_name: faas.errors + stability: experimental brief: "Number of invocation errors" instrument: counter unit: "{error}" @@ -38,6 +42,7 @@ groups: - id: metric.faas.invocations type: metric metric_name: faas.invocations + stability: experimental brief: "Number of successful invocations" instrument: counter unit: "{invocation}" @@ -47,6 +52,7 @@ groups: - id: metric.faas.timeouts type: metric metric_name: faas.timeouts + stability: experimental brief: "Number of invocation timeouts" instrument: counter unit: "{timeout}" @@ -56,6 +62,7 @@ groups: - id: metric.faas.mem_usage type: metric metric_name: faas.mem_usage + stability: experimental brief: "Distribution of max memory usage per invocation" instrument: histogram unit: "By" @@ -65,6 +72,7 @@ groups: - id: metric.faas.cpu_usage type: metric metric_name: faas.cpu_usage + stability: experimental brief: "Distribution of CPU usage per invocation" instrument: histogram unit: "s" @@ -74,6 +82,7 @@ groups: - id: metric.faas.net_io type: metric metric_name: faas.net_io + stability: experimental brief: "Distribution of net I/O usage per invocation" instrument: histogram unit: "By" diff --git a/model/metrics/http.yaml b/model/metrics/http.yaml index a309994f2d..d22e7836b8 100644 --- a/model/metrics/http.yaml +++ b/model/metrics/http.yaml @@ -35,6 +35,7 @@ groups: - id: metric.http.server.active_requests type: metric metric_name: http.server.active_requests + stability: experimental brief: "Number of active HTTP server requests." instrument: updowncounter unit: "{request}" @@ -66,6 +67,7 @@ groups: - id: metric.http.server.request.body.size type: metric metric_name: http.server.request.body.size + stability: experimental brief: "Size of HTTP server request bodies." instrument: histogram unit: "By" @@ -78,6 +80,7 @@ groups: - id: metric.http.server.response.body.size type: metric metric_name: http.server.response.body.size + stability: experimental brief: "Size of HTTP server response bodies." instrument: histogram unit: "By" @@ -99,6 +102,7 @@ groups: - id: metric.http.client.request.body.size type: metric metric_name: http.client.request.body.size + stability: experimental brief: "Size of HTTP client request bodies." instrument: histogram unit: "By" @@ -111,6 +115,7 @@ groups: - id: metric.http.client.response.body.size type: metric metric_name: http.client.response.body.size + stability: experimental brief: "Size of HTTP client response bodies." instrument: histogram unit: "By" diff --git a/model/metrics/jvm-metrics-experimental.yaml b/model/metrics/jvm-metrics-experimental.yaml index 8ea4fa57c5..4bc7cc7581 100644 --- a/model/metrics/jvm-metrics-experimental.yaml +++ b/model/metrics/jvm-metrics-experimental.yaml @@ -2,6 +2,7 @@ groups: - id: metric.jvm.memory.init type: metric metric_name: jvm.memory.init + stability: experimental extends: attributes.jvm.memory brief: "Measure of initial memory requested." instrument: updowncounter @@ -10,6 +11,7 @@ groups: - id: metric.jvm.system.cpu.utilization type: metric metric_name: jvm.system.cpu.utilization + stability: experimental brief: "Recent CPU utilization for the whole system as reported by the JVM." note: > The value range is [0.0,1.0]. @@ -22,6 +24,7 @@ groups: - id: metric.jvm.system.cpu.load_1m type: metric metric_name: jvm.system.cpu.load_1m + stability: experimental brief: "Average CPU load of the whole system for the last minute as reported by the JVM." note: > The value range is [0,n], where n is the number of CPU cores - or a negative number if the value is not available. @@ -38,6 +41,7 @@ groups: attributes: - id: pool.name type: string + stability: experimental requirement_level: recommended brief: Name of the buffer pool. examples: [ "mapped", "direct" ] @@ -48,6 +52,7 @@ groups: - id: metric.jvm.buffer.memory.usage type: metric metric_name: jvm.buffer.memory.usage + stability: experimental extends: attributes.jvm.buffer brief: "Measure of memory used by buffers." instrument: updowncounter @@ -56,6 +61,7 @@ groups: - id: metric.jvm.buffer.memory.limit type: metric metric_name: jvm.buffer.memory.limit + stability: experimental extends: attributes.jvm.buffer brief: "Measure of total memory capacity of buffers." instrument: updowncounter @@ -64,6 +70,7 @@ groups: - id: metric.jvm.buffer.count type: metric metric_name: jvm.buffer.count + stability: experimental extends: attributes.jvm.buffer brief: "Number of buffers in the pool." instrument: updowncounter diff --git a/model/metrics/messaging.yaml b/model/metrics/messaging.yaml index 18079b3a52..03a1a5b44b 100644 --- a/model/metrics/messaging.yaml +++ b/model/metrics/messaging.yaml @@ -1,6 +1,7 @@ groups: - id: metric.messaging.attributes type: attribute_group + stability: experimental brief: "Common messaging metrics attributes." extends: messaging.attributes.common attributes: @@ -16,6 +17,7 @@ groups: type: metric metric_name: messaging.publish.duration brief: "Measures the duration of publish operation." + stability: experimental instrument: histogram unit: "s" extends: metric.messaging.attributes @@ -24,6 +26,7 @@ groups: type: metric metric_name: messaging.receive.duration brief: "Measures the duration of receive operation." + stability: experimental instrument: histogram unit: "s" extends: metric.messaging.attributes @@ -32,6 +35,7 @@ groups: type: metric metric_name: messaging.process.duration brief: "Measures the duration of process operation." + stability: experimental instrument: histogram unit: "s" extends: metric.messaging.attributes @@ -41,6 +45,7 @@ groups: type: metric metric_name: messaging.publish.messages brief: "Measures the number of published messages." + stability: experimental instrument: counter unit: "{message}" extends: metric.messaging.attributes @@ -49,6 +54,7 @@ groups: type: metric metric_name: messaging.receive.messages brief: "Measures the number of received messages." + stability: experimental instrument: counter unit: "{message}" extends: metric.messaging.attributes @@ -57,6 +63,7 @@ groups: type: metric metric_name: messaging.process.messages brief: "Measures the number of processed messages." + stability: experimental instrument: counter unit: "{message}" extends: metric.messaging.attributes diff --git a/model/metrics/process-metrics.yaml b/model/metrics/process-metrics.yaml index cc663a9eaf..d6735399a1 100644 --- a/model/metrics/process-metrics.yaml +++ b/model/metrics/process-metrics.yaml @@ -15,10 +15,11 @@ groups: value: 'user' - id: wait value: 'wait' - + stability: experimental - id: metric.process.cpu.time type: metric metric_name: process.cpu.time + stability: experimental brief: "Total CPU seconds broken down by different states." instrument: counter unit: "s" @@ -28,6 +29,7 @@ groups: - id: metric.process.cpu.utilization type: metric metric_name: process.cpu.utilization + stability: experimental brief: "Difference in process.cpu.time since the last measurement, divided by the elapsed time and number of CPUs available to the process." instrument: gauge unit: "1" @@ -37,6 +39,7 @@ groups: - id: metric.process.memory.usage type: metric metric_name: process.memory.usage + stability: experimental brief: "The amount of physical memory in use." instrument: updowncounter unit: "By" @@ -45,6 +48,7 @@ groups: - id: metric.process.memory.virtual type: metric metric_name: process.memory.virtual + stability: experimental brief: "The amount of committed virtual memory." instrument: updowncounter unit: "By" @@ -53,6 +57,7 @@ groups: - id: metric.process.disk.io type: metric metric_name: process.disk.io + stability: experimental prefix: process.disk brief: "Disk bytes transferred." instrument: counter @@ -63,6 +68,7 @@ groups: - id: metric.process.network.io type: metric metric_name: process.network.io + stability: experimental brief: "Network bytes transferred." instrument: counter unit: "By" @@ -72,22 +78,23 @@ groups: - id: metric.process.thread.count type: metric metric_name: process.thread.count + stability: experimental brief: "Process threads count." instrument: updowncounter unit: "{thread}" - attributes: [] - id: metric.process.open_file_descriptor.count type: metric metric_name: process.open_file_descriptor.count + stability: experimental brief: "Number of file descriptors in use by the process." instrument: updowncounter unit: "{count}" - attributes: [] - id: metric.process.context_switches type: metric metric_name: process.context_switches + stability: experimental brief: "Number of times the process has been context switched." instrument: counter unit: "{count}" @@ -101,10 +108,11 @@ groups: value: 'voluntary' - id: involuntary value: 'involuntary' - + stability: experimental - id: metric.process.paging.faults type: metric metric_name: process.paging.faults + stability: experimental brief: "Number of page faults the process has made." instrument: counter unit: "{fault}" @@ -118,3 +126,4 @@ groups: value: 'major' - id: minor value: 'minor' + stability: experimental diff --git a/model/metrics/rpc-metrics.yaml b/model/metrics/rpc-metrics.yaml index ca29cdf194..aa47588d41 100644 --- a/model/metrics/rpc-metrics.yaml +++ b/model/metrics/rpc-metrics.yaml @@ -19,6 +19,7 @@ groups: - id: metric.rpc.server.duration type: metric metric_name: rpc.server.duration + stability: experimental brief: Measures the duration of inbound RPC. instrument: histogram unit: "ms" @@ -31,6 +32,7 @@ groups: - id: metric.rpc.server.request.size type: metric metric_name: rpc.server.request.size + stability: experimental brief: Measures the size of RPC request messages (uncompressed). instrument: histogram unit: "By" @@ -40,6 +42,7 @@ groups: - id: metric.rpc.server.response.size type: metric metric_name: rpc.server.response.size + stability: experimental brief: Measures the size of RPC response messages (uncompressed). instrument: histogram unit: "By" @@ -49,6 +52,7 @@ groups: - id: metric.rpc.server.requests_per_rpc type: metric metric_name: rpc.server.requests_per_rpc + stability: experimental brief: Measures the number of messages received per RPC. instrument: histogram unit: "{count}" @@ -60,6 +64,7 @@ groups: - id: metric.rpc.server.responses_per_rpc type: metric metric_name: rpc.server.responses_per_rpc + stability: experimental brief: Measures the number of messages sent per RPC. instrument: histogram unit: "{count}" @@ -72,6 +77,7 @@ groups: - id: metric.rpc.client.duration type: metric metric_name: rpc.client.duration + stability: experimental brief: Measures the duration of outbound RPC. instrument: histogram unit: "ms" @@ -84,6 +90,7 @@ groups: - id: metric.rpc.client.request.size type: metric metric_name: rpc.client.request.size + stability: experimental brief: Measures the size of RPC request messages (uncompressed). instrument: histogram unit: "By" @@ -93,6 +100,7 @@ groups: - id: metric.rpc.client.response.size type: metric metric_name: rpc.client.response.size + stability: experimental brief: Measures the size of RPC response messages (uncompressed). instrument: histogram unit: "By" @@ -102,6 +110,7 @@ groups: - id: metric.rpc.client.requests_per_rpc type: metric metric_name: rpc.client.requests_per_rpc + stability: experimental brief: Measures the number of messages received per RPC. instrument: histogram unit: "{count}" @@ -113,6 +122,7 @@ groups: - id: metric.rpc.client.responses_per_rpc type: metric metric_name: rpc.client.responses_per_rpc + stability: experimental brief: Measures the number of messages sent per RPC. instrument: histogram unit: "{count}" diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml index 9f288e87ff..49a3a765b4 100644 --- a/model/metrics/system-metrics.yaml +++ b/model/metrics/system-metrics.yaml @@ -7,6 +7,7 @@ groups: attributes: - id: device type: string + stability: experimental brief: "The device identifier" examples: ["(identifier)"] @@ -34,16 +35,19 @@ groups: value: 'interrupt' - id: steal value: 'steal' + stability: experimental brief: "The state of the CPU" examples: ["idle", "interrupt"] - id: logical_number type: int + stability: experimental brief: "The logical CPU number [0..n-1]" examples: [1] - id: metric.system.cpu.time type: metric metric_name: system.cpu.time + stability: experimental brief: "Seconds each logical CPU spent on each mode" instrument: counter unit: "s" @@ -54,6 +58,7 @@ groups: - id: metric.system.cpu.utilization type: metric metric_name: system.cpu.utilization + stability: experimental brief: "Difference in system.cpu.time since the last measurement, divided by the elapsed time and number of logical CPUs" instrument: gauge unit: "1" @@ -64,6 +69,7 @@ groups: - id: metric.system.cpu.frequency type: metric metric_name: system.cpu.frequency + stability: experimental brief: "Reports the current frequency of the CPU in Hz" instrument: gauge unit: "{Hz}" @@ -73,6 +79,7 @@ groups: - id: metric.system.cpu.physical.count type: metric metric_name: system.cpu.physical.count + stability: experimental brief: "Reports the number of actual physical processor cores on the hardware" instrument: updowncounter unit: "{cpu}" @@ -81,6 +88,7 @@ groups: - id: metric.system.cpu.logical.count type: metric metric_name: system.cpu.logical.count + stability: experimental brief: "Reports the number of logical (virtual) processor cores created by the operating system to manage multitasking" instrument: updowncounter unit: "{cpu}" @@ -106,12 +114,14 @@ groups: value: 'buffers' - id: cached value: 'cached' + stability: experimental brief: "The memory state" examples: ["free", "cached"] - id: metric.system.memory.usage type: metric metric_name: system.memory.usage + stability: experimental brief: "Reports memory in use by state." note: | The sum over all `system.memory.state` values SHOULD equal the total memory @@ -124,6 +134,7 @@ groups: - id: metric.system.memory.limit type: metric metric_name: system.memory.limit + stability: experimental brief: "Total memory available in the system." note: | Its value SHOULD equal the sum of `system.memory.state` over all states. @@ -133,6 +144,7 @@ groups: - id: metric.system.memory.utilization type: metric metric_name: system.memory.utilization + stability: experimental brief: "" instrument: gauge unit: "1" @@ -153,6 +165,7 @@ groups: value: 'used' - id: free value: 'free' + stability: experimental brief: "The memory paging state" examples: ["free"] - id: type @@ -163,6 +176,7 @@ groups: value: 'major' - id: minor value: 'minor' + stability: experimental brief: "The memory paging type" examples: ["minor"] - id: direction @@ -173,11 +187,13 @@ groups: value: 'in' - id: out value: 'out' + stability: experimental brief: "The paging access direction" examples: ["in"] - id: metric.system.paging.usage type: metric metric_name: system.paging.usage + stability: experimental brief: "Unix swap or windows pagefile usage" instrument: updowncounter unit: "By" @@ -187,6 +203,7 @@ groups: - id: metric.system.paging.utilization type: metric metric_name: system.paging.utilization + stability: experimental brief: "" instrument: gauge unit: "1" @@ -196,6 +213,7 @@ groups: - id: metric.system.paging.faults type: metric metric_name: system.paging.faults + stability: experimental brief: "" instrument: counter unit: "{fault}" @@ -205,6 +223,7 @@ groups: - id: metric.system.paging.operations type: metric metric_name: system.paging.operations + stability: experimental brief: "" instrument: counter unit: "{operation}" @@ -216,6 +235,7 @@ groups: - id: metric.system.disk.io type: metric metric_name: system.disk.io + stability: experimental brief: "" instrument: counter unit: "By" @@ -226,6 +246,7 @@ groups: - id: metric.system.disk.operations type: metric metric_name: system.disk.operations + stability: experimental brief: "" instrument: counter unit: "{operation}" @@ -236,6 +257,7 @@ groups: - id: metric.system.disk.io_time type: metric metric_name: system.disk.io_time + stability: experimental brief: "Time disk spent activated" instrument: counter unit: "s" @@ -252,6 +274,7 @@ groups: - id: metric.system.disk.operation_time type: metric metric_name: system.disk.operation_time + stability: experimental brief: "Sum of the time each operation took to complete" instrument: counter unit: "s" @@ -267,6 +290,7 @@ groups: - id: metric.system.disk.merged type: metric metric_name: system.disk.merged + stability: experimental brief: "" instrument: counter unit: "{operation}" @@ -291,6 +315,7 @@ groups: value: 'free' - id: reserved value: 'reserved' + stability: experimental examples: ["used"] - id: type type: @@ -308,20 +333,24 @@ groups: value: 'hfsplus' - id: ext4 value: 'ext4' + stability: experimental brief: "The filesystem type" examples: ["ext4"] - id: mode type: string + stability: experimental brief: "The filesystem mode" examples: ["rw, ro"] - id: mountpoint type: string + stability: experimental brief: "The filesystem mount path" examples: ["/mnt/data"] - id: metric.system.filesystem.usage type: metric metric_name: system.filesystem.usage + stability: experimental brief: "" instrument: updowncounter unit: "By" @@ -335,6 +364,7 @@ groups: - id: metric.system.filesystem.utilization type: metric metric_name: system.filesystem.utilization + stability: experimental brief: "" instrument: gauge unit: "1" @@ -381,12 +411,14 @@ groups: value: 'syn_sent' - id: time_wait value: 'time_wait' + stability: experimental brief: "A stateless protocol MUST NOT set this attribute" examples: ["close_wait"] - id: metric.system.network.dropped type: metric metric_name: system.network.dropped + stability: experimental brief: "Count of packets that are dropped or discarded even though there was no error" instrument: counter unit: "{packet}" @@ -403,6 +435,7 @@ groups: - id: metric.system.network.packets type: metric metric_name: system.network.packets + stability: experimental brief: "" instrument: counter unit: "{packet}" @@ -413,6 +446,7 @@ groups: - id: metric.system.network.errors type: metric metric_name: system.network.errors + stability: experimental brief: "Count of network errors detected" instrument: counter unit: "{error}" @@ -429,6 +463,7 @@ groups: - id: metric.system.network.io type: metric metric_name: system.network.io + stability: experimental brief: "" instrument: counter unit: "By" @@ -439,6 +474,7 @@ groups: - id: metric.system.network.connections type: metric metric_name: system.network.connections + stability: experimental brief: "" instrument: updowncounter unit: "{connection}" @@ -465,6 +501,7 @@ groups: value: 'stopped' - id: defunct value: 'defunct' + stability: experimental brief: > The process state, e.g., [Linux Process State Codes](https://man7.org/linux/man-pages/man1/ps.1.html#PROCESS_STATE_CODES) examples: ["running"] @@ -473,6 +510,7 @@ groups: - id: metric.system.process.count type: metric metric_name: system.process.count + stability: experimental brief: "Total number of processes in each state" instrument: updowncounter unit: "{process}" @@ -482,6 +520,7 @@ groups: - id: metric.system.process.created type: metric metric_name: system.process.created + stability: experimental brief: "Total number of processes created over uptime of the host" instrument: counter unit: "{process}" @@ -490,6 +529,7 @@ groups: - id: metric.system.linux.memory.available type: metric metric_name: system.linux.memory.available + stability: experimental brief: "An estimate of how much memory is available for starting new applications, without causing swapping" note: | This is an alternative to `system.memory.usage` metric with `state=free`. diff --git a/model/registry/browser.yaml b/model/registry/browser.yaml index e9d0da5c93..286c95b193 100644 --- a/model/registry/browser.yaml +++ b/model/registry/browser.yaml @@ -7,6 +7,7 @@ groups: attributes: - id: brands type: string[] + stability: experimental brief: 'Array of brand name and version separated by a space' note: > This value is intended to be taken from the @@ -15,6 +16,7 @@ groups: examples: [ " Not A;Brand 99", "Chromium 99", "Chrome 99" ] - id: platform type: string + stability: experimental brief: 'The platform on which the browser is running' note: > This value is intended to be taken from the @@ -32,6 +34,7 @@ groups: examples: ['Windows', 'macOS', 'Android'] - id: mobile type: boolean + stability: experimental brief: 'A boolean that is true if the browser is running on a mobile device' note: > This value is intended to be taken from the @@ -40,6 +43,7 @@ groups: SHOULD be left unset. - id: language type: string + stability: experimental brief: 'Preferred language of the user using the browser' note: > This value is intended to be taken from the Navigator API diff --git a/model/registry/cloud.yaml b/model/registry/cloud.yaml index 5ddb25c899..e3ce26b0e4 100644 --- a/model/registry/cloud.yaml +++ b/model/registry/cloud.yaml @@ -30,16 +30,18 @@ groups: - id: 'tencent_cloud' value: 'tencent_cloud' brief: 'Tencent Cloud' - + stability: experimental brief: > Name of the cloud provider. - id: account.id type: string + stability: experimental brief: > The cloud account ID the resource is assigned to. examples: ['111111111111', 'opentelemetry'] - id: region type: string + stability: experimental brief: > The geographical region the resource is running. note: > @@ -52,6 +54,7 @@ groups: examples: ['us-central1', 'us-east-1'] - id: resource_id type: string + stability: experimental 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, @@ -81,6 +84,7 @@ groups: - '/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/' - id: availability_zone type: string + stability: experimental brief: > Cloud regions often have multiple, isolated locations known as zones to increase availability. Availability zone represents the @@ -176,6 +180,7 @@ groups: - id: tencent_cloud_scf value: 'tencent_cloud_scf' brief: Tencent Cloud Serverless Cloud Function (SCF) + stability: experimental brief: > The cloud platform in use. note: > diff --git a/model/registry/code.yaml b/model/registry/code.yaml index d5afceeaed..5848b4fa60 100644 --- a/model/registry/code.yaml +++ b/model/registry/code.yaml @@ -7,32 +7,38 @@ groups: attributes: - id: function type: string + stability: experimental brief: > The method or function name, or equivalent (usually rightmost part of the code unit's name). examples: serveRequest - id: namespace type: string + stability: experimental 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 + stability: experimental 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 + stability: experimental 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 + stability: experimental 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 + stability: experimental 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. diff --git a/model/registry/container.yaml b/model/registry/container.yaml index 2288c39e52..343c63b927 100644 --- a/model/registry/container.yaml +++ b/model/registry/container.yaml @@ -7,11 +7,13 @@ groups: attributes: - id: name type: string + stability: experimental brief: > Container name used by container runtime. examples: ['opentelemetry-autoconf'] - id: id type: string + stability: experimental brief: > Container ID. Usually a UUID, as for example used to [identify Docker containers](https://docs.docker.com/engine/reference/run/#container-identification). @@ -19,16 +21,19 @@ groups: examples: ['a3bf90e006b2'] - id: runtime type: string + stability: experimental brief: > The container runtime managing this container. examples: ['docker', 'containerd', 'rkt'] - id: image.name type: string + stability: experimental brief: > Name of the image the container was built on. examples: ['gcr.io/opentelemetry/operator'] - id: image.tags type: string[] + stability: experimental 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). @@ -37,6 +42,7 @@ groups: examples: ['v1.27.1', '3.5.7-0'] - id: image.id type: string + stability: experimental brief: > Runtime specific image identifier. Usually a hash algorithm followed by a UUID. note: > @@ -53,6 +59,7 @@ groups: examples: ['sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f'] - id: image.repo_digests type: string[] + stability: experimental brief: > Repo digests of the container image as provided by the container runtime. note: > @@ -64,6 +71,7 @@ groups: - 'internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578' - id: command type: string + stability: experimental note: > If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage. brief: > @@ -71,16 +79,19 @@ groups: examples: [ 'otelcontribcol' ] - id: command_line type: string + stability: experimental 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[] + stability: experimental brief: > All the command arguments (including the command/executable itself) run by the container. [2] examples: [ 'otelcontribcol, --config, config.yaml' ] - id: label type: template[string] + stability: experimental brief: > Container labels, `` being the label name, the value being the label value. examples: [ 'container.label.app=nginx' ] diff --git a/model/registry/db.yaml b/model/registry/db.yaml index a17c1046d4..6926fa53b6 100644 --- a/model/registry/db.yaml +++ b/model/registry/db.yaml @@ -7,12 +7,14 @@ groups: attributes: - id: cassandra.coordinator.dc type: string + stability: experimental 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 + stability: experimental brief: > The ID of the coordinating node for a query. examples: 'be13faa2-8574-4d71-926d-27f16cf8a7af' @@ -44,26 +46,31 @@ groups: value: 'serial' - id: local_serial value: 'local_serial' + stability: experimental tag: tech-specific-cassandra - id: cassandra.idempotence type: boolean + stability: experimental brief: > Whether or not the query is idempotent. tag: tech-specific-cassandra - id: cassandra.page_size type: int + stability: experimental 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 + stability: experimental 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 + stability: experimental 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. @@ -76,6 +83,7 @@ groups: tag: tech-specific-cassandra - id: connection_string type: string + stability: experimental brief: > The connection string used to connect to the database. It is recommended to remove embedded credentials. @@ -83,6 +91,7 @@ groups: tag: db-generic - id: cosmosdb.client_id type: string + stability: experimental brief: Unique Cosmos client instance id. examples: '3ba4827d-4422-483f-b59f-85b74211c11d' tag: tech-specific-cosmosdb @@ -96,10 +105,12 @@ groups: - id: direct value: 'direct' brief: Direct connection. + stability: experimental brief: Cosmos client connection mode. tag: tech-specific-cosmosdb - id: cosmosdb.container type: string + stability: experimental brief: Cosmos DB container name. examples: 'anystring' tag: tech-specific-cosmosdb @@ -137,41 +148,49 @@ groups: value: 'QueryPlan' - id: execute_javascript value: 'ExecuteJavaScript' + stability: experimental brief: CosmosDB Operation Type. tag: tech-specific-cosmosdb - id: cosmosdb.request_charge type: double + stability: experimental brief: RU consumed for that operation examples: [46.18, 1.0] tag: tech-specific-cosmosdb - id: cosmosdb.request_content_length type: int + stability: experimental brief: Request payload size in bytes tag: tech-specific-cosmosdb - id: cosmosdb.status_code type: int + stability: experimental brief: Cosmos DB status code. examples: [200, 201] tag: tech-specific-cosmosdb - id: cosmosdb.sub_status_code type: int + stability: experimental brief: Cosmos DB sub status code. examples: [1000, 1002] tag: tech-specific-cosmosdb - id: elasticsearch.cluster.name type: string + stability: experimental brief: > Represents the identifier of an Elasticsearch cluster. examples: ["e9106fc68e3044f0b1475b04bf4ffd5f"] tag: tech-specific-elasticsearch - id: elasticsearch.node.name type: string + stability: experimental 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] + stability: experimental brief: > A dynamic value in the url path. note: > @@ -183,18 +202,21 @@ groups: tag: tech-specific-elasticsearch - id: jdbc.driver_classname type: string + stability: experimental 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 + stability: experimental 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 + stability: experimental note: > If setting a `db.mssql.instance_name`, `server.port` is no longer required (but still recommended if non-standard). @@ -205,6 +227,7 @@ groups: tag: tech-specific-mssql - id: name type: string + stability: experimental 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 @@ -218,6 +241,7 @@ groups: tag: db-generic - id: operation type: string + stability: experimental 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. @@ -232,6 +256,7 @@ groups: tag: db-generic - id: redis.database_index type: int + stability: experimental 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. @@ -239,6 +264,7 @@ groups: tag: tech-specific-redis - id: sql.table type: string + stability: experimental 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 @@ -250,6 +276,7 @@ groups: tag: tech-specific-sql - id: statement type: string + stability: experimental brief: > The database statement being executed. examples: ['SELECT * FROM wuser_table', 'SET mykey "WuValue"'] @@ -415,9 +442,11 @@ groups: - id: trino value: 'trino' brief: 'Trino' + stability: experimental tag: db-generic - id: user type: string + stability: experimental brief: > Username for accessing the database. examples: ['readonly_user', 'reporting_user'] @@ -425,6 +454,7 @@ groups: - id: instance.id tag: db-generic type: string + stability: experimental 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. diff --git a/model/registry/destination.yaml b/model/registry/destination.yaml index 595a1c67f9..99adf1a872 100644 --- a/model/registry/destination.yaml +++ b/model/registry/destination.yaml @@ -12,6 +12,7 @@ groups: attributes: - id: address type: string + stability: experimental 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 @@ -19,5 +20,6 @@ groups: examples: ['destination.example.com', '10.1.2.80', '/tmp/my.sock'] - id: port type: int + stability: experimental brief: 'Destination port number' examples: [3389, 2888] diff --git a/model/registry/device.yaml b/model/registry/device.yaml index c109981f11..5c324e37fe 100644 --- a/model/registry/device.yaml +++ b/model/registry/device.yaml @@ -7,6 +7,7 @@ groups: attributes: - id: id type: string + stability: experimental brief: > A unique identifier representing the device note: > @@ -21,6 +22,7 @@ groups: examples: ['2ab2916d-a51f-4ac8-80ee-45ac31a28092'] - id: manufacturer type: string + stability: experimental brief: > The name of the device manufacturer note: > @@ -29,6 +31,7 @@ groups: examples: ['Apple', 'Samsung'] - id: model.identifier type: string + stability: experimental brief: > The model identifier for the device note: > @@ -38,6 +41,7 @@ groups: examples: ['iPhone3,4', 'SM-G920F'] - id: model.name type: string + stability: experimental brief: > The marketing name for the device model note: > diff --git a/model/registry/disk.yaml b/model/registry/disk.yaml index 90d6fb27d2..d8aba1e251 100644 --- a/model/registry/disk.yaml +++ b/model/registry/disk.yaml @@ -13,5 +13,6 @@ groups: value: 'read' - id: write value: 'write' + stability: experimental brief: "The disk IO operation direction." examples: ["read"] diff --git a/model/registry/host.yaml b/model/registry/host.yaml index c6b68ef414..f427266375 100644 --- a/model/registry/host.yaml +++ b/model/registry/host.yaml @@ -7,6 +7,7 @@ groups: attributes: - id: id type: string + stability: experimental 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 @@ -14,6 +15,7 @@ groups: examples: ['fdbf79e8af94cb7f9e8df36789187052'] - id: name type: string + stability: experimental brief: > Name of the host. On Unix systems, it may contain what the hostname command returns, or the fully qualified hostname, or another name @@ -21,6 +23,7 @@ groups: examples: ['opentelemetry-test'] - id: type type: string + stability: experimental brief: > Type of host. For Cloud, this must be the machine type. examples: ['n1-standard-1'] @@ -52,25 +55,30 @@ groups: - id: x86 value: 'x86' brief: "32-bit x86" + stability: experimental brief: > The CPU architecture the host system is running on. - id: image.name type: string + stability: experimental 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 + stability: experimental 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 + stability: experimental 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 + stability: experimental type: string[] brief: > Available IP addresses of the host, excluding loopback interfaces. @@ -79,6 +87,7 @@ groups: 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 + stability: experimental type: string[] brief: > Available MAC addresses of the host, excluding loopback interfaces. @@ -87,6 +96,7 @@ groups: 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 + stability: experimental type: string brief: > Processor manufacturer identifier. A maximum 12-character string. @@ -95,27 +105,32 @@ groups: Writing these to memory in this order results in a 12-character string. examples: [ 'GenuineIntel' ] - id: cpu.family + stability: experimental type: string brief: > Family or generation of the CPU. examples: [ '6', 'PA-RISC 1.1e' ] - id: cpu.model.id + stability: experimental 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 + stability: experimental type: string brief: > Model designation of the processor. examples: [ '11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz' ] - id: cpu.stepping + stability: experimental type: string brief: > Stepping or core revisions. examples: ["1", "r1p1"] - id: cpu.cache.l2.size + stability: experimental type: int brief: > The amount of level 2 memory cache available to the processor (in Bytes). diff --git a/model/registry/k8s.yaml b/model/registry/k8s.yaml index efda36e993..ca878b8fd8 100644 --- a/model/registry/k8s.yaml +++ b/model/registry/k8s.yaml @@ -7,11 +7,13 @@ groups: attributes: - id: cluster.name type: string + stability: experimental brief: > The name of the cluster. examples: ['opentelemetry-cluster'] - id: cluster.uid type: string + stability: experimental brief: > A pseudo-ID for the cluster, set to the UID of the `kube-system` namespace. @@ -41,41 +43,49 @@ groups: examples: ['218fc5a9-a5f1-4b54-aa05-46717d0ab26d'] - id: node.name type: string + stability: experimental brief: > The name of the Node. examples: ['node-1'] - id: node.uid type: string + stability: experimental brief: > The UID of the Node. examples: ['1eb3a0c6-0477-4080-a9cb-0cb7db65c6a2'] - id: namespace.name type: string + stability: experimental brief: > The name of the namespace that the pod is running in. examples: ['default'] - id: pod.uid type: string + stability: experimental brief: > The UID of the Pod. examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - id: pod.name type: string + stability: experimental brief: > The name of the Pod. examples: ['opentelemetry-pod-autoconf'] - id: pod.label type: template[string] + stability: experimental brief: > The label key-value pairs placed on the Pod, the `` being the label name, the value being the label value. examples: ['k8s.pod.label.app=my-app', 'k8s.pod.label.mycompany.io/arch=x64', 'k8s.pod.label.data='] - id: pod.annotation type: template[string] + stability: experimental brief: > The annotation key-value pairs placed on the Pod, the `` being the annotation name, the value being the annotation value. examples: [ 'k8s.pod.annotation.kubernetes.io/enforce-mountable-secrets=true', 'k8s.pod.annotation.mycompany.io/arch=x64', 'k8s.pod.annotation.data=' ] - id: container.name type: string + stability: experimental brief: > The name of the Container from Pod specification, must be unique within a Pod. Container runtime usually uses different globally unique @@ -83,6 +93,7 @@ groups: examples: ['redis'] - id: container.restart_count type: int + stability: experimental brief: > Number of times the container was restarted. This attribute can be used to identify a particular container (running or stopped) within a @@ -90,61 +101,73 @@ groups: examples: [0, 2] - id: replicaset.uid type: string + stability: experimental brief: > The UID of the ReplicaSet. examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - id: replicaset.name type: string + stability: experimental brief: > The name of the ReplicaSet. examples: ['opentelemetry'] - id: deployment.uid type: string + stability: experimental brief: > The UID of the Deployment. examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - id: deployment.name type: string + stability: experimental brief: > The name of the Deployment. examples: ['opentelemetry'] - id: statefulset.uid type: string + stability: experimental brief: > The UID of the StatefulSet. examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - id: statefulset.name type: string + stability: experimental brief: > The name of the StatefulSet. examples: ['opentelemetry'] - id: daemonset.uid type: string + stability: experimental brief: > The UID of the DaemonSet. examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - id: daemonset.name type: string + stability: experimental brief: > The name of the DaemonSet. examples: ['opentelemetry'] - id: job.uid type: string + stability: experimental brief: > The UID of the Job. examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - id: job.name type: string + stability: experimental brief: > The name of the Job. examples: ['opentelemetry'] - id: cronjob.uid type: string + stability: experimental brief: > The UID of the CronJob. examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] - id: cronjob.name type: string + stability: experimental brief: > The name of the CronJob. examples: ['opentelemetry'] diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index fcd0c111bb..4afd4d5320 100644 --- a/model/registry/messaging.yaml +++ b/model/registry/messaging.yaml @@ -6,6 +6,7 @@ groups: attributes: - id: batch.message_count type: int + stability: experimental 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. @@ -15,12 +16,14 @@ groups: tag: messaging-generic - id: client_id type: string + stability: experimental brief: > A unique identifier for the client that consumes or produces a message. examples: ['client-5', 'myhost@8742@s8083jm'] tag: messaging-generic - id: destination.name type: string + stability: experimental brief: 'The message destination name' note: | Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If @@ -29,6 +32,7 @@ groups: tag: messaging-generic - id: destination.template type: string + stability: experimental brief: Low cardinality representation of the messaging destination name note: > Destination names could be constructed from templates. @@ -40,18 +44,22 @@ groups: tag: messaging-generic - id: destination.anonymous type: boolean + stability: experimental brief: 'A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name).' tag: messaging-generic - id: destination.temporary type: boolean + stability: experimental brief: 'A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed.' tag: messaging-generic - id: destination_publish.anonymous type: boolean + stability: experimental brief: 'A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name).' tag: messaging-generic - id: destination_publish.name type: string + stability: experimental 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 @@ -60,6 +68,7 @@ groups: tag: messaging-generic - id: kafka.consumer.group type: string + stability: experimental brief: > Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. @@ -67,12 +76,14 @@ groups: tag: tech-specific-kafka - id: kafka.destination.partition type: int + stability: experimental brief: > Partition the message is sent to. examples: 2 tag: tech-specific-kafka - id: kafka.message.key type: string + stability: experimental 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. @@ -84,16 +95,19 @@ groups: tag: tech-specific-kafka - id: kafka.message.offset type: int + stability: experimental brief: > The offset of a record in the corresponding Kafka partition. examples: 42 tag: tech-specific-kafka - id: kafka.message.tombstone type: boolean + stability: experimental brief: 'A boolean that is true if the message is a tombstone.' tag: tech-specific-kafka - id: message.conversation_id type: string + stability: experimental brief: > The conversation ID identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". @@ -101,6 +115,7 @@ groups: tag: messaging-generic - id: message.envelope.size type: int + stability: experimental brief: > The size of the message body and metadata in bytes. note: | @@ -110,11 +125,13 @@ groups: tag: messaging-generic - id: message.id type: string + stability: experimental brief: 'A value used by the messaging system as an identifier for the message, represented as a string.' examples: '452a7c7c7c7048c2f887f61572b18fc2' tag: messaging-generic - id: message.body.size type: int + stability: experimental brief: > The size of the message body in bytes. note: | @@ -149,18 +166,21 @@ groups: value: "settle" brief: > One or more messages are settled. + stability: experimental brief: > A string identifying the kind of messaging operation. note: If a custom value is used, it MUST be of low cardinality. tag: messaging-generic - id: rabbitmq.destination.routing_key type: string + stability: experimental brief: > RabbitMQ message routing key. examples: 'myKey' tag: tech-specific-rabbitmq - id: rabbitmq.message.delivery_tag type: int + stability: experimental brief: > RabbitMQ message delivery tag examples: 123 @@ -168,6 +188,7 @@ groups: - id: rocketmq.client_group type: string + stability: experimental brief: > Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. examples: 'myConsumerGroup' @@ -182,35 +203,41 @@ groups: - id: broadcasting value: 'broadcasting' brief: 'Broadcasting consumption model' + stability: experimental brief: > Model of message consumption. This only applies to consumer spans. tag: tech-specific-rocketmq - id: rocketmq.message.delay_time_level type: int + stability: experimental brief: > The delay time level for delay message, which determines the message delay time. examples: 3 tag: tech-specific-rocketmq - id: rocketmq.message.delivery_timestamp type: int + stability: experimental brief: > The timestamp in milliseconds that the delay message is expected to be delivered to consumer. examples: 1665987217045 tag: tech-specific-rocketmq - id: rocketmq.message.group type: string + stability: experimental 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' tag: tech-specific-rocketmq - id: rocketmq.message.keys type: string[] + stability: experimental brief: > Key(s) of message, another way to mark message besides message id. examples: ['keyA', 'keyB'] tag: tech-specific-rocketmq - id: rocketmq.message.tag type: string + stability: experimental brief: > The secondary classifier of message besides topic. examples: tagA @@ -231,17 +258,20 @@ groups: - id: transaction value: 'transaction' brief: 'Transaction message' + stability: experimental brief: > Type of message. tag: tech-specific-rocketmq - id: rocketmq.namespace type: string + stability: experimental brief: > Namespace of RocketMQ resources, resources in different namespaces are individual. examples: 'myNamespace' tag: tech-specific-rocketmq - id: gcp_pubsub.message.ordering_key type: string + stability: experimental 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' @@ -282,21 +312,25 @@ groups: - id: rocketmq value: 'rocketmq' brief: 'Apache RocketMQ' + stability: experimental tag: messaging-generic - id: servicebus.message.delivery_count type: int + stability: experimental brief: > Number of deliveries that have been attempted for this message. examples: 2 tag: tech-specific-servicebus - id: servicebus.message.enqueued_time type: int + stability: experimental brief: > The UTC epoch seconds at which the message has been accepted and stored in the entity. examples: 1701393730 tag: tech-specific-servicebus - id: servicebus.destination.subscription_name type: string + stability: experimental brief: > The name of the subscription in the topic messages are received from. examples: "mySubscription" @@ -323,18 +357,21 @@ groups: tag: tech-specific-servicebus - id: eventhubs.message.enqueued_time type: int + stability: experimental brief: > The UTC epoch seconds at which the message has been accepted and stored in the entity. examples: 1701393730 tag: tech-specific-eventhubs - id: eventhubs.destination.partition.id type: string + stability: experimental brief: > The identifier of the partition messages are sent to or received from, unique to the Event Hub which contains it. examples: '1' tag: tech-specific-eventhubs - id: eventhubs.consumer.group type: string + stability: experimental brief: > The name of the consumer group the event consumer is associated with. examples: 'indexer' diff --git a/model/registry/network.yaml b/model/registry/network.yaml index 7715506bcc..e7520bae9c 100644 --- a/model/registry/network.yaml +++ b/model/registry/network.yaml @@ -7,18 +7,22 @@ groups: attributes: - id: carrier.icc type: string + stability: experimental brief: "The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network." examples: "DE" - id: carrier.mcc type: string + stability: experimental brief: "The mobile carrier country code." examples: "310" - id: carrier.mnc type: string + stability: experimental brief: "The mobile carrier network code." examples: "001" - id: carrier.name type: string + stability: experimental brief: "The name of the mobile carrier." examples: "sprint" - id: connection.subtype @@ -88,6 +92,7 @@ groups: - id: lte_ca brief: LTE CA value: "lte_ca" + stability: experimental 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 @@ -104,6 +109,7 @@ groups: value: "unavailable" - id: unknown value: "unknown" + stability: experimental brief: 'The internet connection type.' examples: 'wifi' - id: local.address @@ -190,5 +196,6 @@ groups: value: 'transmit' - id: receive value: 'receive' + stability: experimental brief: "The network IO operation direction." examples: ["transmit"] diff --git a/model/registry/oci.yaml b/model/registry/oci.yaml index 24e0cb93f2..00d0e28c2b 100644 --- a/model/registry/oci.yaml +++ b/model/registry/oci.yaml @@ -7,6 +7,7 @@ groups: attributes: - id: digest type: string + stability: experimental brief: > The digest of the OCI image manifest. For container images specifically is the digest by which the container image is known. diff --git a/model/registry/os.yaml b/model/registry/os.yaml index af8dbfcd2a..113901906a 100644 --- a/model/registry/os.yaml +++ b/model/registry/os.yaml @@ -47,23 +47,28 @@ groups: brief: "IBM z/OS" brief: > The operating system type. + stability: experimental - id: description type: string + stability: experimental 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 + stability: experimental brief: 'Human readable operating system name.' examples: ['iOS', 'Android', 'Ubuntu'] - id: version type: string + stability: experimental 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 + stability: experimental 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 index e4b5c230bd..4279a9e33a 100644 --- a/model/registry/process.yaml +++ b/model/registry/process.yaml @@ -7,16 +7,19 @@ groups: attributes: - id: pid type: int + stability: experimental brief: > Process identifier (PID). examples: [1234] - id: parent_pid type: int + stability: experimental brief: > Parent Process identifier (PPID). examples: [111] - id: executable.name type: string + stability: experimental 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 @@ -24,6 +27,7 @@ groups: examples: ['otelcol'] - id: executable.path type: string + stability: experimental 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 @@ -31,6 +35,7 @@ groups: examples: ['/usr/bin/cmd/otelcol'] - id: command type: string + stability: experimental 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`. @@ -38,6 +43,7 @@ groups: examples: ['cmd/otelcol'] - id: command_line type: string + stability: experimental 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`. @@ -46,6 +52,7 @@ groups: examples: ['C:\cmd\otecol --config="my directory\config.yaml"'] - id: command_args type: string[] + stability: experimental brief: > All the command arguments (including the command/executable itself) as received by the process. On Linux-based systems (and some other Unixoid @@ -55,23 +62,27 @@ groups: examples: ['cmd/otecol', '--config=config.yaml'] - id: owner type: string + stability: experimental brief: > The username of the user that owns the process. examples: 'root' - id: runtime.name type: string + stability: experimental 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 + stability: experimental 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 + stability: experimental brief: > An additional description about the runtime of the process, for example a specific vendor customization of the runtime environment. diff --git a/model/registry/rpc.yaml b/model/registry/rpc.yaml index 64f1f9a667..cfc1e45017 100644 --- a/model/registry/rpc.yaml +++ b/model/registry/rpc.yaml @@ -39,9 +39,11 @@ groups: value: data_loss - id: unauthenticated value: unauthenticated + stability: experimental 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[]] + stability: experimental brief: > Connect request metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. note: > @@ -50,6 +52,7 @@ groups: examples: ['rpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]'] - id: connect_rpc.response.metadata type: template[string[]] + stability: experimental brief: > Connect response metadata, `` being the normalized Connect Metadata key (lowercase), the value being the metadata values. note: > @@ -110,9 +113,11 @@ groups: - id: unauthenticated brief: UNAUTHENTICATED value: 16 + stability: experimental 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[]] + stability: experimental brief: > gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. note: > @@ -121,6 +126,7 @@ groups: examples: ['rpc.grpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]'] - id: grpc.response.metadata type: template[string[]] + stability: experimental brief: > gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase), the value being the metadata values. note: > @@ -129,14 +135,17 @@ groups: examples: ['rpc.grpc.response.metadata.my-custom-metadata-attribute=["attribute_value"]'] - id: jsonrpc.error_code type: int + stability: experimental brief: "`error.code` property of response if it is an error response." examples: [-32700, 100] - id: jsonrpc.error_message type: string + stability: experimental brief: "`error.message` property of response if it is an error response." examples: ['Parse error', 'User already exists'] - id: jsonrpc.request_id type: string + stability: experimental brief: > `id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), @@ -145,10 +154,12 @@ groups: examples: ['10', 'request-7', ''] - id: jsonrpc.version type: string + stability: experimental 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 + stability: experimental 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, @@ -159,6 +170,7 @@ groups: examples: "exampleMethod" - id: service type: string + stability: experimental 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, @@ -188,3 +200,4 @@ groups: - id: connect_rpc value: 'connect_rpc' brief: 'Connect RPC' + stability: experimental diff --git a/model/registry/source.yaml b/model/registry/source.yaml index 263a491cab..2f9a967919 100644 --- a/model/registry/source.yaml +++ b/model/registry/source.yaml @@ -12,6 +12,7 @@ groups: attributes: - id: address type: string + stability: experimental 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 @@ -19,5 +20,6 @@ groups: examples: ['source.example.com', '10.1.2.80', '/tmp/my.sock'] - id: port type: int + stability: experimental brief: 'Source port number' examples: [3389, 2888] diff --git a/model/registry/thread.yaml b/model/registry/thread.yaml index f6b5b5a509..688b0ec8e2 100644 --- a/model/registry/thread.yaml +++ b/model/registry/thread.yaml @@ -7,11 +7,13 @@ groups: attributes: - id: id type: int + stability: experimental brief: > Current "managed" thread ID (as opposed to OS thread ID). examples: 42 - id: name type: string + stability: experimental brief: > Current thread name. examples: main diff --git a/model/registry/tls.yaml b/model/registry/tls.yaml index 421479d18a..1f0c880bc2 100644 --- a/model/registry/tls.yaml +++ b/model/registry/tls.yaml @@ -8,6 +8,7 @@ groups: brief: > String indicating the [cipher](https://datatracker.ietf.org/doc/html/rfc5246#appendix-A.5) used during the current connection. type: string + stability: experimental 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). @@ -18,29 +19,34 @@ groups: ] - id: client.certificate type: string + stability: experimental 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[] + stability: experimental 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 + stability: experimental 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 + stability: experimental 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 + stability: experimental 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. @@ -48,31 +54,38 @@ groups: ["0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0"] - id: client.issuer type: string + stability: experimental 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 + stability: experimental brief: "A hash that identifies clients based on how they perform an SSL/TLS handshake." examples: ["d4e5b18d6b55c71272893221c96ba240"] - id: client.not_after type: string + stability: experimental 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 + stability: experimental brief: "Date/Time indicating when client certificate is first considered valid." examples: ["1970-01-01T00:00:00.000Z"] - id: client.server_name type: string + stability: experimental 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 + stability: experimental 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[] + stability: experimental brief: Array of ciphers offered by the client during the client hello. examples: [ @@ -81,10 +94,12 @@ groups: - id: curve brief: "String indicating the curve used for the given cipher, when applicable" type: string + stability: experimental examples: ["secp256r1"] - id: established brief: "Boolean flag indicating if the TLS negotiation was successful and transitioned to an encrypted tunnel." type: boolean + stability: experimental examples: [true] - id: next_protocol brief: > @@ -92,6 +107,7 @@ groups: 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 + stability: experimental examples: ["http/1.1"] - id: protocol.name brief: > @@ -103,40 +119,48 @@ groups: value: ssl - id: tls value: tls + stability: experimental - 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 + stability: experimental examples: ["1.2", "3"] - id: resumed brief: "Boolean flag indicating if this TLS connection was resumed from an existing TLS negotiation." type: boolean + stability: experimental examples: [true] - id: server.certificate type: string + stability: experimental 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[] + stability: experimental 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 + stability: experimental 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 + stability: experimental 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 + stability: experimental 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. @@ -144,22 +168,27 @@ groups: ["0687F666A054EF17A08E2F2162EAB4CBC0D265E1D7875BE74BF3C712CA92DAF0"] - id: server.issuer type: string + stability: experimental 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 + stability: experimental brief: "A hash that identifies servers based on how they perform an SSL/TLS handshake." examples: ["d4e5b18d6b55c71272893221c96ba240"] - id: server.not_after type: string + stability: experimental 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 + stability: experimental brief: "Date/Time indicating when server certificate is first considered valid." examples: ["1970-01-01T00:00:00.000Z"] - id: server.subject type: string + stability: experimental 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 index 7e07ad7936..624ad90ba3 100644 --- a/model/registry/url.yaml +++ b/model/registry/url.yaml @@ -6,6 +6,7 @@ groups: attributes: - id: domain type: string + stability: experimental brief: > Domain extracted from the `url.full`, such as "opentelemetry.io". note: > @@ -16,6 +17,7 @@ groups: examples: ["www.foo.bar", "opentelemetry.io", "3.12.167.2", "[1080:0:0:0:8:800:200C:417A]"] - id: extension type: string + stability: experimental brief: > The file extension extracted from the `url.full`, excluding the leading dot. note: > @@ -44,6 +46,7 @@ groups: examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv', '//localhost'] - id: original type: string + stability: experimental brief: > Unmodified original URL as seen in the event source. note: > @@ -63,6 +66,7 @@ groups: Sensitive content provided in `url.path` SHOULD be scrubbed when instrumentations can identify it. - id: port type: int + stability: experimental brief: > Port extracted from the `url.full` examples: [443] @@ -76,6 +80,7 @@ groups: Sensitive content provided in `url.query` SHOULD be scrubbed when instrumentations can identify it. - id: registered_domain type: string + stability: experimental brief: > The highest registered url domain, stripped of the subdomain. examples: ["example.com", "foo.co.uk"] @@ -91,6 +96,7 @@ groups: examples: ["https", "ftp", "telnet"] - id: subdomain type: string + stability: experimental brief: > The subdomain portion of a fully qualified domain name includes all of the names except the host name under the registered_domain. In a partially qualified domain, or if the the qualification level of the @@ -101,6 +107,7 @@ groups: such as `sub2.sub1.example.com`, the subdomain field should contain `sub2.sub1`, with no trailing period. - id: top_level_domain type: string + stability: experimental brief: > The effective top level domain (eTLD), also known as the domain suffix, is the last part of the domain name. For example, the top level domain for example.com is `com`. diff --git a/model/registry/user-agent.yaml b/model/registry/user-agent.yaml index f783d379e5..5503454d22 100644 --- a/model/registry/user-agent.yaml +++ b/model/registry/user-agent.yaml @@ -14,6 +14,7 @@ groups: 'YourApp/1.0.0 grpc-java-okhttp/1.27.2'] - id: name type: string + stability: experimental brief: > Name of the user-agent extracted from original. Usually refers to the browser's name. examples: ['Safari', 'YourApp'] @@ -24,6 +25,7 @@ groups: `user_agent.version` - id: version type: string + stability: experimental brief: > Version of the user-agent extracted from original. Usually refers to the browser's version examples: ['14.1.2', '1.0.0'] diff --git a/model/resource/android.yaml b/model/resource/android.yaml index dcc236d846..cf4040f514 100644 --- a/model/resource/android.yaml +++ b/model/resource/android.yaml @@ -7,6 +7,7 @@ groups: attributes: - id: os.api_level type: string + stability: experimental brief: > Uniquely identifies the framework API revision offered by a version (`os.version`) of the android operating system. More information can be found diff --git a/model/resource/cloud_provider/aws/ecs.yaml b/model/resource/cloud_provider/aws/ecs.yaml index a40f950c18..a3c4b3f8b1 100644 --- a/model/resource/cloud_provider/aws/ecs.yaml +++ b/model/resource/cloud_provider/aws/ecs.yaml @@ -7,11 +7,13 @@ groups: attributes: - id: container.arn type: string + stability: experimental brief: > The Amazon Resource Name (ARN) of an [ECS container instance](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_instances.html). examples: ['arn:aws:ecs:us-west-1:123456789123:container/32624152-9086-4f0e-acae-1a75b14fe4d9'] - id: cluster.arn type: string + stability: experimental brief: > The ARN of an [ECS cluster](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/clusters.html). examples: ['arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster'] @@ -23,10 +25,12 @@ groups: value: "ec2" - id: fargate value: "fargate" + stability: experimental brief: > The [launch type](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/launch_types.html) for an ECS task. - id: task.arn type: string + stability: experimental brief: > The ARN of a running [ECS task](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-account-settings.html#ecs-resource-ids). examples: [ @@ -35,11 +39,13 @@ groups: ] - id: task.family type: string + stability: experimental brief: > The family name of the [ECS task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) used to create the ECS task. examples: ['opentelemetry-family'] - id: task.id type: string + stability: experimental brief: > The ID of a running ECS task. The ID MUST be extracted from `task.arn`. requirement_level: @@ -47,6 +53,7 @@ groups: examples: [ '10838bed-421f-43ef-870a-f43feacbbb5b', '23ebb8ac-c18f-46c6-8bbe-d55d0e37cfbd' ] - id: task.revision type: string + stability: experimental brief: > The revision for the task definition used to create the ECS task. examples: ["8", "26"] diff --git a/model/resource/cloud_provider/aws/eks.yaml b/model/resource/cloud_provider/aws/eks.yaml index 2c897253ee..8eafc481aa 100644 --- a/model/resource/cloud_provider/aws/eks.yaml +++ b/model/resource/cloud_provider/aws/eks.yaml @@ -7,6 +7,7 @@ groups: attributes: - id: cluster.arn type: string + stability: experimental brief: > The ARN of an EKS cluster. examples: ['arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster'] diff --git a/model/resource/cloud_provider/aws/logs.yaml b/model/resource/cloud_provider/aws/logs.yaml index 8a433629bb..35889e137c 100644 --- a/model/resource/cloud_provider/aws/logs.yaml +++ b/model/resource/cloud_provider/aws/logs.yaml @@ -7,6 +7,7 @@ groups: attributes: - id: group.names type: string[] + stability: experimental brief: > The name(s) of the AWS log group(s) an application is writing to. examples: ['/aws/lambda/my-function', 'opentelemetry-service'] @@ -16,6 +17,7 @@ groups: group. - id: group.arns type: string[] + stability: experimental brief: > The Amazon Resource Name(s) (ARN) of the AWS log group(s). examples: ['arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:*'] @@ -24,11 +26,13 @@ groups: [log group ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). - id: stream.names type: string[] + stability: experimental brief: > The name(s) of the AWS log stream(s) an application is writing to. examples: ['logs/main/10838bed-421f-43ef-870a-f43feacbbb5b'] - id: stream.arns type: string[] + stability: experimental brief: > The ARN(s) of the AWS log stream(s). examples: ['arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:log-stream:logs/main/10838bed-421f-43ef-870a-f43feacbbb5b'] diff --git a/model/resource/cloud_provider/gcp/cloud_run.yaml b/model/resource/cloud_provider/gcp/cloud_run.yaml index e4da8f5929..269f4a6f84 100644 --- a/model/resource/cloud_provider/gcp/cloud_run.yaml +++ b/model/resource/cloud_provider/gcp/cloud_run.yaml @@ -7,6 +7,7 @@ groups: attributes: - id: job.execution type: string + stability: experimental brief: > The name of the Cloud Run [execution](https://cloud.google.com/run/docs/managing/job-executions) @@ -16,6 +17,7 @@ groups: examples: ['job-name-xxxx', 'sample-job-mdw84'] - id: job.task_index type: int + stability: experimental brief: > The index for a task within an execution as provided by the [`CLOUD_RUN_TASK_INDEX`](https://cloud.google.com/run/docs/container-contract#jobs-env-vars) diff --git a/model/resource/cloud_provider/gcp/gce.yaml b/model/resource/cloud_provider/gcp/gce.yaml index 879d0ea388..22b96628dc 100644 --- a/model/resource/cloud_provider/gcp/gce.yaml +++ b/model/resource/cloud_provider/gcp/gce.yaml @@ -7,6 +7,7 @@ groups: attributes: - id: instance.name type: string + stability: experimental brief: > The instance name of a GCE instance. This is the value provided by `host.name`, the visible name of the instance in @@ -17,6 +18,7 @@ groups: examples: ['instance-1', 'my-vm-name'] - id: instance.hostname type: string + stability: experimental brief: > The hostname of a GCE instance. This is the full value of the default or [custom hostname](https://cloud.google.com/compute/docs/instances/custom-hostname-vm). examples: ['my-host1234.example.com', 'sample-vm.us-west1-b.c.my-project.internal'] diff --git a/model/resource/cloud_provider/heroku.yaml b/model/resource/cloud_provider/heroku.yaml index e73eddc1e7..c8f7e34143 100644 --- a/model/resource/cloud_provider/heroku.yaml +++ b/model/resource/cloud_provider/heroku.yaml @@ -7,18 +7,21 @@ groups: attributes: - id: release.creation_timestamp type: string + stability: experimental brief: > Time and date the release was created examples: [ '2022-10-23T18:00:42Z' ] requirement_level: opt_in - id: release.commit type: string + stability: experimental brief: > Commit hash for the current release examples: [ 'e6134959463efd8966b20e75b913cafe3f5ec' ] requirement_level: opt_in - id: app.id type: string + stability: experimental brief: > Unique identifier for the application examples: [ '2daa2797-e42b-4624-9322-ec3f968df4da' ] diff --git a/model/resource/deployment_environment.yaml b/model/resource/deployment_environment.yaml index 7ada3f9798..bc2574386a 100644 --- a/model/resource/deployment_environment.yaml +++ b/model/resource/deployment_environment.yaml @@ -7,6 +7,7 @@ groups: attributes: - id: environment type: string + stability: experimental brief: > Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). diff --git a/model/resource/faas.yaml b/model/resource/faas.yaml index 7f1a02e0e0..e73ee38646 100644 --- a/model/resource/faas.yaml +++ b/model/resource/faas.yaml @@ -7,6 +7,7 @@ groups: attributes: - id: name type: string + stability: experimental requirement_level: required brief: > The name of the single function that this runtime instance executes. @@ -30,6 +31,7 @@ groups: examples: ['my-function', 'myazurefunctionapp/some-function-name'] - id: version type: string + stability: experimental brief: The immutable version of the function being executed. note: | Depending on the cloud provider and platform, use: @@ -44,6 +46,7 @@ groups: examples: ['26', 'pinkfroid-00002'] - id: instance type: string + stability: experimental brief: > The execution environment ID as a string, that will be potentially reused for other invocations to the same function/function version. @@ -52,6 +55,7 @@ groups: examples: ['2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de'] - id: max_memory type: int + stability: experimental brief: > The amount of memory available to the serverless function converted to Bytes. note: > diff --git a/model/resource/service_experimental.yaml b/model/resource/service_experimental.yaml index 99ed64f024..a11a30a048 100644 --- a/model/resource/service_experimental.yaml +++ b/model/resource/service_experimental.yaml @@ -7,6 +7,7 @@ groups: attributes: - id: namespace type: string + stability: experimental brief: > A namespace for `service.name`. note: > @@ -20,6 +21,7 @@ groups: examples: ["Shop"] - id: instance.id type: string + stability: experimental brief: > The string ID of the service instance. note: | diff --git a/model/resource/telemetry_experimental.yaml b/model/resource/telemetry_experimental.yaml index 8f7b23554b..6569c8ff87 100644 --- a/model/resource/telemetry_experimental.yaml +++ b/model/resource/telemetry_experimental.yaml @@ -7,6 +7,7 @@ groups: attributes: - id: distro.name type: string + stability: experimental brief: > The name of the auto instrumentation agent or distribution, if used. note: | @@ -15,6 +16,7 @@ groups: examples: ["parts-unlimited-java"] - id: distro.version type: string + stability: experimental brief: > The version string of the auto instrumentation agent or distribution, if used. examples: ["1.2.3"] diff --git a/model/resource/webengine.yaml b/model/resource/webengine.yaml index 5e0cdf8fab..10485dcc18 100644 --- a/model/resource/webengine.yaml +++ b/model/resource/webengine.yaml @@ -7,17 +7,20 @@ groups: attributes: - id: name type: string + stability: experimental requirement_level: required brief: > The name of the web engine. examples: ['WildFly'] - id: version type: string + stability: experimental brief: > The version of the web engine. examples: ['21.0.0'] - id: description type: string + stability: experimental brief: > Additional description of the web engine (e.g. detailed version and edition information). examples: ['WildFly Full 21.0.0.Final (WildFly Core 13.0.1.Final) - 2.2.2.Final'] diff --git a/model/scope/exporter/exporter.yaml b/model/scope/exporter/exporter.yaml index 0a47d625a9..259061d3ad 100644 --- a/model/scope/exporter/exporter.yaml +++ b/model/scope/exporter/exporter.yaml @@ -22,11 +22,11 @@ groups: attributes: - id: name type: string - stability: "deprecated" - brief: Deprecated, use the `otel.scope.name` attribute. + deprecated: use the `otel.scope.name` attribute. + brief: examples: ['io.opentelemetry.contrib.mongodb'] - id: version type: string - stability: "deprecated" - brief: Deprecated, use the `otel.scope.version` attribute. + deprecated: use the `otel.scope.version` attribute. + brief: examples: ['1.0.0'] diff --git a/model/session.yaml b/model/session.yaml index f221265338..ee09ffe1f3 100644 --- a/model/session.yaml +++ b/model/session.yaml @@ -16,11 +16,13 @@ groups: attributes: - id: id type: string + stability: experimental brief: "A unique id to identify a session." examples: "00112233-4455-6677-8899-aabbccddeeff" requirement_level: opt_in - id: previous_id type: string + stability: experimental 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/aws/lambda.yaml b/model/trace/aws/lambda.yaml index 73e77ea747..795736f5ed 100644 --- a/model/trace/aws/lambda.yaml +++ b/model/trace/aws/lambda.yaml @@ -7,6 +7,7 @@ groups: attributes: - id: invoked_arn type: string + stability: experimental brief: > The full invoked ARN as provided on the `Context` passed to the function (`Lambda-Runtime-Invoked-Function-Arn` header on the `/runtime/invocation/next` applicable). diff --git a/model/trace/cloudevents.yaml b/model/trace/cloudevents.yaml index 6fcf7ae268..931b082f94 100644 --- a/model/trace/cloudevents.yaml +++ b/model/trace/cloudevents.yaml @@ -9,28 +9,33 @@ groups: attributes: - id: event_id type: string + stability: experimental requirement_level: required brief: > The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event. examples: ['123e4567-e89b-12d3-a456-426614174000', '0001'] - id: event_source type: string + stability: experimental requirement_level: required brief: > The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened. examples: ['https://github.com/cloudevents', '/cloudevents/spec/pull/123', 'my-service' ] - id: event_spec_version type: string + stability: experimental brief: > The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses. examples: '1.0' - id: event_type type: string + stability: experimental brief: > The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence. examples: ['com.github.pull_request.opened', 'com.example.object.deleted.v2'] - id: event_subject type: string + stability: experimental brief: > The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source). examples: 'mynewfile.jpg' diff --git a/model/trace/compatibility.yaml b/model/trace/compatibility.yaml index 2e3fe12dc7..b24b39a339 100644 --- a/model/trace/compatibility.yaml +++ b/model/trace/compatibility.yaml @@ -8,6 +8,7 @@ groups: attributes: - id: ref_type brief: 'Parent-child Reference type' + stability: experimental note: > The causal relationship between a child Span and a parent Span. type: diff --git a/model/trace/faas.yaml b/model/trace/faas.yaml index 84b7141b38..3eb9b53354 100644 --- a/model/trace/faas.yaml +++ b/model/trace/faas.yaml @@ -20,6 +20,7 @@ groups: call to invoke the lambda, which is often HTTP). - id: invocation_id type: string + stability: experimental brief: 'The invocation ID of the current function invocation.' examples: 'af9d5aa4-a685-4c5f-a22b-444f80b3cc28' - ref: cloud.resource_id @@ -33,6 +34,7 @@ groups: attributes: - id: collection type: string + stability: experimental requirement_level: required brief: > The name of the source on which the triggering operation was performed. @@ -40,6 +42,7 @@ groups: and in Cosmos DB to the database name. examples: ['myBucketName', 'myDbName'] - id: operation + stability: experimental requirement_level: required type: allow_custom_values: true @@ -56,6 +59,7 @@ groups: brief: 'Describes the type of the operation that was performed on the data.' - id: time type: string + stability: experimental brief: > A string containing the time when the data was accessed in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) @@ -63,6 +67,7 @@ groups: examples: "2020-01-23T13:47:06Z" - id: name type: string + stability: experimental brief: > The document name/table subjected to the operation. For example, in Cloud Storage or S3 is the name of @@ -76,7 +81,6 @@ groups: source operation such as a database or filesystem read/write. constraints: - include: trace.http.server - attributes: [] - id: faas_span.pubsub type: span @@ -85,7 +89,6 @@ groups: sent to a messaging system. constraints: - include: messaging - attributes: [] - id: faas_span.timer prefix: faas @@ -95,6 +98,7 @@ groups: attributes: - id: time type: string + stability: experimental brief: > A string containing the function invocation time in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) @@ -102,6 +106,7 @@ groups: examples: "2020-01-23T13:47:06Z" - id: cron type: string + stability: experimental brief: > A string containing the schedule period as [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). @@ -116,6 +121,7 @@ groups: attributes: - id: coldstart type: boolean + stability: experimental brief: > A boolean that is true if the serverless function is executed for the first time (aka cold-start). diff --git a/model/trace/feature-flag.yaml b/model/trace/feature-flag.yaml index 50706ba2d7..b6bc1ba1dc 100644 --- a/model/trace/feature-flag.yaml +++ b/model/trace/feature-flag.yaml @@ -8,16 +8,19 @@ groups: attributes: - id: key type: string + stability: experimental requirement_level: required brief: The unique identifier of the feature flag. examples: ["logo-color"] - id: provider_name type: string + stability: experimental requirement_level: recommended brief: The name of the service provider that performs the flag evaluation. examples: ["Flag Manager"] - id: variant type: string + stability: experimental requirement_level: recommended examples: ["red", "true", "on"] brief: > diff --git a/model/trace/instrumentation/aws-sdk.yml b/model/trace/instrumentation/aws-sdk.yml index 90b6d1c967..552914670a 100644 --- a/model/trace/instrumentation/aws-sdk.yml +++ b/model/trace/instrumentation/aws-sdk.yml @@ -28,6 +28,7 @@ groups: - PutItem - id: request_id type: string + stability: experimental brief: "The AWS request ID as returned in the response headers `x-amz-request-id` or `x-amz-requestid`." examples: - 79b9da39-b7ae-508a-a6bc-864b2829c622 @@ -56,12 +57,14 @@ groups: - PutItem - id: table_names type: string[] + stability: experimental brief: The keys in the `RequestItems` object field. examples: - Users - Cats - id: consumed_capacity type: string[] + stability: experimental brief: "The JSON-serialized value of each item in the `ConsumedCapacity` response field." examples: - '{ @@ -91,6 +94,7 @@ groups: }' - id: item_collection_metrics type: string + stability: experimental brief: "The JSON-serialized value of the `ItemCollectionMetrics` response field." examples: - '{ @@ -120,21 +124,25 @@ groups: }' - id: provisioned_read_capacity type: double + stability: experimental brief: "The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter." examples: - 1.0 - 2.0 - id: provisioned_write_capacity type: double + stability: experimental brief: "The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter." examples: - 1.0 - 2.0 - id: consistent_read type: boolean + stability: experimental brief: "The value of the `ConsistentRead` request parameter." - id: projection type: string + stability: experimental brief: "The value of the `ProjectionExpression` request parameter." examples: - Title @@ -142,22 +150,26 @@ groups: - Title, Description, RelatedItems, ProductReviews - id: limit type: int + stability: experimental brief: "The value of the `Limit` request parameter." examples: - 10 - id: attributes_to_get type: string[] + stability: experimental brief: "The value of the `AttributesToGet` request parameter." examples: - lives - id - id: index_name type: string + stability: experimental brief: "The value of the `IndexName` request parameter." examples: - name_to_group - id: select type: string + stability: experimental brief: "The value of the `Select` request parameter." examples: - ALL_ATTRIBUTES @@ -190,6 +202,7 @@ groups: attributes: - id: global_secondary_indexes type: string[] + stability: experimental brief: "The JSON-serialized value of each item of the `GlobalSecondaryIndexes` request field" examples: - '{ @@ -211,6 +224,7 @@ groups: }' - id: local_secondary_indexes type: string[] + stability: experimental brief: "The JSON-serialized value of each item of the `LocalSecondaryIndexes` request field." examples: - '{ @@ -295,12 +309,14 @@ groups: attributes: - id: exclusive_start_table type: string + stability: experimental brief: "The value of the `ExclusiveStartTableName` request parameter." examples: - Users - CatsTable - id: table_count type: int + stability: experimental brief: "The the number of items in the `TableNames` response parameter." examples: - 20 @@ -324,6 +340,7 @@ groups: attributes: - id: scan_forward type: boolean + stability: experimental brief: "The value of the `ScanIndexForward` request parameter." - ref: aws.dynamodb.table_names brief: "A single-element array with the value of the TableName request parameter." @@ -345,21 +362,25 @@ groups: attributes: - id: segment type: int + stability: experimental brief: "The value of the `Segment` request parameter." examples: - 10 - id: total_segments type: int + stability: experimental brief: "The value of the `TotalSegments` request parameter." examples: - 100 - id: count type: int + stability: experimental brief: "The value of the `Count` response parameter." examples: - 10 - id: scanned_count type: int + stability: experimental brief: "The value of the `ScannedCount` response parameter." examples: - 50 @@ -396,6 +417,7 @@ groups: attributes: - id: attribute_definitions type: string[] + stability: experimental brief: "The JSON-serialized value of each item in the `AttributeDefinitions` request field." examples: - '{ @@ -404,6 +426,7 @@ groups: }' - id: global_secondary_index_updates type: string[] + stability: experimental brief: "The JSON-serialized value of each item in the the `GlobalSecondaryIndexUpdates` request field." examples: - '{ @@ -440,6 +463,7 @@ groups: attributes: - id: bucket type: string + stability: experimental brief: "The S3 bucket name the request refers to. Corresponds to the `--bucket` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations." examples: - some-bucket-name @@ -448,6 +472,7 @@ groups: This applies to almost all S3 operations except `list-buckets`. - id: key type: string + stability: experimental brief: "The S3 object key the request refers to. Corresponds to the `--key` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations." examples: - someFile.yml @@ -470,6 +495,7 @@ groups: - [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) - id: copy_source type: string + stability: experimental brief: "The source object (in the form `bucket`/`key`) for the copy operation." examples: - someFile.yml @@ -482,6 +508,7 @@ groups: - [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) - id: upload_id type: string + stability: experimental brief: "Upload ID that identifies the multipart upload." examples: - 'dfRtDYWFbkRONycy.Yxwh66Yjlx.cph0gtNBtJ' @@ -497,6 +524,7 @@ groups: - [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) - id: delete type: string + stability: experimental brief: "The delete request container that specifies the objects to be deleted." examples: - 'Objects=[{Key=string,VersionId=string},{Key=string,VersionId=string}],Quiet=boolean' @@ -506,6 +534,7 @@ groups: [delete-objects operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-objects.html). - id: part_number type: int + stability: experimental brief: "The part number of the part being uploaded in a multipart-upload operation. This is a positive integer between 1 and 10,000." examples: - 3456 diff --git a/model/trace/instrumentation/graphql.yml b/model/trace/instrumentation/graphql.yml index 88af65e98e..f3f28d1585 100644 --- a/model/trace/instrumentation/graphql.yml +++ b/model/trace/instrumentation/graphql.yml @@ -9,9 +9,11 @@ groups: - id: operation.name brief: "The name of the operation being executed." type: string + stability: experimental examples: 'findBookById' - id: operation.type brief: "The type of the operation being executed." + stability: experimental type: allow_custom_values: false members: @@ -28,5 +30,6 @@ groups: - id: document brief: "The GraphQL document being executed." type: string + stability: experimental note: The value may be sanitized to exclude sensitive information. examples: 'query findBookById { bookById(id: ?) { name } }' diff --git a/model/trace/rpc.yaml b/model/trace/rpc.yaml index de36d6767a..42a3211d26 100644 --- a/model/trace/rpc.yaml +++ b/model/trace/rpc.yaml @@ -100,16 +100,20 @@ groups: value: "SENT" - id: received value: "RECEIVED" + stability: experimental brief: "Whether this is a received or sent message." - id: id type: int + stability: experimental brief: "MUST be calculated as two different counters starting from `1` one for sent messages and one for received message." note: "This way we guarantee that the values will be consistent between different implementations." - id: compressed_size type: int + stability: experimental brief: "Compressed size of the message in bytes." - id: uncompressed_size type: int + stability: experimental brief: "Uncompressed size of the message in bytes." - id: rpc.connect_rpc From 0e945f169e26ca502bb2233f6e8c941a31eac83d Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Wed, 6 Mar 2024 11:30:13 +0100 Subject: [PATCH 16/22] [chore] Improve check/fix make targets (#787) --- .prettierignore | 1 + CONTRIBUTING.md | 32 +++++++------- Makefile | 7 +-- docs/cloudevents/cloudevents-spans.md | 8 ++-- docs/database/database-metrics.md | 18 ++++---- docs/database/database-spans.md | 2 +- docs/dotnet/dotnet-aspnetcore-metrics.md | 14 +++--- docs/dotnet/dotnet-dns-metrics.md | 2 +- docs/dotnet/dotnet-http-metrics.md | 14 +++--- docs/exceptions/exceptions-logs.md | 2 +- docs/exceptions/exceptions-spans.md | 2 +- docs/faas/aws-lambda.md | 18 ++++---- docs/faas/faas-metrics.md | 22 +++++----- docs/faas/faas-spans.md | 18 ++++---- docs/general/attributes.md | 26 ++++++------ docs/general/logs.md | 4 +- docs/general/metrics.md | 20 ++++----- docs/http/http-metrics.md | 14 +++--- docs/http/http-spans.md | 28 ++++++------ docs/messaging/kafka.md | 2 +- docs/messaging/messaging-metrics.md | 12 +++--- docs/messaging/messaging-spans.md | 42 +++++++++--------- docs/mobile/events.md | 4 +- docs/resource/README.md | 4 +- docs/resource/process.md | 14 +++--- docs/rpc/rpc-metrics.md | 26 ++++++------ docs/rpc/rpc-spans.md | 14 +++--- docs/runtime/README.md | 2 +- docs/runtime/jvm-metrics.md | 36 ++++++++-------- docs/system/hardware-metrics.md | 32 +++++++------- docs/system/process-metrics.md | 20 ++++----- docs/system/system-metrics.md | 54 ++++++++++++------------ 32 files changed, 258 insertions(+), 256 deletions(-) diff --git a/.prettierignore b/.prettierignore index aa4edb3751..001890f677 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,4 +1,5 @@ /.github +/.chloggen # for the first iteration, we only reformat /docs/cloud* and will add the rest in individual PRs /docs/** diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0639de51d0..8e5b78e834 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,23 +13,23 @@ requirements and recommendations. - [Sign the CLA](#sign-the-cla) - [How to Contribute](#how-to-contribute) - * [Prerequisites](#prerequisites) - * [1. Modify the YAML model](#1-modify-the-yaml-model) - + [Schema files](#schema-files) - * [2. Update the markdown files](#2-update-the-markdown-files) - + [Hugo frontmatter](#hugo-frontmatter) - * [3. Verify the changes before committing](#3-verify-the-changes-before-committing) - * [4. Changelog](#4-changelog) - + [When to add a Changelog Entry](#when-to-add-a-changelog-entry) + - [Prerequisites](#prerequisites) + - [1. Modify the YAML model](#1-modify-the-yaml-model) + - [Schema files](#schema-files) + - [2. Update the markdown files](#2-update-the-markdown-files) + - [Hugo frontmatter](#hugo-frontmatter) + - [3. Verify the changes before committing](#3-verify-the-changes-before-committing) + - [4. Changelog](#4-changelog) + - [When to add a Changelog Entry](#when-to-add-a-changelog-entry) - [Examples](#examples) - + [Adding a Changelog Entry](#adding-a-changelog-entry) - * [5. Getting your PR merged](#5-getting-your-pr-merged) + - [Adding a Changelog Entry](#adding-a-changelog-entry) + - [5. Getting your PR merged](#5-getting-your-pr-merged) - [Automation](#automation) - * [Consistency Checks](#consistency-checks) - * [Auto formatting](#auto-formatting) - * [Markdown style](#markdown-style) - * [Misspell check](#misspell-check) - * [Markdown link check](#markdown-link-check) + - [Consistency Checks](#consistency-checks) + - [Auto formatting](#auto-formatting) + - [Markdown style](#markdown-style) + - [Misspell check](#misspell-check) + - [Markdown link check](#markdown-link-check) - [Updating the referenced specification version](#updating-the-referenced-specification-version) - [Making a Release](#making-a-release) - [Merging existing ECS conventions](#merging-existing-ecs-conventions) @@ -320,7 +320,7 @@ make markdown-link-check - Add `next` as a version in `schema-next.yaml` version. - Run `make chlog-update VERSION=v{version}` - `make chlog-update` will clean up all the current `.yaml` files inside the - `.chloggen` folder automatically + `.chloggen` folder automatically - Double check that `CONTRIBUTING.md` is updated with the proper `v{version}` - Send staging tag as PR for review. - Create a tag `v{version}` on the merged PR and push remote. diff --git a/Makefile b/Makefile index b0a1e81e95..3ef76b3827 100644 --- a/Makefile +++ b/Makefile @@ -62,7 +62,7 @@ markdown-toc: @for f in $(ALL_DOCS); do \ if grep -q '' $$f; then \ echo markdown-toc: processing $$f; \ - npx --no -- markdown-toc --no-first-h1 --no-stripHeadingTags -i $$f || exit 1; \ + npx --no -- markdown-toc --bullets "-" --no-first-h1 --no-stripHeadingTags -i $$f || exit 1; \ else \ echo markdown-toc: no TOC markers, skipping $$f; \ fi; \ @@ -117,12 +117,13 @@ fix-format: # Run all checks in order of speed / likely failure. .PHONY: check -check: misspell markdownlint markdown-link-check check-format +check: misspell markdownlint check-format markdown-toc markdown-link-check + git diff --exit-code ':*.md' || (echo 'Generated markdown Table of Contents is out of date, please run "make markdown-toc" and commit the changes in this PR.' && exit 1) @echo "All checks complete" # Attempt to fix issues / regenerate tables. .PHONY: fix -fix: table-generation misspell-correction fix-format +fix: table-generation misspell-correction fix-format markdown-toc @echo "All autofixes complete" .PHONY: install-tools diff --git a/docs/cloudevents/cloudevents-spans.md b/docs/cloudevents/cloudevents-spans.md index 1236b745ad..44f112fe7a 100644 --- a/docs/cloudevents/cloudevents-spans.md +++ b/docs/cloudevents/cloudevents-spans.md @@ -13,10 +13,10 @@ linkTitle: CloudEvents Spans - [Definitions](#definitions) - [Overview](#overview) - [Conventions](#conventions) - * [Spans](#spans) - + [Creation](#creation) - + [Processing](#processing) - * [Attributes](#attributes) + - [Spans](#spans) + - [Creation](#creation) + - [Processing](#processing) + - [Attributes](#attributes) diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 1f21ddf074..402607fdfd 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -16,15 +16,15 @@ and attributes but more may be added in the future. - [Connection pools](#connection-pools) - * [Metric: `db.client.connections.usage`](#metric-dbclientconnectionsusage) - * [Metric: `db.client.connections.idle.max`](#metric-dbclientconnectionsidlemax) - * [Metric: `db.client.connections.idle.min`](#metric-dbclientconnectionsidlemin) - * [Metric: `db.client.connections.max`](#metric-dbclientconnectionsmax) - * [Metric: `db.client.connections.pending_requests`](#metric-dbclientconnectionspending_requests) - * [Metric: `db.client.connections.timeouts`](#metric-dbclientconnectionstimeouts) - * [Metric: `db.client.connections.create_time`](#metric-dbclientconnectionscreate_time) - * [Metric: `db.client.connections.wait_time`](#metric-dbclientconnectionswait_time) - * [Metric: `db.client.connections.use_time`](#metric-dbclientconnectionsuse_time) + - [Metric: `db.client.connections.usage`](#metric-dbclientconnectionsusage) + - [Metric: `db.client.connections.idle.max`](#metric-dbclientconnectionsidlemax) + - [Metric: `db.client.connections.idle.min`](#metric-dbclientconnectionsidlemin) + - [Metric: `db.client.connections.max`](#metric-dbclientconnectionsmax) + - [Metric: `db.client.connections.pending_requests`](#metric-dbclientconnectionspending_requests) + - [Metric: `db.client.connections.timeouts`](#metric-dbclientconnectionstimeouts) + - [Metric: `db.client.connections.create_time`](#metric-dbclientconnectionscreate_time) + - [Metric: `db.client.connections.wait_time`](#metric-dbclientconnectionswait_time) + - [Metric: `db.client.connections.use_time`](#metric-dbclientconnectionsuse_time) diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index e8e224fc74..5965c90a41 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -11,7 +11,7 @@ linkTitle: Client Calls - [Common attributes](#common-attributes) - * [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem) + - [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem) - [Semantic Conventions for specific database technologies](#semantic-conventions-for-specific-database-technologies) diff --git a/docs/dotnet/dotnet-aspnetcore-metrics.md b/docs/dotnet/dotnet-aspnetcore-metrics.md index e217a1664c..b09a34d8b8 100644 --- a/docs/dotnet/dotnet-aspnetcore-metrics.md +++ b/docs/dotnet/dotnet-aspnetcore-metrics.md @@ -12,15 +12,15 @@ This article defines semantic conventions for ASP.NET Core metrics. - [Server](#server) - [Routing](#routing) - * [Metric: `aspnetcore.routing.match_attempts`](#metric-aspnetcoreroutingmatch_attempts) + - [Metric: `aspnetcore.routing.match_attempts`](#metric-aspnetcoreroutingmatch_attempts) - [Exceptions](#exceptions) - * [Metric: `aspnetcore.diagnostics.exceptions`](#metric-aspnetcorediagnosticsexceptions) + - [Metric: `aspnetcore.diagnostics.exceptions`](#metric-aspnetcorediagnosticsexceptions) - [Rate-limiting](#rate-limiting) - * [Metric: `aspnetcore.rate_limiting.active_request_leases`](#metric-aspnetcorerate_limitingactive_request_leases) - * [Metric: `aspnetcore.rate_limiting.request_lease.duration`](#metric-aspnetcorerate_limitingrequest_leaseduration) - * [Metric: `aspnetcore.rate_limiting.queued_requests`](#metric-aspnetcorerate_limitingqueued_requests) - * [Metric: `aspnetcore.rate_limiting.request.time_in_queue`](#metric-aspnetcorerate_limitingrequesttime_in_queue) - * [Metric: `aspnetcore.rate_limiting.requests`](#metric-aspnetcorerate_limitingrequests) + - [Metric: `aspnetcore.rate_limiting.active_request_leases`](#metric-aspnetcorerate_limitingactive_request_leases) + - [Metric: `aspnetcore.rate_limiting.request_lease.duration`](#metric-aspnetcorerate_limitingrequest_leaseduration) + - [Metric: `aspnetcore.rate_limiting.queued_requests`](#metric-aspnetcorerate_limitingqueued_requests) + - [Metric: `aspnetcore.rate_limiting.request.time_in_queue`](#metric-aspnetcorerate_limitingrequesttime_in_queue) + - [Metric: `aspnetcore.rate_limiting.requests`](#metric-aspnetcorerate_limitingrequests) diff --git a/docs/dotnet/dotnet-dns-metrics.md b/docs/dotnet/dotnet-dns-metrics.md index c0bb6b7aa3..4240445dd1 100644 --- a/docs/dotnet/dotnet-dns-metrics.md +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -11,7 +11,7 @@ This article defines semantic conventions for DNS metrics emitted by .NET. - [DNS metrics](#dns-metrics) - * [Metric: `dns.lookup.duration`](#metric-dnslookupduration) + - [Metric: `dns.lookup.duration`](#metric-dnslookupduration) diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index ee7cb4d399..47bf1a71b7 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -11,14 +11,14 @@ This article defines semantic conventions for HTTP metrics emitted by .NET compo - [HTTP client](#http-client) - * [Metric: `http.client.request.duration`](#metric-httpclientrequestduration) - * [Metric: `http.client.open_connections`](#metric-httpclientopen_connections) - * [Metric: `http.client.connection.duration`](#metric-httpclientconnectionduration) - * [Metric: `http.client.request.time_in_queue`](#metric-httpclientrequesttime_in_queue) - * [Metric: `http.client.active_requests`](#metric-httpclientactive_requests) + - [Metric: `http.client.request.duration`](#metric-httpclientrequestduration) + - [Metric: `http.client.open_connections`](#metric-httpclientopen_connections) + - [Metric: `http.client.connection.duration`](#metric-httpclientconnectionduration) + - [Metric: `http.client.request.time_in_queue`](#metric-httpclientrequesttime_in_queue) + - [Metric: `http.client.active_requests`](#metric-httpclientactive_requests) - [HTTP server](#http-server) - * [Metric: `http.server.request.duration`](#metric-httpserverrequestduration) - * [Metric: `http.server.active_requests`](#metric-httpserveractive_requests) + - [Metric: `http.server.request.duration`](#metric-httpserverrequestduration) + - [Metric: `http.server.active_requests`](#metric-httpserveractive_requests) diff --git a/docs/exceptions/exceptions-logs.md b/docs/exceptions/exceptions-logs.md index 11656ea1df..0746762191 100644 --- a/docs/exceptions/exceptions-logs.md +++ b/docs/exceptions/exceptions-logs.md @@ -14,7 +14,7 @@ emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry - [Recording an Exception](#recording-an-exception) - [Attributes](#attributes) - * [Stacktrace Representation](#stacktrace-representation) + - [Stacktrace Representation](#stacktrace-representation) diff --git a/docs/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md index 18a91996a5..ef9d3849e1 100644 --- a/docs/exceptions/exceptions-spans.md +++ b/docs/exceptions/exceptions-spans.md @@ -13,7 +13,7 @@ exceptions associated with spans. - [Recording an Exception](#recording-an-exception) - [Attributes](#attributes) - * [Stacktrace Representation](#stacktrace-representation) + - [Stacktrace Representation](#stacktrace-representation) diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md index 45b68d67f3..c2219b9e4e 100644 --- a/docs/faas/aws-lambda.md +++ b/docs/faas/aws-lambda.md @@ -14,18 +14,18 @@ use cases. - [All triggers](#all-triggers) - * [AWS X-Ray Active Tracing Considerations](#aws-x-ray-active-tracing-considerations) - + [`xray-lambda` Propagator Functionality](#xray-lambda-propagator-functionality) - + [`xray-lambda` Propagator Configuration](#xray-lambda-propagator-configuration) + - [AWS X-Ray Active Tracing Considerations](#aws-x-ray-active-tracing-considerations) + - [`xray-lambda` Propagator Functionality](#xray-lambda-propagator-functionality) + - [`xray-lambda` Propagator Configuration](#xray-lambda-propagator-configuration) - [API Gateway](#api-gateway) - [SQS](#sqs) - * [SQS Event](#sqs-event) - * [SQS Message](#sqs-message) + - [SQS Event](#sqs-event) + - [SQS Message](#sqs-message) - [Examples](#examples) - * [API Gateway Request Proxy (Lambda tracing passive)](#api-gateway-request-proxy-lambda-tracing-passive) - * [API Gateway Request Proxy (Lambda tracing active)](#api-gateway-request-proxy-lambda-tracing-active) - * [SQS (Lambda tracing passive)](#sqs-lambda-tracing-passive) - * [SQS (Lambda tracing active)](#sqs-lambda-tracing-active) + - [API Gateway Request Proxy (Lambda tracing passive)](#api-gateway-request-proxy-lambda-tracing-passive) + - [API Gateway Request Proxy (Lambda tracing active)](#api-gateway-request-proxy-lambda-tracing-active) + - [SQS (Lambda tracing passive)](#sqs-lambda-tracing-passive) + - [SQS (Lambda tracing active)](#sqs-lambda-tracing-active) - [Resource Detector](#resource-detector) diff --git a/docs/faas/faas-metrics.md b/docs/faas/faas-metrics.md index e84a0921dc..d6046b04f9 100644 --- a/docs/faas/faas-metrics.md +++ b/docs/faas/faas-metrics.md @@ -18,18 +18,18 @@ operations. By adding FaaS attributes to metric events it allows for finely tune - [Metric Instruments](#metric-instruments) - * [FaaS Instance](#faas-instance) - + [Metric: `faas.invoke_duration`](#metric-faasinvoke_duration) - + [Metric: `faas.init_duration`](#metric-faasinit_duration) - + [Metric: `faas.coldstarts`](#metric-faascoldstarts) - + [Metric: `faas.errors`](#metric-faaserrors) - + [Metric: `faas.invocations`](#metric-faasinvocations) - + [Metric: `faas.timeouts`](#metric-faastimeouts) - + [Metric: `faas.mem_usage`](#metric-faasmem_usage) - + [Metric: `faas.cpu_usage`](#metric-faascpu_usage) - + [Metric: `faas.net_io`](#metric-faasnet_io) + - [FaaS Instance](#faas-instance) + - [Metric: `faas.invoke_duration`](#metric-faasinvoke_duration) + - [Metric: `faas.init_duration`](#metric-faasinit_duration) + - [Metric: `faas.coldstarts`](#metric-faascoldstarts) + - [Metric: `faas.errors`](#metric-faaserrors) + - [Metric: `faas.invocations`](#metric-faasinvocations) + - [Metric: `faas.timeouts`](#metric-faastimeouts) + - [Metric: `faas.mem_usage`](#metric-faasmem_usage) + - [Metric: `faas.cpu_usage`](#metric-faascpu_usage) + - [Metric: `faas.net_io`](#metric-faasnet_io) - [References](#references) - * [Metric References](#metric-references) + - [Metric References](#metric-references) diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md index 8088cf7c42..34a03528db 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -16,18 +16,18 @@ See also the [additional instructions for instrumenting AWS Lambda](aws-lambda.m - [General Attributes](#general-attributes) - * [Function Name](#function-name) - * [Difference between invocation and instance](#difference-between-invocation-and-instance) + - [Function Name](#function-name) + - [Difference between invocation and instance](#difference-between-invocation-and-instance) - [Incoming Invocations](#incoming-invocations) - * [Incoming FaaS Span attributes](#incoming-faas-span-attributes) - * [Resource attributes as incoming FaaS span attributes](#resource-attributes-as-incoming-faas-span-attributes) + - [Incoming FaaS Span attributes](#incoming-faas-span-attributes) + - [Resource attributes as incoming FaaS span attributes](#resource-attributes-as-incoming-faas-span-attributes) - [Outgoing Invocations](#outgoing-invocations) - [Function Trigger Type](#function-trigger-type) - * [Datasource](#datasource) - * [HTTP](#http) - * [PubSub](#pubsub) - * [Timer](#timer) - * [Other](#other) + - [Datasource](#datasource) + - [HTTP](#http) + - [PubSub](#pubsub) + - [Timer](#timer) + - [Other](#other) - [Example](#example) diff --git a/docs/general/attributes.md b/docs/general/attributes.md index e9f9dddad7..3ae6cbfdfd 100644 --- a/docs/general/attributes.md +++ b/docs/general/attributes.md @@ -16,20 +16,20 @@ Particular operations may refer to or require some of these attributes. - [Server, client and shared network attributes](#server-client-and-shared-network-attributes) - * [Address and port attributes](#address-and-port-attributes) - * [Server attributes](#server-attributes) - + [`server.address`](#serveraddress) - * [Client attributes](#client-attributes) - * [Source and destination attributes](#source-and-destination-attributes) - + [Source](#source) - + [Destination](#destination) - * [Other network attributes](#other-network-attributes) - + [`network.peer.*` and `network.local.*` attributes](#networkpeer-and-networklocal-attributes) + - [Address and port attributes](#address-and-port-attributes) + - [Server attributes](#server-attributes) + - [`server.address`](#serveraddress) + - [Client attributes](#client-attributes) + - [Source and destination attributes](#source-and-destination-attributes) + - [Source](#source) + - [Destination](#destination) + - [Other network attributes](#other-network-attributes) + - [`network.peer.*` and `network.local.*` attributes](#networkpeer-and-networklocal-attributes) - [Client/server examples using `network.peer.*`](#clientserver-examples-using--networkpeer) - * [Simple client/server example](#simple-clientserver-example) - * [Client/server example with reverse proxy](#clientserver-example-with-reverse-proxy) - * [Client/server example with forward proxy](#clientserver-example-with-forward-proxy) - + [Network connection and carrier attributes](#network-connection-and-carrier-attributes) + - [Simple client/server example](#simple-clientserver-example) + - [Client/server example with reverse proxy](#clientserver-example-with-reverse-proxy) + - [Client/server example with forward proxy](#clientserver-example-with-forward-proxy) + - [Network connection and carrier attributes](#network-connection-and-carrier-attributes) - [General remote service attributes](#general-remote-service-attributes) - [General identity attributes](#general-identity-attributes) - [General thread attributes](#general-thread-attributes) diff --git a/docs/general/logs.md b/docs/general/logs.md index c66136624d..152950057a 100644 --- a/docs/general/logs.md +++ b/docs/general/logs.md @@ -16,8 +16,8 @@ They may be used in any Log Record they apply to. - [General log identification attributes](#general-log-identification-attributes) - [Log Media](#log-media) - * [Log File](#log-file) - * [I/O Stream](#io-stream) + - [Log File](#log-file) + - [I/O Stream](#io-stream) diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 74699fbad0..2f235e23ce 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -10,17 +10,17 @@ aliases: [docs/specs/semconv/general/metrics-general] - [General Guidelines](#general-guidelines) - * [Name Reuse Prohibition](#name-reuse-prohibition) - * [Units](#units) - * [Naming rules for Counters and UpDownCounters](#naming-rules-for-counters-and-updowncounters) - + [Pluralization](#pluralization) - + [Use `count` Instead of Pluralization for UpDownCounters](#use-count-instead-of-pluralization-for-updowncounters) - + [Do not use `total`](#do-not-use-total) + - [Name Reuse Prohibition](#name-reuse-prohibition) + - [Units](#units) + - [Naming rules for Counters and UpDownCounters](#naming-rules-for-counters-and-updowncounters) + - [Pluralization](#pluralization) + - [Use `count` Instead of Pluralization for UpDownCounters](#use-count-instead-of-pluralization-for-updowncounters) + - [Do not use `total`](#do-not-use-total) - [General Metric Semantic Conventions](#general-metric-semantic-conventions) - * [Instrument Naming](#instrument-naming) - * [Instrument Units](#instrument-units) - * [Instrument Types](#instrument-types) - * [Consistent UpDownCounter timeseries](#consistent-updowncounter-timeseries) + - [Instrument Naming](#instrument-naming) + - [Instrument Units](#instrument-units) + - [Instrument Types](#instrument-types) + - [Consistent UpDownCounter timeseries](#consistent-updowncounter-timeseries) diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index eae37608ed..aed8fc81dc 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -15,14 +15,14 @@ operations. By adding HTTP attributes to metric events it allows for finely tune - [HTTP Server](#http-server) - * [Metric: `http.server.request.duration`](#metric-httpserverrequestduration) - * [Metric: `http.server.active_requests`](#metric-httpserveractive_requests) - * [Metric: `http.server.request.body.size`](#metric-httpserverrequestbodysize) - * [Metric: `http.server.response.body.size`](#metric-httpserverresponsebodysize) + - [Metric: `http.server.request.duration`](#metric-httpserverrequestduration) + - [Metric: `http.server.active_requests`](#metric-httpserveractive_requests) + - [Metric: `http.server.request.body.size`](#metric-httpserverrequestbodysize) + - [Metric: `http.server.response.body.size`](#metric-httpserverresponsebodysize) - [HTTP Client](#http-client) - * [Metric: `http.client.request.duration`](#metric-httpclientrequestduration) - * [Metric: `http.client.request.body.size`](#metric-httpclientrequestbodysize) - * [Metric: `http.client.response.body.size`](#metric-httpclientresponsebodysize) + - [Metric: `http.client.request.duration`](#metric-httpclientrequestduration) + - [Metric: `http.client.request.body.size`](#metric-httpclientrequestbodysize) + - [Metric: `http.client.response.body.size`](#metric-httpclientresponsebodysize) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 4b5edb5b99..1668199fa2 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -18,22 +18,22 @@ and various HTTP versions like 1.1, 2 and SPDY. - [Status](#status) - [Common Attributes](#common-attributes) - [HTTP client](#http-client) - * [HTTP client span duration](#http-client-span-duration) - * [HTTP request retries and redirects](#http-request-retries-and-redirects) + - [HTTP client span duration](#http-client-span-duration) + - [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) + - [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) - * [HTTP client retries examples](#http-client-retries-examples) - * [HTTP client authorization retry examples](#http-client-authorization-retry-examples) - * [HTTP client redirects examples](#http-client-redirects-examples) - * [HTTP client call: DNS error](#http-client-call-dns-error) - * [HTTP client call: Internal Server Error](#http-client-call-internal-server-error) - * [HTTP server call: connection dropped before response body was sent](#http-server-call-connection-dropped-before-response-body-was-sent) + - [HTTP client-server example](#http-client-server-example) + - [HTTP client retries examples](#http-client-retries-examples) + - [HTTP client authorization retry examples](#http-client-authorization-retry-examples) + - [HTTP client redirects examples](#http-client-redirects-examples) + - [HTTP client call: DNS error](#http-client-call-dns-error) + - [HTTP client call: Internal Server Error](#http-client-call-internal-server-error) + - [HTTP server call: connection dropped before response body was sent](#http-server-call-connection-dropped-before-response-body-was-sent) diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index ffb30d89c2..47deec0d23 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -10,7 +10,7 @@ linkTitle: Kafka - [Span attributes](#span-attributes) - [Examples](#examples) - * [Apache Kafka with Quarkus or Spring Boot Example](#apache-kafka-with-quarkus-or-spring-boot-example) + - [Apache Kafka with Quarkus or Spring Boot Example](#apache-kafka-with-quarkus-or-spring-boot-example) diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md index d715d1100d..f650cfd9bf 100644 --- a/docs/messaging/messaging-metrics.md +++ b/docs/messaging/messaging-metrics.md @@ -8,13 +8,13 @@ - [Common attributes](#common-attributes) - [Producer metrics](#producer-metrics) - * [Metric: `messaging.publish.duration`](#metric-messagingpublishduration) - * [Metric: `messaging.publish.messages`](#metric-messagingpublishmessages) + - [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.process.duration`](#metric-messagingprocessduration) - * [Metric: `messaging.process.messages`](#metric-messagingprocessmessages) + - [Metric: `messaging.receive.duration`](#metric-messagingreceiveduration) + - [Metric: `messaging.receive.messages`](#metric-messagingreceivemessages) + - [Metric: `messaging.process.duration`](#metric-messagingprocessduration) + - [Metric: `messaging.process.messages`](#metric-messagingprocessmessages) diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index b93932c8b6..7cff828c2c 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -7,30 +7,30 @@ - [Definitions](#definitions) - * [Message](#message) - * [Producer](#producer) - * [Consumer](#consumer) - * [Intermediary](#intermediary) - * [Destinations](#destinations) - * [Message consumption](#message-consumption) - * [Conversations](#conversations) - * [Temporary and anonymous destinations](#temporary-and-anonymous-destinations) + - [Message](#message) + - [Producer](#producer) + - [Consumer](#consumer) + - [Intermediary](#intermediary) + - [Destinations](#destinations) + - [Message consumption](#message-consumption) + - [Conversations](#conversations) + - [Temporary and anonymous destinations](#temporary-and-anonymous-destinations) - [Conventions](#conventions) - * [Context propagation](#context-propagation) - * [Span name](#span-name) - * [Operation names](#operation-names) - * [Span kind](#span-kind) - * [Trace structure](#trace-structure) - + [Producer spans](#producer-spans) - + [Consumer spans](#consumer-spans) + - [Context propagation](#context-propagation) + - [Span name](#span-name) + - [Operation names](#operation-names) + - [Span kind](#span-kind) + - [Trace structure](#trace-structure) + - [Producer spans](#producer-spans) + - [Consumer spans](#consumer-spans) - [Messaging attributes](#messaging-attributes) - * [Consumer attributes](#consumer-attributes) - * [Per-message attributes](#per-message-attributes) - * [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems) + - [Consumer attributes](#consumer-attributes) + - [Per-message attributes](#per-message-attributes) + - [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems) - [Examples](#examples) - * [Topic with multiple consumers](#topic-with-multiple-consumers) - * [Batch receiving](#batch-receiving) - * [Batch publishing](#batch-publishing) + - [Topic with multiple consumers](#topic-with-multiple-consumers) + - [Batch receiving](#batch-receiving) + - [Batch publishing](#batch-publishing) - [Semantic Conventions for specific messaging technologies](#semantic-conventions-for-specific-messaging-technologies) diff --git a/docs/mobile/events.md b/docs/mobile/events.md index 70a5d6fdc3..e626f2c9c3 100644 --- a/docs/mobile/events.md +++ b/docs/mobile/events.md @@ -9,8 +9,8 @@ events on mobile platforms. All mobile events MUST use a namespace of - [Lifecycle instrumentation](#lifecycle-instrumentation) - * [iOS](#ios) - * [Android](#android) + - [iOS](#ios) + - [Android](#android) diff --git a/docs/resource/README.md b/docs/resource/README.md index 5dd529d264..5c62168b6c 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -19,8 +19,8 @@ This document defines standard attributes for resources. These attributes are ty - [TODOs](#todos) - [Document Conventions](#document-conventions) - [Attributes with Special Handling](#attributes-with-special-handling) - * [Semantic Attributes with Dedicated Environment Variable](#semantic-attributes-with-dedicated-environment-variable) - * [Semantic Attributes with SDK-provided Default Value](#semantic-attributes-with-sdk-provided-default-value) + - [Semantic Attributes with Dedicated Environment Variable](#semantic-attributes-with-dedicated-environment-variable) + - [Semantic Attributes with SDK-provided Default Value](#semantic-attributes-with-sdk-provided-default-value) - [Service](#service) - [Service (Experimental)](#service-experimental) - [Telemetry SDK](#telemetry-sdk) diff --git a/docs/resource/process.md b/docs/resource/process.md index 8156fbcd2a..36403a2de4 100644 --- a/docs/resource/process.md +++ b/docs/resource/process.md @@ -8,13 +8,13 @@ - [Process](#process) - [Process runtimes](#process-runtimes) - * [Erlang Runtimes](#erlang-runtimes) - * [Go Runtimes](#go-runtimes) - * [Java runtimes](#java-runtimes) - * [JavaScript runtimes](#javascript-runtimes) - * [.NET Runtimes](#net-runtimes) - * [Python Runtimes](#python-runtimes) - * [Ruby Runtimes](#ruby-runtimes) + - [Erlang Runtimes](#erlang-runtimes) + - [Go Runtimes](#go-runtimes) + - [Java runtimes](#java-runtimes) + - [JavaScript runtimes](#javascript-runtimes) + - [.NET Runtimes](#net-runtimes) + - [Python Runtimes](#python-runtimes) + - [Ruby Runtimes](#ruby-runtimes) diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index 106e2e6c4a..693653d92e 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -17,20 +17,20 @@ metrics can be filtered for finer grain analysis. - [Metric instruments](#metric-instruments) - * [RPC Server](#rpc-server) - + [Metric: `rpc.server.duration`](#metric-rpcserverduration) - + [Metric: `rpc.server.request.size`](#metric-rpcserverrequestsize) - + [Metric: `rpc.server.response.size`](#metric-rpcserverresponsesize) - + [Metric: `rpc.server.requests_per_rpc`](#metric-rpcserverrequests_per_rpc) - + [Metric: `rpc.server.responses_per_rpc`](#metric-rpcserverresponses_per_rpc) - * [RPC Client](#rpc-client) - + [Metric: `rpc.client.duration`](#metric-rpcclientduration) - + [Metric: `rpc.client.request.size`](#metric-rpcclientrequestsize) - + [Metric: `rpc.client.response.size`](#metric-rpcclientresponsesize) - + [Metric: `rpc.client.requests_per_rpc`](#metric-rpcclientrequests_per_rpc) - + [Metric: `rpc.client.responses_per_rpc`](#metric-rpcclientresponses_per_rpc) + - [RPC Server](#rpc-server) + - [Metric: `rpc.server.duration`](#metric-rpcserverduration) + - [Metric: `rpc.server.request.size`](#metric-rpcserverrequestsize) + - [Metric: `rpc.server.response.size`](#metric-rpcserverresponsesize) + - [Metric: `rpc.server.requests_per_rpc`](#metric-rpcserverrequests_per_rpc) + - [Metric: `rpc.server.responses_per_rpc`](#metric-rpcserverresponses_per_rpc) + - [RPC Client](#rpc-client) + - [Metric: `rpc.client.duration`](#metric-rpcclientduration) + - [Metric: `rpc.client.request.size`](#metric-rpcclientrequestsize) + - [Metric: `rpc.client.response.size`](#metric-rpcclientresponsesize) + - [Metric: `rpc.client.requests_per_rpc`](#metric-rpcclientrequests_per_rpc) + - [Metric: `rpc.client.responses_per_rpc`](#metric-rpcclientresponses_per_rpc) - [Attributes](#attributes) - * [Service name](#service-name) + - [Service name](#service-name) - [Semantic Conventions for specific RPC technologies](#semantic-conventions-for-specific-rpc-technologies) diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index c3a9554350..0fc18c483d 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -14,13 +14,13 @@ This document defines how to describe remote procedure calls - [Common remote procedure call conventions](#common-remote-procedure-call-conventions) - * [Span name](#span-name) - * [Common attributes](#common-attributes) - + [Service name](#service-name) - * [Client attributes](#client-attributes) - * [Server attributes](#server-attributes) - * [Events](#events) - * [Distinction from HTTP spans](#distinction-from-http-spans) + - [Span name](#span-name) + - [Common attributes](#common-attributes) + - [Service name](#service-name) + - [Client attributes](#client-attributes) + - [Server attributes](#server-attributes) + - [Events](#events) + - [Distinction from HTTP spans](#distinction-from-http-spans) - [Semantic Conventions for specific RPC technologies](#semantic-conventions-for-specific-rpc-technologies) diff --git a/docs/runtime/README.md b/docs/runtime/README.md index 24d221e3b6..8b8b2ebb1b 100644 --- a/docs/runtime/README.md +++ b/docs/runtime/README.md @@ -14,7 +14,7 @@ runtime environment spans, metrics and logs. - [Metrics](#metrics) - * [Attributes](#attributes) + - [Attributes](#attributes) diff --git a/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md index 780c15afd3..3d27e0a24a 100644 --- a/docs/runtime/jvm-metrics.md +++ b/docs/runtime/jvm-metrics.md @@ -13,29 +13,29 @@ This document describes semantic conventions for JVM metrics in OpenTelemetry. - [JVM Memory](#jvm-memory) - * [Metric: `jvm.memory.used`](#metric-jvmmemoryused) - * [Metric: `jvm.memory.committed`](#metric-jvmmemorycommitted) - * [Metric: `jvm.memory.limit`](#metric-jvmmemorylimit) - * [Metric: `jvm.memory.used_after_last_gc`](#metric-jvmmemoryused_after_last_gc) + - [Metric: `jvm.memory.used`](#metric-jvmmemoryused) + - [Metric: `jvm.memory.committed`](#metric-jvmmemorycommitted) + - [Metric: `jvm.memory.limit`](#metric-jvmmemorylimit) + - [Metric: `jvm.memory.used_after_last_gc`](#metric-jvmmemoryused_after_last_gc) - [JVM Garbage Collection](#jvm-garbage-collection) - * [Metric: `jvm.gc.duration`](#metric-jvmgcduration) + - [Metric: `jvm.gc.duration`](#metric-jvmgcduration) - [JVM Threads](#jvm-threads) - * [Metric: `jvm.thread.count`](#metric-jvmthreadcount) + - [Metric: `jvm.thread.count`](#metric-jvmthreadcount) - [JVM Classes](#jvm-classes) - * [Metric: `jvm.class.loaded`](#metric-jvmclassloaded) - * [Metric: `jvm.class.unloaded`](#metric-jvmclassunloaded) - * [Metric: `jvm.class.count`](#metric-jvmclasscount) + - [Metric: `jvm.class.loaded`](#metric-jvmclassloaded) + - [Metric: `jvm.class.unloaded`](#metric-jvmclassunloaded) + - [Metric: `jvm.class.count`](#metric-jvmclasscount) - [JVM CPU](#jvm-cpu) - * [Metric: `jvm.cpu.time`](#metric-jvmcputime) - * [Metric: `jvm.cpu.count`](#metric-jvmcpucount) - * [Metric: `jvm.cpu.recent_utilization`](#metric-jvmcpurecent_utilization) + - [Metric: `jvm.cpu.time`](#metric-jvmcputime) + - [Metric: `jvm.cpu.count`](#metric-jvmcpucount) + - [Metric: `jvm.cpu.recent_utilization`](#metric-jvmcpurecent_utilization) - [Experimental](#experimental) - * [Metric: `jvm.memory.init`](#metric-jvmmemoryinit) - * [Metric: `jvm.system.cpu.utilization`](#metric-jvmsystemcpuutilization) - * [Metric: `jvm.system.cpu.load_1m`](#metric-jvmsystemcpuload_1m) - * [Metric: `jvm.buffer.memory.usage`](#metric-jvmbuffermemoryusage) - * [Metric: `jvm.buffer.memory.limit`](#metric-jvmbuffermemorylimit) - * [Metric: `jvm.buffer.count`](#metric-jvmbuffercount) + - [Metric: `jvm.memory.init`](#metric-jvmmemoryinit) + - [Metric: `jvm.system.cpu.utilization`](#metric-jvmsystemcpuutilization) + - [Metric: `jvm.system.cpu.load_1m`](#metric-jvmsystemcpuload_1m) + - [Metric: `jvm.buffer.memory.usage`](#metric-jvmbuffermemoryusage) + - [Metric: `jvm.buffer.memory.limit`](#metric-jvmbuffermemorylimit) + - [Metric: `jvm.buffer.count`](#metric-jvmbuffercount) diff --git a/docs/system/hardware-metrics.md b/docs/system/hardware-metrics.md index a5c9f8ac01..f109d5f240 100644 --- a/docs/system/hardware-metrics.md +++ b/docs/system/hardware-metrics.md @@ -14,22 +14,22 @@ when creating instruments not explicitly defined in the specification. - [Common hardware attributes](#common-hardware-attributes) - [Metric Instruments](#metric-instruments) - * [`hw.` - Common hardware metrics](#hw---common-hardware-metrics) - * [`hw.host.` - Physical host metrics](#hwhost---physical-host-metrics) - * [`hw.battery.` - Battery metrics](#hwbattery---battery-metrics) - * [`hw.cpu.` - Physical processor metrics](#hwcpu---physical-processor-metrics) - * [`hw.disk_controller.` - Disk controller metrics](#hwdisk_controller---disk-controller-metrics) - * [`hw.enclosure.` - Enclosure metrics](#hwenclosure---enclosure-metrics) - * [`hw.fan.` - Fan metrics](#hwfan---fan-metrics) - * [`hw.gpu.` - GPU metrics](#hwgpu---gpu-metrics) - * [`hw.logical_disk.`- Logical disk metrics](#hwlogical_disk--logical-disk-metrics) - * [`hw.memory.` - Memory module metrics](#hwmemory---memory-module-metrics) - * [`hw.network.` - Network adapter metrics](#hwnetwork---network-adapter-metrics) - * [`hw.physical_disk.`- Physical disk metrics](#hwphysical_disk--physical-disk-metrics) - * [`hw.power_supply.` - Power supply metrics](#hwpower_supply---power-supply-metrics) - * [`hw.tape_drive.` - Tape drive metrics](#hwtape_drive---tape-drive-metrics) - * [`hw.temperature.` - Temperature sensor metrics](#hwtemperature---temperature-sensor-metrics) - * [`hw.voltage.` - Voltage sensor metrics](#hwvoltage---voltage-sensor-metrics) + - [`hw.` - Common hardware metrics](#hw---common-hardware-metrics) + - [`hw.host.` - Physical host metrics](#hwhost---physical-host-metrics) + - [`hw.battery.` - Battery metrics](#hwbattery---battery-metrics) + - [`hw.cpu.` - Physical processor metrics](#hwcpu---physical-processor-metrics) + - [`hw.disk_controller.` - Disk controller metrics](#hwdisk_controller---disk-controller-metrics) + - [`hw.enclosure.` - Enclosure metrics](#hwenclosure---enclosure-metrics) + - [`hw.fan.` - Fan metrics](#hwfan---fan-metrics) + - [`hw.gpu.` - GPU metrics](#hwgpu---gpu-metrics) + - [`hw.logical_disk.`- Logical disk metrics](#hwlogical_disk--logical-disk-metrics) + - [`hw.memory.` - Memory module metrics](#hwmemory---memory-module-metrics) + - [`hw.network.` - Network adapter metrics](#hwnetwork---network-adapter-metrics) + - [`hw.physical_disk.`- Physical disk metrics](#hwphysical_disk--physical-disk-metrics) + - [`hw.power_supply.` - Power supply metrics](#hwpower_supply---power-supply-metrics) + - [`hw.tape_drive.` - Tape drive metrics](#hwtape_drive---tape-drive-metrics) + - [`hw.temperature.` - Temperature sensor metrics](#hwtemperature---temperature-sensor-metrics) + - [`hw.voltage.` - Voltage sensor metrics](#hwvoltage---voltage-sensor-metrics) diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index 35e343349e..31b1367200 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -20,16 +20,16 @@ metrics](/docs/runtime/README.md#metrics). - [Process Metrics](#process-metrics) - * [Metric: `process.cpu.time`](#metric-processcputime) - * [Metric: `process.cpu.utilization`](#metric-processcpuutilization) - * [Metric: `process.memory.usage`](#metric-processmemoryusage) - * [Metric: `process.memory.virtual`](#metric-processmemoryvirtual) - * [Metric: `process.disk.io`](#metric-processdiskio) - * [Metric: `process.network.io`](#metric-processnetworkio) - * [Metric: `process.thread.count`](#metric-processthreadcount) - * [Metric: `process.open_file_descriptor.count`](#metric-processopen_file_descriptorcount) - * [Metric: `process.context_switches`](#metric-processcontext_switches) - * [Metric: `process.paging.faults`](#metric-processpagingfaults) + - [Metric: `process.cpu.time`](#metric-processcputime) + - [Metric: `process.cpu.utilization`](#metric-processcpuutilization) + - [Metric: `process.memory.usage`](#metric-processmemoryusage) + - [Metric: `process.memory.virtual`](#metric-processmemoryvirtual) + - [Metric: `process.disk.io`](#metric-processdiskio) + - [Metric: `process.network.io`](#metric-processnetworkio) + - [Metric: `process.thread.count`](#metric-processthreadcount) + - [Metric: `process.open_file_descriptor.count`](#metric-processopen_file_descriptorcount) + - [Metric: `process.context_switches`](#metric-processcontext_switches) + - [Metric: `process.paging.faults`](#metric-processpagingfaults) diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 4f682cc030..38be351b98 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -22,40 +22,40 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam - [Processor Metrics](#processor-metrics) - * [Metric: `system.cpu.time`](#metric-systemcputime) - * [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) + - [Metric: `system.cpu.time`](#metric-systemcputime) + - [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) + - [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) - * [Metric: `system.paging.utilization`](#metric-systempagingutilization) - * [Metric: `system.paging.faults`](#metric-systempagingfaults) - * [Metric: `system.paging.operations`](#metric-systempagingoperations) + - [Metric: `system.paging.usage`](#metric-systempagingusage) + - [Metric: `system.paging.utilization`](#metric-systempagingutilization) + - [Metric: `system.paging.faults`](#metric-systempagingfaults) + - [Metric: `system.paging.operations`](#metric-systempagingoperations) - [Disk Controller Metrics](#disk-controller-metrics) - * [Metric: `system.disk.io`](#metric-systemdiskio) - * [Metric: `system.disk.operations`](#metric-systemdiskoperations) - * [Metric: `system.disk.io_time`](#metric-systemdiskio_time) - * [Metric: `system.disk.operation_time`](#metric-systemdiskoperation_time) - * [Metric: `system.disk.merged`](#metric-systemdiskmerged) + - [Metric: `system.disk.io`](#metric-systemdiskio) + - [Metric: `system.disk.operations`](#metric-systemdiskoperations) + - [Metric: `system.disk.io_time`](#metric-systemdiskio_time) + - [Metric: `system.disk.operation_time`](#metric-systemdiskoperation_time) + - [Metric: `system.disk.merged`](#metric-systemdiskmerged) - [Filesystem Metrics](#filesystem-metrics) - * [Metric: `system.filesystem.usage`](#metric-systemfilesystemusage) - * [Metric: `system.filesystem.utilization`](#metric-systemfilesystemutilization) + - [Metric: `system.filesystem.usage`](#metric-systemfilesystemusage) + - [Metric: `system.filesystem.utilization`](#metric-systemfilesystemutilization) - [Network Metrics](#network-metrics) - * [Metric: `system.network.dropped`](#metric-systemnetworkdropped) - * [Metric: `system.network.packets`](#metric-systemnetworkpackets) - * [Metric: `system.network.errors`](#metric-systemnetworkerrors) - * [Metric: `system.network.io`](#metric-systemnetworkio) - * [Metric: `system.network.connections`](#metric-systemnetworkconnections) + - [Metric: `system.network.dropped`](#metric-systemnetworkdropped) + - [Metric: `system.network.packets`](#metric-systemnetworkpackets) + - [Metric: `system.network.errors`](#metric-systemnetworkerrors) + - [Metric: `system.network.io`](#metric-systemnetworkio) + - [Metric: `system.network.connections`](#metric-systemnetworkconnections) - [Aggregate System Process Metrics](#aggregate-system-process-metrics) - * [Metric: `system.process.count`](#metric-systemprocesscount) - * [Metric: `system.process.created`](#metric-systemprocesscreated) + - [Metric: `system.process.count`](#metric-systemprocesscount) + - [Metric: `system.process.created`](#metric-systemprocesscreated) - [`system.{os}.` - OS Specific System Metrics](#systemos---os-specific-system-metrics) - * [Metric: `system.linux.memory.available`](#metric-systemlinuxmemoryavailable) + - [Metric: `system.linux.memory.available`](#metric-systemlinuxmemoryavailable) From 153b768fa620e3d69dd179bc0bec63d558213dc7 Mon Sep 17 00:00:00 2001 From: Miguel Luna <39376769+mlunadia@users.noreply.github.com> Date: Wed, 6 Mar 2024 11:07:21 +0000 Subject: [PATCH 17/22] moving android to the registry attributes (#544) Signed-off-by: Miguel Luna <39376769+mlunadia@users.noreply.github.com> Co-authored-by: jason plumb <75337021+breedx-splk@users.noreply.github.com> Co-authored-by: Chris Mark Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- docs/attributes-registry/README.md | 1 + docs/attributes-registry/android.md | 8 ++++++++ docs/resource/android.md | 2 +- model/registry/android.yaml | 15 +++++++++++++++ model/resource/android.yaml | 9 +-------- 5 files changed, 26 insertions(+), 9 deletions(-) create mode 100644 docs/attributes-registry/android.md create mode 100644 model/registry/android.yaml diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index ada3b9534f..113725054e 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -27,6 +27,7 @@ All registered attributes are listed by namespace in this registry. Currently, the following namespaces exist: +* [Android](android.md) * [Browser](browser.md) * [Client](client.md) * [Cloud](cloud.md) diff --git a/docs/attributes-registry/android.md b/docs/attributes-registry/android.md new file mode 100644 index 0000000000..e8539f2b73 --- /dev/null +++ b/docs/attributes-registry/android.md @@ -0,0 +1,8 @@ +# Android + +## Android Attributes + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `android.os.api_level` | string | Uniquely identifies the framework API revision offered by a version (`os.version`) of the android operating system. More information can be found [here](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels). | `33`; `32` | + diff --git a/docs/resource/android.md b/docs/resource/android.md index 39daee5a8f..aa635d29ef 100644 --- a/docs/resource/android.md +++ b/docs/resource/android.md @@ -9,7 +9,7 @@ | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `android.os.api_level` | string | Uniquely identifies the framework API revision offered by a version (`os.version`) of the android operating system. More information can be found [here](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels). | `33`; `32` | Recommended | +| [`android.os.api_level`](../attributes-registry/android.md) | string | Uniquely identifies the framework API revision offered by a version (`os.version`) of the android operating system. More information can be found [here](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels). | `33`; `32` | Recommended | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/model/registry/android.yaml b/model/registry/android.yaml new file mode 100644 index 0000000000..cfdcac8a46 --- /dev/null +++ b/model/registry/android.yaml @@ -0,0 +1,15 @@ +groups: + - id: registry.android + prefix: android + type: attribute_group + brief: > + The Android platform on which the Android application is running. + attributes: + - id: os.api_level + type: string + stability: experimental + brief: > + Uniquely identifies the framework API revision offered by a version + (`os.version`) of the android operating system. More information can be found + [here](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels). + examples: ['33', '32'] diff --git a/model/resource/android.yaml b/model/resource/android.yaml index cf4040f514..0f2b756eb9 100644 --- a/model/resource/android.yaml +++ b/model/resource/android.yaml @@ -5,11 +5,4 @@ groups: brief: > The Android platform on which the Android application is running. attributes: - - id: os.api_level - type: string - stability: experimental - brief: > - Uniquely identifies the framework API revision offered by a version - (`os.version`) of the android operating system. More information can be found - [here](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels). - examples: ['33', '32'] + - ref: android.os.api_level From 6c79a1d9107c1833d95177beda84947ce1902792 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 6 Mar 2024 11:46:13 -0800 Subject: [PATCH 18/22] Deprecate db.connection_string (#769) --- .chloggen/769.yaml | 4 ++++ docs/attributes-registry/db.md | 10 +++++++++- docs/database/database-metrics.md | 18 +++++++++--------- docs/database/database-spans.md | 1 - docs/database/mongodb.md | 1 - docs/database/redis.md | 1 - docs/database/sql.md | 1 - model/metrics/database-metrics.yaml | 4 ++-- model/registry/db.yaml | 8 -------- model/registry/deprecated/db.yaml | 13 +++++++++++++ model/trace/database.yaml | 2 -- 11 files changed, 37 insertions(+), 26 deletions(-) create mode 100644 .chloggen/769.yaml create mode 100644 model/registry/deprecated/db.yaml diff --git a/.chloggen/769.yaml b/.chloggen/769.yaml new file mode 100644 index 0000000000..8789e89f94 --- /dev/null +++ b/.chloggen/769.yaml @@ -0,0 +1,4 @@ +change_type: deprecation +component: db +note: Deprecate `db.connection_string` attribute in favor of `server.address` and `server.port` +issues: [724, 769] diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index c178bbe971..5441b91de9 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -14,6 +14,7 @@ - [MSSQL Attributes](#mssql-attributes) - [Redis Attributes](#redis-attributes) - [SQL Attributes](#sql-attributes) +- [Deprecated DB Attributes](#deprecated-db-attributes) @@ -22,7 +23,6 @@ | 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` | @@ -221,3 +221,11 @@ **[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. + +## Deprecated DB Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `db.connection_string` | string | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, use `server.address`, `server.port` attributes instead. | `Server=(localdb)\v11.0;Integrated Security=true;` | + \ No newline at end of file diff --git a/docs/database/database-metrics.md b/docs/database/database-metrics.md index 402607fdfd..cd476652e0 100644 --- a/docs/database/database-metrics.md +++ b/docs/database/database-metrics.md @@ -52,7 +52,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 doesn't provide a name, then the [db.connection_string](/docs/database/database-spans.md#common-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, instrumentation should use a combination of `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | Required | | `state` | string | The state of a connection in the pool | `idle` | Required | `state` MUST be one of the following: @@ -75,7 +75,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 doesn't provide a name, then the [db.connection_string](/docs/database/database-spans.md#common-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, instrumentation should use a combination of `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | Required | ### Metric: `db.client.connections.idle.min` @@ -91,7 +91,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 doesn't provide a name, then the [db.connection_string](/docs/database/database-spans.md#common-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, instrumentation should use a combination of `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | Required | ### Metric: `db.client.connections.max` @@ -107,7 +107,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 doesn't provide a name, then the [db.connection_string](/docs/database/database-spans.md#common-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, instrumentation should use a combination of `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | Required | ### Metric: `db.client.connections.pending_requests` @@ -123,7 +123,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 doesn't provide a name, then the [db.connection_string](/docs/database/database-spans.md#common-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, instrumentation should use a combination of `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | Required | ### Metric: `db.client.connections.timeouts` @@ -139,7 +139,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 doesn't provide a name, then the [db.connection_string](/docs/database/database-spans.md#common-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, instrumentation should use a combination of `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | Required | ### Metric: `db.client.connections.create_time` @@ -155,7 +155,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 doesn't provide a name, then the [db.connection_string](/docs/database/database-spans.md#common-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, instrumentation should use a combination of `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | Required | ### Metric: `db.client.connections.wait_time` @@ -171,7 +171,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 doesn't provide a name, then the [db.connection_string](/docs/database/database-spans.md#common-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, instrumentation should use a combination of `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `myDataSource` | Required | ### Metric: `db.client.connections.use_time` @@ -187,7 +187,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 doesn't provide a name, then the [db.connection_string](/docs/database/database-spans.md#common-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, instrumentation should use a combination of `server.address` and `server.port` attributes formatted as `server.address:server.port`. | `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 5965c90a41..6324709e0c 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -73,7 +73,6 @@ Some database systems may allow a connection to switch to a different `db.user`, | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`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.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. | diff --git a/docs/database/mongodb.md b/docs/database/mongodb.md index ebb2a5a883..71558732c8 100644 --- a/docs/database/mongodb.md +++ b/docs/database/mongodb.md @@ -26,7 +26,6 @@ described on this page. | :---------------------- | :----------------------------------------------------------- | | Span name | `"products.findAndModify"` | | `db.system` | `"mongodb"` | -| `db.connection_string` | not set | | `db.user` | `"the_user"` | | `server.address` | `"mongodb0.example.com"` | | `server.port` | `27017` | diff --git a/docs/database/redis.md b/docs/database/redis.md index 62637688e3..838d50822e 100644 --- a/docs/database/redis.md +++ b/docs/database/redis.md @@ -34,7 +34,6 @@ Furthermore, `db.name` is not specified as there is no database name in Redis an |:--------------------------| :-------------------------------------------- | | Span name | `"HMSET myhash"` | | `db.system` | `"redis"` | -| `db.connection_string` | not set | | `db.user` | not set | | `network.peer.address` | `"/tmp/redis.sock"` | | `network.transport` | `"unix"` | diff --git a/docs/database/sql.md b/docs/database/sql.md index 5eaddacf39..d60e3e158e 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -29,7 +29,6 @@ This is an example of attributes for a MySQL database span: |:------------------------| :----------------------------------------------------------- | | Span name | `"SELECT ShopDb.orders"` | | `db.system` | `"mysql"` | -| `db.connection_string` | `"Server=shopdb.example.com;Database=ShopDb;Uid=billing_user;TableCache=true;UseCompression=True;MinimumPoolSize=10;MaximumPoolSize=50;"` | | `db.user` | `"billing_user"` | | `server.address` | `"shopdb.example.com"` | | `server.port` | `3306` | diff --git a/model/metrics/database-metrics.yaml b/model/metrics/database-metrics.yaml index 0691e6c625..bfcc7020ec 100644 --- a/model/metrics/database-metrics.yaml +++ b/model/metrics/database-metrics.yaml @@ -22,8 +22,8 @@ groups: brief: > 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#common-attributes) - should be used + instrumentation should use a combination of `server.address` and `server.port` attributes + formatted as `server.address:server.port`. examples: ["myDataSource"] - id: metric.db.client.connections.usage diff --git a/model/registry/db.yaml b/model/registry/db.yaml index 6926fa53b6..a94eef9471 100644 --- a/model/registry/db.yaml +++ b/model/registry/db.yaml @@ -81,14 +81,6 @@ groups: value MUST NOT be set. examples: 'mytable' tag: tech-specific-cassandra - - id: connection_string - type: string - stability: experimental - 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 stability: experimental diff --git a/model/registry/deprecated/db.yaml b/model/registry/deprecated/db.yaml new file mode 100644 index 0000000000..a3718cf6bc --- /dev/null +++ b/model/registry/deprecated/db.yaml @@ -0,0 +1,13 @@ +groups: + - id: attributes.db.deprecated + prefix: db + type: attribute_group + brief: > + "Describes deprecated db attributes." + attributes: + - id: connection_string + type: string + brief: 'Deprecated, use `server.address`, `server.port` attributes instead.' + deprecated: > + "Removed in favor of `server.address` and `server.port`." + examples: Server=(localdb)\v11.0;Integrated Security=true; diff --git a/model/trace/database.yaml b/model/trace/database.yaml index 8637fbed28..74ea98ceb2 100644 --- a/model/trace/database.yaml +++ b/model/trace/database.yaml @@ -7,8 +7,6 @@ groups: attributes: - ref: db.system requirement_level: required - - - ref: db.connection_string - ref: db.user - ref: db.name requirement_level: From 88d66b53e14590b0fac57455bde49d763817f86f Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 7 Mar 2024 08:23:54 -0800 Subject: [PATCH 19/22] Move DNS lookup metric outside of .NET semconv (#785) --- .chloggen/785.yaml | 4 ++ docs/attributes-registry/dns.md | 14 +++++++ docs/dns/dns-metrics.md | 55 +++++++++++++++++++++++++++ docs/dotnet/dotnet-dns-metrics.md | 7 +--- model/metrics/dns.yaml | 23 +++++++++++ model/metrics/dotnet/dotnet-http.yaml | 38 ------------------ model/registry/dns.yaml | 18 +++++++++ 7 files changed, 116 insertions(+), 43 deletions(-) create mode 100644 .chloggen/785.yaml create mode 100644 docs/attributes-registry/dns.md create mode 100644 docs/dns/dns-metrics.md create mode 100644 model/metrics/dns.yaml create mode 100644 model/registry/dns.yaml diff --git a/.chloggen/785.yaml b/.chloggen/785.yaml new file mode 100644 index 0000000000..f00ba848ef --- /dev/null +++ b/.chloggen/785.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: dns +note: Introduces common DNS lookup duration metric and attributes. +issues: [404] diff --git a/docs/attributes-registry/dns.md b/docs/attributes-registry/dns.md new file mode 100644 index 0000000000..eeb6e10d5e --- /dev/null +++ b/docs/attributes-registry/dns.md @@ -0,0 +1,14 @@ + + +# DNS + +## DNS Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `dns.question.name` | string | The name being queried. [1] | `www.example.com`; `opentelemetry.io` | + +**[1]:** If the name field contains non-printable characters (below 32 or above 126), those characters should be represented as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped. Tabs, carriage returns, and line feeds should be converted to \t, \r, and \n respectively. + \ No newline at end of file diff --git a/docs/dns/dns-metrics.md b/docs/dns/dns-metrics.md new file mode 100644 index 0000000000..46262286cc --- /dev/null +++ b/docs/dns/dns-metrics.md @@ -0,0 +1,55 @@ + + +# Semantic Conventions for DNS queries + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions to apply when instrumenting DNS queries. + + + + + +- [Metrics](#metrics) + - [Metric: `dns.lookup.duration`](#metric-dnslookupduration) + + + +## Metrics + +### Metric: `dns.lookup.duration` + +**Status**: [Experimental][DocumentStatus] + +This metric is optional. + +This metric SHOULD be specified with +[`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 ]`. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `dns.lookup.duration` | Histogram | `s` | Measures the time taken to perform a DNS lookup. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`dns.question.name`](../attributes-registry/dns.md) | string | The name being queried. [1] | `www.example.com`; `dot.net` | Required | +| [`error.type`](../attributes-registry/error.md) | string | Describes the error the DNS lookup failed with. [2] | `host_not_found`; `no_recovery`; `java.net.UnknownHostException` | Conditionally Required: if and only if an error has occurred. | + +**[1]:** If the name field contains non-printable characters (below 32 or above 126), those characters should be represented as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped. Tabs, carriage returns, and line feeds should be converted to \t, \r, and \n respectively. + +**[2]:** Instrumentations SHOULD use error code such as one of errors reported by `getaddrinfo`([Linux or other POSIX systems](https://man7.org/linux/man-pages/man3/getaddrinfo.3.html) / [Windows](https://learn.microsoft.com/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo)) or one reported by the runtime or client library. If error code is not available, the full name of exception type SHOULD be used. + +`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. | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-dns-metrics.md b/docs/dotnet/dotnet-dns-metrics.md index 4240445dd1..6df6fb85d3 100644 --- a/docs/dotnet/dotnet-dns-metrics.md +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -19,19 +19,17 @@ This article defines semantic conventions for DNS metrics emitted by .NET. ### Metric: `dns.lookup.duration` -this metric SHOULD be specified with +This metric SHOULD be specified with [`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 ]`. - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | | `dns.lookup.duration` | Histogram | `s` | Measures the time taken to perform a DNS lookup. [1] | **[1]:** Meter name: `System.Net.NameResolution`; Added in: .NET 8.0 - - | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `dns.question.name` | string | The name being queried. [1] | `www.example.com`; `dot.net` | Required | @@ -55,6 +53,5 @@ for more details. | Value | Description | |---|---| | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | - [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/model/metrics/dns.yaml b/model/metrics/dns.yaml new file mode 100644 index 0000000000..627213d90f --- /dev/null +++ b/model/metrics/dns.yaml @@ -0,0 +1,23 @@ +groups: + - id: metric.dns.lookup.duration + type: metric + metric_name: dns.lookup.duration + stability: experimental + brief: Measures the time taken to perform a DNS lookup. + instrument: histogram + unit: "s" + attributes: + - ref: dns.question.name + requirement_level: required + examples: ["www.example.com", "dot.net"] + - ref: error.type + requirement_level: + conditionally_required: if and only if an error has occurred. + brief: Describes the error the DNS lookup failed with. + note: > + Instrumentations SHOULD use error code such as one of errors reported by + `getaddrinfo`([Linux or other POSIX systems](https://man7.org/linux/man-pages/man3/getaddrinfo.3.html) / + [Windows](https://learn.microsoft.com/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo)) or one reported by the + runtime or client library. + If error code is not available, the full name of exception type SHOULD be used. + examples: ["host_not_found", "no_recovery", "java.net.UnknownHostException"] diff --git a/model/metrics/dotnet/dotnet-http.yaml b/model/metrics/dotnet/dotnet-http.yaml index 9a326bb5d7..6b3723ddb8 100644 --- a/model/metrics/dotnet/dotnet-http.yaml +++ b/model/metrics/dotnet/dotnet-http.yaml @@ -1,42 +1,4 @@ groups: - - id: metric.dotnet.dns.lookup.duration - type: metric - metric_name: dns.lookup.duration - brief: Measures the time taken to perform a DNS lookup. - instrument: histogram - unit: "s" - note: | - Meter name: `System.Net.NameResolution`; Added in: .NET 8.0 - attributes: - - id: dns.question.name - type: string - brief: The name being queried. - requirement_level: required - examples: ["www.example.com", "dot.net"] - note: > - The name being queried. - - If the name field contains non-printable - characters (below 32 or above 126), those characters should be represented - as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped. - Tabs, carriage returns, and line feeds should be converted to \t, \r, and - \n respectively. - - ref: error.type - brief: One of the resolution errors or the full name of exception type. - requirement_level: - conditionally_required: if and only if an error has occurred. - note: | - The following errors codes are reported: - - - "host_not_found" - - "try_again" - - "address_family_not_supported" - - "no_recovery" - - See [SocketError](https://learn.microsoft.com/dotnet/api/system.net.sockets.socketerror) - for more details. - examples: ["host_not_found", "no_recovery", "System.Net.Sockets.SocketException"] - - id: dotnet.http.client.common.attributes type: attribute_group brief: "Common HTTP client attributes" diff --git a/model/registry/dns.yaml b/model/registry/dns.yaml new file mode 100644 index 0000000000..d4042c4add --- /dev/null +++ b/model/registry/dns.yaml @@ -0,0 +1,18 @@ +groups: + - id: registry.dns + type: attribute_group + prefix: dns + brief: > + This document defines the shared attributes used to report a DNS query. + attributes: + - id: question.name + type: string + stability: experimental + brief: The name being queried. + examples: ["www.example.com", "opentelemetry.io"] + note: > + If the name field contains non-printable + characters (below 32 or above 126), those characters should be represented + as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped. + Tabs, carriage returns, and line feeds should be converted to \t, \r, and + \n respectively. From 3d409a7d4abe03e6b3df0c9c34e6086481b5a71a Mon Sep 17 00:00:00 2001 From: Alexandra Konrad <10500694+trisch-me@users.noreply.github.com> Date: Thu, 7 Mar 2024 18:04:52 +0100 Subject: [PATCH 20/22] move faas to registry (#525) Co-authored-by: Joao Grassi Co-authored-by: Josh Suereth --- docs/attributes-registry/README.md | 1 + docs/attributes-registry/faas.md | 93 ++++++++++++++ docs/faas/faas-metrics.md | 18 +-- docs/faas/faas-spans.md | 28 ++--- docs/resource/faas.md | 8 +- model/faas-common.yaml | 68 +--------- model/registry/faas.yaml | 195 +++++++++++++++++++++++++++++ model/resource/faas.yaml | 62 +-------- model/trace/faas.yaml | 84 +++---------- 9 files changed, 343 insertions(+), 214 deletions(-) create mode 100644 docs/attributes-registry/faas.md create mode 100644 model/registry/faas.yaml diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 113725054e..00ff6ad8e6 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -39,6 +39,7 @@ Currently, the following namespaces exist: * [Disk](disk.md) * [Error](error.md) * [Exception](exception.md) +* [FaaS](faas.md) * [Host](host.md) * [HTTP](http.md) * [K8s](k8s.md) diff --git a/docs/attributes-registry/faas.md b/docs/attributes-registry/faas.md new file mode 100644 index 0000000000..4f8f5e4ea8 --- /dev/null +++ b/docs/attributes-registry/faas.md @@ -0,0 +1,93 @@ + + +# FaaS + +## FaaS Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `faas.coldstart` | boolean | A boolean that is true if the serverless function is executed for the first time (aka cold-start). | | +| `faas.cron` | string | A string containing the schedule period as [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). | `0/5 * * * ? *` | +| `faas.document.collection` | string | The name of the source on which the triggering operation was performed. For example, in Cloud Storage or S3 corresponds to the bucket name, and in Cosmos DB to the database name. | `myBucketName`; `myDbName` | +| `faas.document.name` | string | The document name/table subjected to the operation. For example, in Cloud Storage or S3 is the name of the file, and in Cosmos DB the table name. | `myFile.txt`; `myTableName` | +| `faas.document.operation` | string | Describes the type of the operation that was performed on the data. | `insert` | +| `faas.document.time` | string | A string containing the time when the data was accessed in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | +| `faas.instance` | string | The execution environment ID as a string, that will be potentially reused for other invocations to the same function/function version. [1] | `2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de` | +| `faas.invocation_id` | string | The invocation ID of the current function invocation. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | +| `faas.invoked_name` | string | The name of the invoked function. [2] | `my-function` | +| `faas.invoked_provider` | string | The cloud provider of the invoked function. [3] | `alibaba_cloud` | +| `faas.invoked_region` | string | The cloud region of the invoked function. [4] | `eu-central-1` | +| `faas.max_memory` | int | The amount of memory available to the serverless function converted to Bytes. [5] | `134217728` | +| `faas.name` | string | The name of the single function that this runtime instance executes. [6] | `my-function`; `myazurefunctionapp/some-function-name` | +| `faas.time` | string | A string containing the function invocation time in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | +| `faas.version` | string | The immutable version of the function being executed. [7] | `26`; `pinkfroid-00002` | + +**[1]:** * **AWS Lambda:** Use the (full) log stream name. + +**[2]:** SHOULD be equal to the `faas.name` resource attribute of the invoked function. + +**[3]:** SHOULD be equal to the `cloud.provider` resource attribute of the invoked function. + +**[4]:** SHOULD be equal to the `cloud.region` resource attribute of the invoked function. + +**[5]:** It's recommended to set this attribute since e.g. too little memory can easily stop a Java AWS Lambda function from working correctly. On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` provides this information (which must be multiplied by 1,048,576). + +**[6]:** This is the name of the function as configured/deployed on the FaaS +platform and is usually different from the name of the callback +function (which may be stored in the +[`code.namespace`/`code.function`](/docs/general/attributes.md#source-code-attributes) +span attributes). + +For some cloud providers, the above definition is ambiguous. The following +definition of function name MUST be used for this attribute +(and consequently the span name) for the listed cloud providers/products: + +* **Azure:** The full name `/`, i.e., function app name + followed by a forward slash followed by the function name (this form + can also be seen in the resource JSON for the function). + This means that a span attribute MUST be used, as an Azure function + app can host multiple functions that would usually share + a TracerProvider (see also the `cloud.resource_id` attribute). + +**[7]:** Depending on the cloud provider and platform, use: + +* **AWS Lambda:** The [function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html) + (an integer represented as a decimal string). +* **Google Cloud Run (Services):** The [revision](https://cloud.google.com/run/docs/managing/revisions) + (i.e., the function name plus the revision suffix). +* **Google Cloud Functions:** The value of the + [`K_REVISION` environment variable](https://cloud.google.com/functions/docs/env-var#runtime_environment_variables_set_automatically). +* **Azure Functions:** Not applicable. Do not set this attribute. + +`faas.document.operation` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `insert` | When a new object is created. | +| `edit` | When an object is modified. | +| `delete` | When an object is deleted. | + +`faas.invoked_provider` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `alibaba_cloud` | Alibaba Cloud | +| `aws` | Amazon Web Services | +| `azure` | Microsoft Azure | +| `gcp` | Google Cloud Platform | +| `tencent_cloud` | Tencent Cloud | + +`faas.trigger` MUST be one of the following: + +| Value | Description | +|---|---| +| `datasource` | A response to some data source operation such as a database or filesystem read/write | +| `http` | To provide an answer to an inbound HTTP request | +| `pubsub` | A function is set to be executed when messages are sent to a messaging system | +| `timer` | A function is scheduled to be executed regularly | +| `other` | If none of the others apply | + \ No newline at end of file diff --git a/docs/faas/faas-metrics.md b/docs/faas/faas-metrics.md index d6046b04f9..22dbc92556 100644 --- a/docs/faas/faas-metrics.md +++ b/docs/faas/faas-metrics.md @@ -58,7 +58,7 @@ 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 | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | `faas.trigger` MUST be one of the following: @@ -88,7 +88,7 @@ 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 | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | `faas.trigger` MUST be one of the following: @@ -114,7 +114,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | `faas.trigger` MUST be one of the following: @@ -140,7 +140,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | `faas.trigger` MUST be one of the following: @@ -166,7 +166,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | `faas.trigger` MUST be one of the following: @@ -192,7 +192,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | `faas.trigger` MUST be one of the following: @@ -218,7 +218,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | `faas.trigger` MUST be one of the following: @@ -248,7 +248,7 @@ 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 | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | `faas.trigger` MUST be one of the following: @@ -274,7 +274,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | `faas.trigger` MUST be one of the following: diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md index 34a03528db..ee38715df3 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -42,8 +42,8 @@ If Spans following this convention are produced, a Resource of type `faas` MUST | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`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 | +| [`faas.invocation_id`](../attributes-registry/faas.md) | string | The invocation ID of the current function invocation. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. [2] | `datasource` | Recommended | **[1]:** 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. @@ -122,8 +122,8 @@ For incoming FaaS spans, the span kind MUST be `Server`. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.coldstart` | boolean | A boolean that is true if the serverless function is executed for the first time (aka cold-start). | | Recommended | -| `faas.trigger` | string | Type of the trigger which caused this function invocation. [1] | `datasource` | Required | +| [`faas.coldstart`](../attributes-registry/faas.md) | boolean | A boolean that is true if the serverless function is executed for the first time (aka cold-start). | | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. [1] | `datasource` | Required | **[1]:** For the server/consumer span on the incoming side, `faas.trigger` MUST be set. @@ -161,9 +161,9 @@ which the invoked FaaS instance reports about itself, if it's instrumented. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.invoked_name` | string | The name of the invoked function. [1] | `my-function` | Required | -| `faas.invoked_provider` | string | The cloud provider of the invoked function. [2] | `alibaba_cloud` | Required | -| `faas.invoked_region` | string | The cloud region of the invoked function. [3] | `eu-central-1` | Conditionally Required: [4] | +| [`faas.invoked_name`](../attributes-registry/faas.md) | string | The name of the invoked function. [1] | `my-function` | Required | +| [`faas.invoked_provider`](../attributes-registry/faas.md) | string | The cloud provider of the invoked function. [2] | `alibaba_cloud` | Required | +| [`faas.invoked_region`](../attributes-registry/faas.md) | string | The cloud region of the invoked function. [3] | `eu-central-1` | Conditionally Required: [4] | **[1]:** SHOULD be equal to the `faas.name` resource attribute of the invoked function. @@ -196,13 +196,13 @@ This section describes how to handle the span creation and additional attributes A datasource function is triggered as a response to some data source operation such as a database or filesystem read/write. FaaS instrumentations that produce `faas` spans with trigger `datasource`, SHOULD use the following set of attributes. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.document.collection` | string | The name of the source on which the triggering operation was performed. For example, in Cloud Storage or S3 corresponds to the bucket name, and in Cosmos DB to the database name. | `myBucketName`; `myDbName` | Required | -| `faas.document.name` | string | The document name/table subjected to the operation. For example, in Cloud Storage or S3 is the name of the file, and in Cosmos DB the table name. | `myFile.txt`; `myTableName` | Recommended | -| `faas.document.operation` | string | Describes the type of the operation that was performed on the data. | `insert` | Required | -| `faas.document.time` | string | A string containing the time when the data was accessed in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | Recommended | +| [`faas.document.collection`](../attributes-registry/faas.md) | string | The name of the source on which the triggering operation was performed. For example, in Cloud Storage or S3 corresponds to the bucket name, and in Cosmos DB to the database name. | `myBucketName`; `myDbName` | Required | +| [`faas.document.name`](../attributes-registry/faas.md) | string | The document name/table subjected to the operation. For example, in Cloud Storage or S3 is the name of the file, and in Cosmos DB the table name. | `myFile.txt`; `myTableName` | Recommended | +| [`faas.document.operation`](../attributes-registry/faas.md) | string | Describes the type of the operation that was performed on the data. | `insert` | Required | +| [`faas.document.time`](../attributes-registry/faas.md) | string | A string containing the time when the data was accessed in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | Recommended | `faas.document.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. @@ -232,8 +232,8 @@ A function is scheduled to be executed regularly. The following additional attri | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.cron` | string | A string containing the schedule period as [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). | `0/5 * * * ? *` | Recommended | -| `faas.time` | string | A string containing the function invocation time in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | Recommended | +| [`faas.cron`](../attributes-registry/faas.md) | string | A string containing the schedule period as [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). | `0/5 * * * ? *` | Recommended | +| [`faas.time`](../attributes-registry/faas.md) | string | A string containing the function invocation time in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | Recommended | ### Other diff --git a/docs/resource/faas.md b/docs/resource/faas.md index c83eabc193..b354c2fdad 100644 --- a/docs/resource/faas.md +++ b/docs/resource/faas.md @@ -17,10 +17,10 @@ See also: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`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 | -| `faas.version` | string | The immutable version of the function being executed. [5] | `26`; `pinkfroid-00002` | Recommended | +| [`faas.instance`](../attributes-registry/faas.md) | 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`](../attributes-registry/faas.md) | int | The amount of memory available to the serverless function converted to Bytes. [3] | `134217728` | Recommended | +| [`faas.name`](../attributes-registry/faas.md) | string | The name of the single function that this runtime instance executes. [4] | `my-function`; `myazurefunctionapp/some-function-name` | Required | +| [`faas.version`](../attributes-registry/faas.md) | string | The immutable version of the function being executed. [5] | `26`; `pinkfroid-00002` | Recommended | **[1]:** 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. diff --git a/model/faas-common.yaml b/model/faas-common.yaml index 11a8b430c0..9d951485b2 100644 --- a/model/faas-common.yaml +++ b/model/faas-common.yaml @@ -4,66 +4,12 @@ groups: brief: "Describes FaaS attributes." prefix: faas attributes: - - id: trigger - brief: 'Type of the trigger which caused this function invocation.' - type: - allow_custom_values: false - members: - - id: datasource - value: 'datasource' - brief: 'A response to some data source operation such as a database or filesystem read/write' - - id: http - value: 'http' - brief: 'To provide an answer to an inbound HTTP request' - - id: pubsub - value: 'pubsub' - brief: 'A function is set to be executed when messages are sent to a messaging system' - - id: timer - value: 'timer' - brief: 'A function is scheduled to be executed regularly' - - id: other - value: 'other' - brief: 'If none of the others apply' - stability: experimental - - id: invoked_name - type: string - stability: experimental + - ref: faas.trigger + - ref: faas.invoked_name requirement_level: required - brief: > - The name of the invoked function. - note: > - SHOULD be equal to the `faas.name` resource attribute of the - invoked function. - examples: 'my-function' - - id: invoked_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: 'tencent_cloud' - value: 'tencent_cloud' - brief: 'Tencent Cloud' - stability: experimental + - ref: faas.invoked_provider requirement_level: required - brief: > - The cloud provider of the invoked function. - note: > - SHOULD be equal to the `cloud.provider` resource attribute of the - invoked function. - - id: invoked_region - type: string - stability: experimental + - ref: faas.invoked_region requirement_level: conditionally_required: > For some cloud providers, like AWS or GCP, the region in which a @@ -73,9 +19,3 @@ groups: `faas.invoked_region` MUST be set accordingly. If the region is unknown to the client or not required for identifying the invoked function, setting `faas.invoked_region` is optional. - brief: > - The cloud region of the invoked function. - note: > - SHOULD be equal to the `cloud.region` resource attribute of the - invoked function. - examples: 'eu-central-1' diff --git a/model/registry/faas.yaml b/model/registry/faas.yaml new file mode 100644 index 0000000000..12c5816a20 --- /dev/null +++ b/model/registry/faas.yaml @@ -0,0 +1,195 @@ +groups: + - id: registry.faas + brief: FaaS attributes + type: attribute_group + prefix: faas + attributes: + - id: name + type: string + stability: experimental + brief: > + The name of the single function that this runtime instance executes. + note: | + This is the name of the function as configured/deployed on the FaaS + platform and is usually different from the name of the callback + function (which may be stored in the + [`code.namespace`/`code.function`](/docs/general/attributes.md#source-code-attributes) + span attributes). + + For some cloud providers, the above definition is ambiguous. The following + definition of function name MUST be used for this attribute + (and consequently the span name) for the listed cloud providers/products: + + * **Azure:** The full name `/`, i.e., function app name + followed by a forward slash followed by the function name (this form + can also be seen in the resource JSON for the function). + This means that a span attribute MUST be used, as an Azure function + app can host multiple functions that would usually share + a TracerProvider (see also the `cloud.resource_id` attribute). + examples: ['my-function', 'myazurefunctionapp/some-function-name'] + - id: version + type: string + stability: experimental + brief: The immutable version of the function being executed. + note: | + Depending on the cloud provider and platform, use: + + * **AWS Lambda:** The [function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html) + (an integer represented as a decimal string). + * **Google Cloud Run (Services):** The [revision](https://cloud.google.com/run/docs/managing/revisions) + (i.e., the function name plus the revision suffix). + * **Google Cloud Functions:** The value of the + [`K_REVISION` environment variable](https://cloud.google.com/functions/docs/env-var#runtime_environment_variables_set_automatically). + * **Azure Functions:** Not applicable. Do not set this attribute. + examples: ['26', 'pinkfroid-00002'] + - id: instance + type: string + stability: experimental + brief: > + The execution environment ID as a string, that will be potentially reused + for other invocations to the same function/function version. + note: > + * **AWS Lambda:** Use the (full) log stream name. + examples: ['2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de'] + - id: max_memory + type: int + stability: experimental + brief: > + The amount of memory available to the serverless function converted to Bytes. + note: > + It's recommended to set this attribute since e.g. too little memory can easily + stop a Java AWS Lambda function from working correctly. + On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` + provides this information (which must be multiplied by 1,048,576). + examples: 134217728 + - id: trigger + stability: experimental + brief: > + Type of the trigger which caused this function invocation. + type: + allow_custom_values: false + members: + - id: datasource + value: 'datasource' + brief: 'A response to some data source operation such as a database or filesystem read/write' + - id: http + value: 'http' + brief: 'To provide an answer to an inbound HTTP request' + - id: pubsub + value: 'pubsub' + brief: 'A function is set to be executed when messages are sent to a messaging system' + - id: timer + value: 'timer' + brief: 'A function is scheduled to be executed regularly' + - id: other + value: 'other' + brief: 'If none of the others apply' + - id: invoked_name + type: string + stability: experimental + brief: > + The name of the invoked function. + note: > + SHOULD be equal to the `faas.name` resource attribute of the + invoked function. + examples: 'my-function' + - id: invoked_provider + stability: experimental + 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: 'tencent_cloud' + value: 'tencent_cloud' + brief: 'Tencent Cloud' + brief: > + The cloud provider of the invoked function. + note: > + SHOULD be equal to the `cloud.provider` resource attribute of the + invoked function. + - id: invoked_region + type: string + stability: experimental + brief: > + The cloud region of the invoked function. + note: > + SHOULD be equal to the `cloud.region` resource attribute of the + invoked function. + examples: 'eu-central-1' + - id: invocation_id + type: string + stability: experimental + brief: > + The invocation ID of the current function invocation. + examples: 'af9d5aa4-a685-4c5f-a22b-444f80b3cc28' + - id: time + type: string + stability: experimental + brief: > + A string containing the function invocation time in the + [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) + format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). + examples: "2020-01-23T13:47:06Z" + - id: cron + type: string + stability: experimental + brief: > + A string containing the schedule period as + [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). + examples: "0/5 * * * ? *" + - id: coldstart + type: boolean + stability: experimental + brief: > + A boolean that is true if the serverless function is executed for the + first time (aka cold-start). + - id: document.collection + type: string + stability: experimental + brief: > + The name of the source on which the triggering operation was performed. + For example, in Cloud Storage or S3 corresponds to the bucket name, + and in Cosmos DB to the database name. + examples: ['myBucketName', 'myDbName'] + - id: document.operation + stability: experimental + type: + allow_custom_values: true + members: + - id: insert + value: 'insert' + brief: 'When a new object is created.' + - id: edit + value: 'edit' + brief: 'When an object is modified.' + - id: delete + value: 'delete' + brief: 'When an object is deleted.' + brief: 'Describes the type of the operation that was performed on the data.' + - id: document.time + type: string + stability: experimental + brief: > + A string containing the time when the data was accessed in the + [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) + format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). + examples: "2020-01-23T13:47:06Z" + - id: document.name + type: string + stability: experimental + brief: > + The document name/table subjected to the operation. + For example, in Cloud Storage or S3 is the name of + the file, and in Cosmos DB the table name. + examples: ["myFile.txt", "myTableName"] diff --git a/model/resource/faas.yaml b/model/resource/faas.yaml index e73ee38646..ab028c89bb 100644 --- a/model/resource/faas.yaml +++ b/model/resource/faas.yaml @@ -5,63 +5,9 @@ groups: brief: > A serverless instance. attributes: - - id: name - type: string - stability: experimental + - ref: faas.name requirement_level: required - brief: > - The name of the single function that this runtime instance executes. - note: | - This is the name of the function as configured/deployed on the FaaS - platform and is usually different from the name of the callback - function (which may be stored in the - [`code.namespace`/`code.function`](/docs/general/attributes.md#source-code-attributes) - span attributes). - - For some cloud providers, the above definition is ambiguous. The following - definition of function name MUST be used for this attribute - (and consequently the span name) for the listed cloud providers/products: - - * **Azure:** The full name `/`, i.e., function app name - followed by a forward slash followed by the function name (this form - can also be seen in the resource JSON for the function). - This means that a span attribute MUST be used, as an Azure function - app can host multiple functions that would usually share - a TracerProvider (see also the `cloud.resource_id` attribute). - examples: ['my-function', 'myazurefunctionapp/some-function-name'] - - id: version - type: string - stability: experimental - brief: The immutable version of the function being executed. - note: | - Depending on the cloud provider and platform, use: - - * **AWS Lambda:** The [function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html) - (an integer represented as a decimal string). - * **Google Cloud Run (Services):** The [revision](https://cloud.google.com/run/docs/managing/revisions) - (i.e., the function name plus the revision suffix). - * **Google Cloud Functions:** The value of the - [`K_REVISION` environment variable](https://cloud.google.com/functions/docs/env-var#runtime_environment_variables_set_automatically). - * **Azure Functions:** Not applicable. Do not set this attribute. - examples: ['26', 'pinkfroid-00002'] - - id: instance - type: string - stability: experimental - brief: > - The execution environment ID as a string, that will be potentially reused - for other invocations to the same function/function version. - note: > - * **AWS Lambda:** Use the (full) log stream name. - examples: ['2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de'] - - id: max_memory - type: int - stability: experimental - brief: > - The amount of memory available to the serverless function converted to Bytes. - note: > - It's recommended to set this attribute since e.g. too little memory can easily - stop a Java AWS Lambda function from working correctly. - On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` - provides this information (which must be multiplied by 1,048,576). - examples: 134217728 + - ref: faas.version + - ref: faas.instance + - ref: faas.max_memory - ref: cloud.resource_id diff --git a/model/trace/faas.yaml b/model/trace/faas.yaml index 3eb9b53354..58dba9d979 100644 --- a/model/trace/faas.yaml +++ b/model/trace/faas.yaml @@ -18,11 +18,7 @@ groups: trigger that corresponding incoming would have (i.e., this has nothing to do with the underlying transport used to make the API call to invoke the lambda, which is often HTTP). - - id: invocation_id - type: string - stability: experimental - brief: 'The invocation ID of the current function invocation.' - examples: 'af9d5aa4-a685-4c5f-a22b-444f80b3cc28' + - ref: faas.invocation_id - ref: cloud.resource_id - id: faas_span.datasource @@ -32,47 +28,12 @@ groups: Semantic Convention for FaaS triggered as a response to some data source operation such as a database or filesystem read/write. attributes: - - id: collection - type: string - stability: experimental + - ref: faas.document.collection requirement_level: required - brief: > - The name of the source on which the triggering operation was performed. - For example, in Cloud Storage or S3 corresponds to the bucket name, - and in Cosmos DB to the database name. - examples: ['myBucketName', 'myDbName'] - - id: operation - stability: experimental + - ref: faas.document.operation requirement_level: required - type: - allow_custom_values: true - members: - - id: insert - value: 'insert' - brief: 'When a new object is created.' - - id: edit - value: 'edit' - brief: 'When an object is modified.' - - id: delete - value: 'delete' - brief: 'When an object is deleted.' - brief: 'Describes the type of the operation that was performed on the data.' - - id: time - type: string - stability: experimental - brief: > - A string containing the time when the data was accessed in the - [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) - format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). - examples: "2020-01-23T13:47:06Z" - - id: name - type: string - stability: experimental - brief: > - The document name/table subjected to the operation. - For example, in Cloud Storage or S3 is the name of - the file, and in Cosmos DB the table name. - examples: ["myFile.txt", "myTableName"] + - ref: faas.document.time + - ref: faas.document.name - id: faas_span.http type: span @@ -96,21 +57,8 @@ groups: brief: > Semantic Convention for FaaS scheduled to be executed regularly. attributes: - - id: time - type: string - stability: experimental - brief: > - A string containing the function invocation time in the - [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) - format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). - examples: "2020-01-23T13:47:06Z" - - id: cron - type: string - stability: experimental - brief: > - A string containing the schedule period as - [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). - examples: "0/5 * * * ? *" + - ref: faas.time + - ref: faas.cron - id: faas_span.in span_kind: server @@ -119,12 +67,7 @@ groups: brief: > Contains additional attributes for incoming FaaS spans. attributes: - - id: coldstart - type: boolean - stability: experimental - brief: > - A boolean that is true if the serverless function is executed for the - first time (aka cold-start). + - ref: faas.coldstart - ref: faas.trigger requirement_level: required note: | @@ -146,5 +89,16 @@ groups: Contains additional attributes for outgoing FaaS spans. attributes: - ref: faas.invoked_name + requirement_level: required - ref: faas.invoked_provider + requirement_level: required - ref: faas.invoked_region + requirement_level: + conditionally_required: > + For some cloud providers, like AWS or GCP, the region in which a + function is hosted is essential to uniquely identify the function + and also part of its endpoint. Since it's part of the endpoint + being called, the region is always known to clients. In these cases, + `faas.invoked_region` MUST be set accordingly. If the region is + unknown to the client or not required for identifying the invoked + function, setting `faas.invoked_region` is optional. From a3252cb6058a428f0616b6e649765cd4d04f8578 Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Fri, 8 Mar 2024 13:29:44 +0100 Subject: [PATCH 21/22] Clarify metric attributes should be namespaced (#786) Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com> Co-authored-by: Chris Mark Co-authored-by: Liudmila Molkova --- .chloggen/clarify-metric-namespace.yaml | 5 +++++ docs/general/metrics.md | 21 +++++++++++++++++++++ 2 files changed, 26 insertions(+) create mode 100755 .chloggen/clarify-metric-namespace.yaml diff --git a/.chloggen/clarify-metric-namespace.yaml b/.chloggen/clarify-metric-namespace.yaml new file mode 100755 index 0000000000..7fffee1683 --- /dev/null +++ b/.chloggen/clarify-metric-namespace.yaml @@ -0,0 +1,5 @@ +change_type: 'enhancement' +component: metrics +note: Clarify metric attributes should be namespaced. +issues: [394] +subtext: diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 2f235e23ce..d76440f253 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -11,6 +11,7 @@ aliases: [docs/specs/semconv/general/metrics-general] - [General Guidelines](#general-guidelines) - [Name Reuse Prohibition](#name-reuse-prohibition) + - [Metric attributes](#metric-attributes) - [Units](#units) - [Naming rules for Counters and UpDownCounters](#naming-rules-for-counters-and-updowncounters) - [Pluralization](#pluralization) @@ -89,6 +90,26 @@ When introducing a new metric name check all existing schema files to make sure the name does not appear as a key of any "rename_metrics" section (keys denote old metric names in rename operations). +### Metric attributes + +Metric attributes SHOULD follow the general [attribute naming rules](attribute-naming.md). +In particular, metric attributes SHOULD have a namespace. + +Metric attributes SHOULD be added under the metric namespace when their usage and +semantics are exclusive to the metric. + +Examples: + +Attributes `mode` and `mountpoint` for metric `system.filesystem.usage` +should be namespaced as `system.filesystem.mode` and `system.filesystem.mountpoint`. + +Metrics can also have attributes outside of their namespace. + +Examples: + +Metric `http.server.request.duration` uses attributes from the registry such as +`server.port`, `error.type`. + ### Units Conventional metrics or metrics that have their units included in From c8b61636277c9577a8e1948f1df70b4da8716d2d Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 8 Mar 2024 08:41:04 -0800 Subject: [PATCH 22/22] Deprecate `db.jdbc.driver_classname` attribute since it's not used (#796) --- .chloggen/796.yaml | 4 ++++ docs/attributes-registry/db.md | 10 +--------- docs/database/mssql.md | 1 - docs/database/sql.md | 1 - model/registry/db.yaml | 7 ------- model/registry/deprecated/db.yaml | 7 ++++++- model/trace/database.yaml | 2 -- 7 files changed, 11 insertions(+), 21 deletions(-) create mode 100644 .chloggen/796.yaml diff --git a/.chloggen/796.yaml b/.chloggen/796.yaml new file mode 100644 index 0000000000..725dc48513 --- /dev/null +++ b/.chloggen/796.yaml @@ -0,0 +1,4 @@ +change_type: deprecation +component: db +note: Deprecate `db.jdbc.driver_classname` attribute +issues: [796] diff --git a/docs/attributes-registry/db.md b/docs/attributes-registry/db.md index 5441b91de9..be7f5753d0 100644 --- a/docs/attributes-registry/db.md +++ b/docs/attributes-registry/db.md @@ -9,7 +9,6 @@ - [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) @@ -178,14 +177,6 @@ **[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 @@ -228,4 +219,5 @@ | Attribute | Type | Description | Examples | |---|---|---|---| | `db.connection_string` | string | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, use `server.address`, `server.port` attributes instead. | `Server=(localdb)\v11.0;Integrated Security=true;` | +| `db.jdbc.driver_classname` | string | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Removed, no replacement at this time. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | \ No newline at end of file diff --git a/docs/database/mssql.md b/docs/database/mssql.md index 6eeaf08030..e0ad3c6727 100644 --- a/docs/database/mssql.md +++ b/docs/database/mssql.md @@ -17,7 +17,6 @@ described on this page. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`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 | | [`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). [2] | `public.users`; `customers` | Recommended | diff --git a/docs/database/sql.md b/docs/database/sql.md index d60e3e158e..17b8dcc892 100644 --- a/docs/database/sql.md +++ b/docs/database/sql.md @@ -15,7 +15,6 @@ described on this page. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`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.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. diff --git a/model/registry/db.yaml b/model/registry/db.yaml index a94eef9471..4185c279ab 100644 --- a/model/registry/db.yaml +++ b/model/registry/db.yaml @@ -192,13 +192,6 @@ groups: 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 - stability: experimental - 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 stability: experimental diff --git a/model/registry/deprecated/db.yaml b/model/registry/deprecated/db.yaml index a3718cf6bc..1dd6996704 100644 --- a/model/registry/deprecated/db.yaml +++ b/model/registry/deprecated/db.yaml @@ -9,5 +9,10 @@ groups: type: string brief: 'Deprecated, use `server.address`, `server.port` attributes instead.' deprecated: > - "Removed in favor of `server.address` and `server.port`." + "Replaced by `server.address` and `server.port`." examples: Server=(localdb)\v11.0;Integrated Security=true; + - id: jdbc.driver_classname + type: string + brief: 'Removed, no replacement at this time.' + deprecated: 'Removed as not used.' + examples: ['org.postgresql.Driver', 'com.microsoft.sqlserver.jdbc.SQLServerDriver'] diff --git a/model/trace/database.yaml b/model/trace/database.yaml index 74ea98ceb2..5d7d4fc269 100644 --- a/model/trace/database.yaml +++ b/model/trace/database.yaml @@ -183,8 +183,6 @@ groups: attributes: - ref: db.sql.table tag: tech-specific - - ref: db.jdbc.driver_classname - tag: tech-specific - id: db.cosmosdb type: span