From 56286849c94324fbe87adc69fba92ea4245d1e3d Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 2 Oct 2023 08:45:46 -0700 Subject: [PATCH 1/4] BREAKING: Remove `server.socket.address` attribute from http and rpc metrics (#350) --- CHANGELOG.md | 2 ++ docs/http/http-metrics.md | 12 ---------- docs/rpc/rpc-metrics.md | 42 ++++++++++++++++++---------------- model/metrics/http.yaml | 1 - model/metrics/rpc-metrics.yaml | 2 -- 5 files changed, 24 insertions(+), 35 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ce87eb3c0c..18b2cb8f85 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -125,6 +125,8 @@ release. ([#289](https://github.com/open-telemetry/semantic-conventions/pull/289)) - BREAKING: Add `url.scheme` to `http.client.*` metrics ([#357](https://github.com/open-telemetry/semantic-conventions/pull/357)) +- BREAKING: Remove `server.socket.address` from HTTP and RPC client metrics. + ([#350](https://github.com/open-telemetry/semantic-conventions/pull/350)) ## v1.21.0 (2023-07-13) diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 101ce3c5c0..e488fd5f60 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -463,7 +463,6 @@ 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 | [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | | [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `example.com` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | -| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [7] | `10.5.3.2` | Recommended: If different than `server.address`. | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Required | **[1]:** If the request fails with an error before response status code was sent or received, @@ -511,9 +510,6 @@ SHOULD NOT be set if capturing it would require an extra DNS lookup. **[6]:** If not default (`80` for `http` scheme, `443` for `https`). -**[7]:** When observed from the client side, this SHOULD represent the immediate server peer address. -When observed from the server side, this SHOULD represent the physical server address. - `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 | @@ -560,7 +556,6 @@ This metric is optional. | [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | | [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `example.com` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | -| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [7] | `10.5.3.2` | Recommended: If different than `server.address`. | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Required | **[1]:** If the request fails with an error before response status code was sent or received, @@ -608,9 +603,6 @@ SHOULD NOT be set if capturing it would require an extra DNS lookup. **[6]:** If not default (`80` for `http` scheme, `443` for `https`). -**[7]:** When observed from the client side, this SHOULD represent the immediate server peer address. -When observed from the server side, this SHOULD represent the physical server address. - `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 | @@ -657,7 +649,6 @@ This metric is optional. | [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | | [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `example.com` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | -| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [7] | `10.5.3.2` | Recommended: If different than `server.address`. | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Required | **[1]:** If the request fails with an error before response status code was sent or received, @@ -705,9 +696,6 @@ SHOULD NOT be set if capturing it would require an extra DNS lookup. **[6]:** If not default (`80` for `http` scheme, `443` for `https`). -**[7]:** When observed from the client side, this SHOULD represent the immediate server peer address. -When observed from the server side, this SHOULD represent the physical server address. - `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 | diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index 8ff24ac2b8..44021f7d01 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -217,39 +217,41 @@ This metric is [recommended][MetricRecommended]. Below is a table of attributes that SHOULD be included on client and server RPC measurements. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`rpc.system`](rpc-spans.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | -| [`rpc.service`](rpc-spans.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended | -| [`rpc.method`](rpc-spans.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended | | [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). 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. | `tcp`; `udp` | Recommended | | [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../general/attributes.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | -| [`server.port`](../general/attributes.md) | int | Server port number [4] | `80`; `8080`; `443` | Conditionally Required: See below | -| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [5] | `10.5.3.2` | See below | -| [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [6] | `16456` | Recommended: [7] | +| [`rpc.method`](rpc-spans.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [1] | `exampleMethod` | Recommended | +| [`rpc.service`](rpc-spans.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [2] | `myservice.EchoService` | Recommended | +| [`rpc.system`](rpc-spans.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number [4] | `80`; `8080`; `443` | Recommended | -**[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). +**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). -**[2]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). +**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). -**[3]:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +the server address behind any intermediaries (e.g. proxies) if it's available. **[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. -**[5]:** When observed from the client side, this SHOULD represent the immediate server peer address. -When observed from the server side, this SHOULD represent the physical server address. +`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. -**[6]:** When observed from the client side, this SHOULD represent the immediate server peer port. -When observed from the server side, this SHOULD represent the physical server port. - -**[7]:** If different than `server.port` and if `server.socket.address` is set. +| Value | Description | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | -**Additional attribute requirements:** At least one of the following sets of attributes is required: +`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. -* [`server.socket.address`](../general/attributes.md) -* [`server.address`](../general/attributes.md) +| Value | Description | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | `rpc.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. diff --git a/model/metrics/http.yaml b/model/metrics/http.yaml index a5ceceb288..8e6f350929 100644 --- a/model/metrics/http.yaml +++ b/model/metrics/http.yaml @@ -66,7 +66,6 @@ groups: - ref: http.response.status_code - ref: network.protocol.name - ref: network.protocol.version - - ref: server.socket.address - ref: error.type requirement_level: conditionally_required: If request has ended with an error. diff --git a/model/metrics/rpc-metrics.yaml b/model/metrics/rpc-metrics.yaml index 237107e6d8..43186b0765 100644 --- a/model/metrics/rpc-metrics.yaml +++ b/model/metrics/rpc-metrics.yaml @@ -13,8 +13,6 @@ groups: - ref: network.type - ref: server.address - ref: server.port - - ref: server.socket.address - - ref: server.socket.port # RPC Server metrics - id: metric.rpc.server.duration From 3286326b17fdd9f6aebc17f97e1ee01f9d450577 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 2 Oct 2023 08:57:37 -0700 Subject: [PATCH 2/4] Improve network briefs (#352) --- CHANGELOG.md | 2 + docs/database/database-spans.md | 32 ++++++---- docs/general/attributes.md | 20 ++++-- docs/http/http-metrics.md | 102 +++++++++++++++++------------- docs/http/http-spans.md | 22 +++++-- docs/messaging/messaging-spans.md | 38 +++++++---- docs/rpc/rpc-metrics.md | 28 +++++--- docs/rpc/rpc-spans.md | 42 ++++++++---- docs/system/system-metrics.md | 8 ++- model/network.yaml | 18 +++--- 10 files changed, 197 insertions(+), 115 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 18b2cb8f85..d93c97e1bf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -127,6 +127,8 @@ release. ([#357](https://github.com/open-telemetry/semantic-conventions/pull/357)) - BREAKING: Remove `server.socket.address` from HTTP and RPC client metrics. ([#350](https://github.com/open-telemetry/semantic-conventions/pull/350)) +- Improve network attribute briefs. + ([#352](https://github.com/open-telemetry/semantic-conventions/pull/352)) ## v1.21.0 (2023-07-13) diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index d942b29f16..544798808e 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -67,24 +67,32 @@ Some database systems may allow a connection to switch to a different `db.user`, | `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Required | | `db.connection_string` | string | The connection string used to connect to the database. It is recommended to remove embedded credentials. | `Server=(localdb)\v11.0;Integrated Security=true;` | Recommended | | `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended | -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). 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. | `tcp`; `udp` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the database host. [1] | `example.com` | Conditionally Required: See alternative attributes below. | -| [`server.port`](../general/attributes.md) | int | Server port number [2] | `80`; `8080`; `443` | Conditionally Required: [3] | -| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [4] | `10.5.3.2` | See below | -| [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [5] | `16456` | Recommended: If different than `server.port`. | - -**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | +| [`server.address`](../general/attributes.md) | string | Name of the database host. [3] | `example.com` | Conditionally Required: See alternative attributes below. | +| [`server.port`](../general/attributes.md) | int | Server port number [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [6] | `10.5.3.2` | See below | +| [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [7] | `16456` | Recommended: If different than `server.port`. | + +**[1]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport, for example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[2]:** The value SHOULD be normalized to lowercase. + +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries (e.g. proxies) if it's available. -**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. -**[3]:** If using a port other than the default port for this DBMS and if `server.address` is set. +**[5]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[4]:** When observed from the client side, this SHOULD represent the immediate server peer address. +**[6]:** When observed from the client side, this SHOULD represent the immediate server peer address. When observed from the server side, this SHOULD represent the physical server address. -**[5]:** When observed from the client side, this SHOULD represent the immediate server peer port. +**[7]:** When observed from the client side, this SHOULD represent the immediate server peer port. When observed from the server side, this SHOULD represent the physical server port. **Additional attribute requirements:** At least one of the following sets of attributes is required: diff --git a/docs/general/attributes.md b/docs/general/attributes.md index 99fe0da717..e8160cfdb1 100644 --- a/docs/general/attributes.md +++ b/docs/general/attributes.md @@ -233,12 +233,22 @@ if they do not cause breaking changes to HTTP semantic conventions. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `network.transport` | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. 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. | `tcp`; `udp` | Recommended | -| `network.type` | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| `network.protocol.name` | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| `network.protocol.version` | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | +| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended | +| `network.type` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | +| `network.protocol.name` | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `amqp`; `http`; `mqtt` | Recommended | +| `network.protocol.version` | string | Version of the protocol specified in `network.protocol.name`. [4] | `3.1.1` | Recommended | -**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[1]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport, for example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[2]:** The value SHOULD be normalized to lowercase. + +**[3]:** The value SHOULD be normalized to lowercase. + +**[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. `network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index e488fd5f60..f4fa7a8fc9 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -80,10 +80,10 @@ 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 | `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | | `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [5] | `example.com` | Opt-In | -| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [6] | `80`; `8080`; `443` | Opt-In | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com` | Opt-In | +| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [7] | `80`; `8080`; `443` | Opt-In | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. @@ -120,9 +120,11 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[4]:** The value SHOULD be normalized to lowercase. -**[5]:** Determined by using the first of the following that applies +**[5]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[6]:** Determined by using the first of the following that applies - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. @@ -132,7 +134,7 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. -**[6]:** Determined by using the first of the following that applies +**[7]:** Determined by using the first of the following that applies - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) @@ -250,10 +252,10 @@ This metric is optional. | `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | | `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [5] | `example.com` | Opt-In | -| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [6] | `80`; `8080`; `443` | Opt-In | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com` | Opt-In | +| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [7] | `80`; `8080`; `443` | Opt-In | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. @@ -290,9 +292,11 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[4]:** The value SHOULD be normalized to lowercase. -**[5]:** Determined by using the first of the following that applies +**[5]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[6]:** Determined by using the first of the following that applies - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. @@ -302,7 +306,7 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. -**[6]:** Determined by using the first of the following that applies +**[7]:** Determined by using the first of the following that applies - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) @@ -352,10 +356,10 @@ This metric is optional. | `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | | `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [5] | `example.com` | Opt-In | -| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [6] | `80`; `8080`; `443` | Opt-In | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com` | Opt-In | +| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [7] | `80`; `8080`; `443` | Opt-In | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. @@ -392,9 +396,11 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[4]:** The value SHOULD be normalized to lowercase. -**[5]:** Determined by using the first of the following that applies +**[5]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[6]:** Determined by using the first of the following that applies - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. @@ -404,7 +410,7 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. -**[6]:** Determined by using the first of the following that applies +**[7]:** Determined by using the first of the following that applies - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) @@ -459,10 +465,10 @@ 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 | `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | | `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `example.com` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [4] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [6] | `80`; `8080`; `443` | Conditionally Required: [7] | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Required | **[1]:** If the request fails with an error before response status code was sent or received, @@ -496,9 +502,11 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[3]:** The value SHOULD be normalized to lowercase. -**[4]:** Determined by using the first of the following that applies +**[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[5]:** Determined by using the first of the following that applies - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form @@ -506,9 +514,9 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[5]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. +**[6]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. -**[6]:** If not default (`80` for `http` scheme, `443` for `https`). +**[7]:** If not default (`80` for `http` scheme, `443` for `https`). `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. @@ -552,10 +560,10 @@ This metric is optional. | `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | | `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `example.com` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [4] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [6] | `80`; `8080`; `443` | Conditionally Required: [7] | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Required | **[1]:** If the request fails with an error before response status code was sent or received, @@ -589,9 +597,11 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[3]:** The value SHOULD be normalized to lowercase. -**[4]:** Determined by using the first of the following that applies +**[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[5]:** Determined by using the first of the following that applies - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form @@ -599,9 +609,9 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[5]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. +**[6]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. -**[6]:** If not default (`80` for `http` scheme, `443` for `https`). +**[7]:** If not default (`80` for `http` scheme, `443` for `https`). `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. @@ -645,10 +655,10 @@ This metric is optional. | `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | | `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `example.com` | Required | -| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [4] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [6] | `80`; `8080`; `443` | Conditionally Required: [7] | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Required | **[1]:** If the request fails with an error before response status code was sent or received, @@ -682,9 +692,11 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[3]:** The value SHOULD be normalized to lowercase. -**[4]:** Determined by using the first of the following that applies +**[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[5]:** Determined by using the first of the following that applies - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form @@ -692,9 +704,9 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[5]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. +**[6]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. -**[6]:** If not default (`80` for `http` scheme, `443` for `https`). +**[7]:** If not default (`80` for `http` scheme, `443` for `https`). `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. diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 68a8a0cd50..929b81c027 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -123,10 +123,10 @@ sections below. | `http.response.header.` | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [3] | `http.response.header.content_type=["application/json"]`; `http.response.header.my_custom_header=["abc", "def"]` | Opt-In | | `error.type` | string | Describes a class of error the operation ended with. [4] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | | `http.request.method` | string | HTTP request method. [5] | `GET`; `POST`; `HEAD` | Required | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `spdy` | Recommended: if not default (`http`). | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [6] | `1.0`; `1.1`; `2`; `3` | Recommended | -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). 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. | `tcp`; `udp` | Conditionally Required: [7] | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [6] | `http`; `spdy` | Recommended: if not default (`http`). | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [7] | `1.0`; `1.1`; `2`; `3` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [8] | `tcp`; `udp` | Conditionally Required: [9] | +| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [10] | `ipv4`; `ipv6` | Recommended | | `user_agent.original` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended | **[1]:** If and only if it's different than `http.request.method`. @@ -170,9 +170,19 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. -**[6]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[6]:** The value SHOULD be normalized to lowercase. -**[7]:** If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`). +**[7]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[8]:** The value SHOULD be normalized to lowercase. + +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. + +**[9]:** If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`). + +**[10]:** The value SHOULD be normalized to lowercase. Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 90f58da2fb..b1505e49d7 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -229,14 +229,14 @@ The following operations related to messages are defined for these semantic conv | `messaging.message.conversation_id` | string | The [conversation ID](#conversations) identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended: [12] | | `messaging.message.envelope.size` | int | The size of the message body and metadata in bytes. [13] | `2738` | Recommended: [14] | | `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [15] | -| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [16] | `3.1.1` | Recommended | -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). 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. | `tcp`; `udp` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [17] | `example.com` | Conditionally Required: If available. | -| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [18] | `10.5.3.2` | Recommended: If different than `server.address`. | -| [`server.socket.domain`](../general/attributes.md) | string | Immediate server peer's domain name if available without reverse DNS lookup [19] | `proxy.example.com` | Recommended: [20] | -| [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [21] | `16456` | Recommended: If different than `server.port`. | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [16] | `amqp`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [17] | `3.1.1` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [18] | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [19] | `ipv4`; `ipv6` | Recommended | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [20] | `example.com` | Conditionally Required: If available. | +| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [21] | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`server.socket.domain`](../general/attributes.md) | string | Immediate server peer's domain name if available without reverse DNS lookup [22] | `proxy.example.com` | Recommended: [23] | +| [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [24] | `16456` | Recommended: If different than `server.port`. | **[1]:** If a custom value is used, it MUST be of low cardinality. @@ -271,18 +271,28 @@ size should be used. **[15]:** Only for spans that represent an operation on a single message. -**[16]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[16]:** The value SHOULD be normalized to lowercase. -**[17]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. +**[17]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[18]:** When observed from the client side, this SHOULD represent the immediate server peer address. +**[18]:** 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. + +**[19]:** The value SHOULD be normalized to lowercase. + +**[20]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. + +**[21]:** When observed from the client side, this SHOULD represent the immediate server peer address. When observed from the server side, this SHOULD represent the physical server address. -**[19]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. +**[22]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. -**[20]:** If different than `server.address` and if `server.socket.address` is set. +**[23]:** If different than `server.address` and if `server.socket.address` is set. -**[21]:** When observed from the client side, this SHOULD represent the immediate server peer port. +**[24]:** When observed from the client side, this SHOULD represent the immediate server peer port. When observed from the server side, this SHOULD represent the physical server port. `messaging.operation` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index 44021f7d01..ac07909f79 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -220,22 +220,30 @@ measurements. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). 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. | `tcp`; `udp` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`rpc.method`](rpc-spans.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [1] | `exampleMethod` | Recommended | -| [`rpc.service`](rpc-spans.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [2] | `myservice.EchoService` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | +| [`rpc.method`](rpc-spans.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [3] | `exampleMethod` | Recommended | +| [`rpc.service`](rpc-spans.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [4] | `myservice.EchoService` | Recommended | | [`rpc.system`](rpc-spans.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [3] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number [4] | `80`; `8080`; `443` | Recommended | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [5] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number [6] | `80`; `8080`; `443` | Recommended | -**[1]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). +**[1]:** The value SHOULD be normalized to lowercase. -**[2]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). +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. -**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +**[2]:** The value SHOULD be normalized to lowercase. + +**[3]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +**[4]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). + +**[5]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries (e.g. proxies) if it's available. -**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. `network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 9a9ae62cc7..d45cf2c6ea 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -88,28 +88,36 @@ Examples of span names: | `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | | `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended | | `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended | -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). 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. | `tcp`; `udp` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../general/attributes.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | -| [`server.port`](../general/attributes.md) | int | Server port number [4] | `80`; `8080`; `443` | Conditionally Required: See below | -| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [5] | `10.5.3.2` | See below | -| [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [6] | `16456` | Recommended: [7] | +| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | Recommended | +| [`server.address`](../general/attributes.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [5] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Server port number [6] | `80`; `8080`; `443` | Conditionally Required: See below | +| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [7] | `10.5.3.2` | See below | +| [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [8] | `16456` | Recommended: [9] | **[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). **[2]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). -**[3]:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. +**[3]:** The value SHOULD be normalized to lowercase. -**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +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. -**[5]:** When observed from the client side, this SHOULD represent the immediate server peer address. +**[4]:** The value SHOULD be normalized to lowercase. + +**[5]:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. + +**[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. + +**[7]:** When observed from the client side, this SHOULD represent the immediate server peer address. When observed from the server side, this SHOULD represent the physical server address. -**[6]:** When observed from the client side, this SHOULD represent the immediate server peer port. +**[8]:** When observed from the client side, this SHOULD represent the immediate server peer port. When observed from the server side, this SHOULD represent the physical server port. -**[7]:** If different than `server.port` and if `server.socket.address` is set. +**[9]:** If different than `server.port` and if `server.socket.address` is set. **Additional attribute requirements:** At least one of the following sets of attributes is required: @@ -165,8 +173,8 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service | [`client.port`](../general/attributes.md) | int | Client port number. [2] | `65123` | Recommended | | [`client.socket.address`](../general/attributes.md) | string | Client address of the socket connection - IP address or Unix domain socket name. [3] | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | | [`client.socket.port`](../general/attributes.md) | int | Client port number of the socket connection. [4] | `35555` | Recommended: If different than `client.port`. | -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). 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. | `tcp`; `udp` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [5] | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [6] | `ipv4`; `ipv6` | Recommended | **[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries (e.g. proxies) if it's available. @@ -177,6 +185,14 @@ When observed from the client side, this SHOULD represent the physical client ad **[4]:** When observed from the server side, this SHOULD represent the immediate client peer port. When observed from the client side, this SHOULD represent the physical client port. + +**[5]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport, for example +different processes could be listening on TCP port 12345 and UDP port 12345. + +**[6]:** The value SHOULD be normalized to lowercase. ### Events diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 8fa2bfa16f..745c9c25a0 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -637,10 +637,16 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). 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. | `tcp`; `udp` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended | | `system.device` | string | The device identifier | `(identifier)` | Recommended | | `system.network.state` | string | A stateless protocol MUST NOT set this attribute | `close_wait` | Recommended | +**[1]:** The value SHOULD be normalized to lowercase. + +Consider always setting the transport when setting a port number, since +a port number is ambiguous without knowing the transport, for example +different processes could be listening on TCP port 12345 and UDP port 12345. + `network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. | Value | Description | diff --git a/model/network.yaml b/model/network.yaml index 28074ba84d..2b969ea36e 100644 --- a/model/network.yaml +++ b/model/network.yaml @@ -22,9 +22,11 @@ groups: value: 'unix' brief: "Unix domain socket" brief: > - [OSI Transport Layer](https://osi-model.com/transport-layer/) or - [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). + [OSI transport layer](https://osi-model.com/transport-layer/) or + [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). + note: | The value SHOULD be normalized to lowercase. + Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport, for example different processes could be listening on TCP port 12345 and UDP port 12345. @@ -39,19 +41,17 @@ groups: - id: ipv6 value: 'ipv6' brief: "IPv6" - brief: > - [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. - The value SHOULD be normalized to lowercase. + brief: '[OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent.' + note: The value SHOULD be normalized to lowercase. examples: ['ipv4', 'ipv6'] - id: protocol.name type: string - brief: > - [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. - The value SHOULD be normalized to lowercase. + brief: '[OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent.' + note: The value SHOULD be normalized to lowercase. examples: ['amqp', 'http', 'mqtt'] - id: protocol.version type: string - brief: 'Version of the application layer protocol used. See note below.' + brief: Version of the protocol specified in `network.protocol.name`. examples: '3.1.1' note: > `network.protocol.version` refers to the version of the protocol used and might be From 590aff7ffc42d77c7c6feef76fe134976fb64c29 Mon Sep 17 00:00:00 2001 From: Chris Mark Date: Mon, 2 Oct 2023 18:00:05 +0100 Subject: [PATCH 3/4] Document the difference between host and system metrics (#324) Signed-off-by: ChrsMark Co-authored-by: Joao Grassi Co-authored-by: Joao Grassi Co-authored-by: Josh Suereth --- docs/resource/host.md | 3 +++ docs/system/system-metrics.md | 6 ++++++ 2 files changed, 9 insertions(+) diff --git a/docs/resource/host.md b/docs/resource/host.md index 150755dc19..7469f8f40f 100644 --- a/docs/resource/host.md +++ b/docs/resource/host.md @@ -6,6 +6,9 @@ **Description:** A host is defined as a computing instance. For example, physical servers, virtual machines, switches or disk array. +The `host.*` namespace SHOULD be exclusively used to capture resource attributes. +To report host metrics, the `system.*` namespace SHOULD be used. + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 745c9c25a0..a06d5b9664 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -11,6 +11,12 @@ metrics in OpenTelemetry. Consider the [general metric semantic conventions](/docs/general/metrics.md#general-metric-semantic-conventions) when creating instruments not explicitly defined in the specification. +The `system.*` namespace SHOULD be exclusively used to report hosts' metrics. +The `system.*` namespace SHOULD only be used when the metrics are collected from within the target system. (physical servers, virtual machines etc). +Metrics collected from technology-specific, well-defined APIs (e.g. Kubelet's API or container runtimes) +should be reported under their respective namespace (e.g. k8s.*, container.*). +Resource attributes related to a host, SHOULD be reported under the `host.*` namespace. + From 2c065be5e66bbaf00898b1a740bb3b3e47b8acc6 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 3 Oct 2023 00:37:56 -0700 Subject: [PATCH 4/4] Editorial: Update build-tools to 0.22.0 and sort attributes alphabetically in all semconv (#359) Co-authored-by: Armin Ruech --- Makefile | 2 +- docs/cloudevents/cloudevents-spans.md | 2 +- docs/database/cassandra.md | 8 +-- docs/database/cosmosdb.md | 18 +++---- docs/database/database-spans.md | 10 ++-- docs/database/dynamodb.md | 18 +++---- docs/database/elasticsearch.md | 10 ++-- docs/database/graphql.md | 2 +- docs/faas/faas-spans.md | 6 +-- docs/general/attributes.md | 68 ++++++++++++------------ docs/general/events.md | 2 +- docs/general/logs.md | 2 +- docs/http/http-metrics.md | 48 ++++++++--------- docs/http/http-spans.md | 60 ++++++++++----------- docs/jvm/jvm-metrics.md | 18 +++---- docs/messaging/kafka.md | 2 +- docs/messaging/messaging-spans.md | 56 +++++++++---------- docs/messaging/rocketmq.md | 30 +++++------ docs/object-stores/s3.md | 44 +++++++-------- docs/resource/README.md | 10 ++-- docs/resource/browser.md | 10 ++-- docs/resource/cloud-provider/aws/ecs.md | 2 +- docs/resource/cloud-provider/aws/logs.md | 10 ++-- docs/resource/cloud-provider/gcp/gce.md | 2 +- docs/resource/cloud-provider/heroku.md | 4 +- docs/resource/cloud.md | 46 ++++++++-------- docs/resource/container.md | 22 ++++---- docs/resource/device.md | 12 ++--- docs/resource/faas.md | 58 ++++++++++---------- docs/resource/host.md | 12 ++--- docs/resource/k8s.md | 14 ++--- docs/resource/os.md | 4 +- docs/resource/process.md | 12 ++--- docs/resource/webengine.md | 2 +- docs/rpc/grpc.md | 2 +- docs/rpc/json-rpc.md | 4 +- docs/rpc/rpc-spans.md | 24 ++++----- docs/url/url.md | 4 +- internal/tools/schema_check.sh | 10 ++-- model/README.md | 6 +-- 40 files changed, 339 insertions(+), 337 deletions(-) diff --git a/Makefile b/Makefile index a87243775e..c6d956424b 100644 --- a/Makefile +++ b/Makefile @@ -8,7 +8,7 @@ MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY) # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates # Keep links in model/README.md and .vscode/settings.json in sync! -SEMCONVGEN_VERSION=0.21.0 +SEMCONVGEN_VERSION=0.22.0 # TODO: add `yamllint` step to `all` after making sure it works on Mac. .PHONY: all diff --git a/docs/cloudevents/cloudevents-spans.md b/docs/cloudevents/cloudevents-spans.md index d13a8d5300..a985cae034 100644 --- a/docs/cloudevents/cloudevents-spans.md +++ b/docs/cloudevents/cloudevents-spans.md @@ -205,8 +205,8 @@ The following attributes are applicable to creation and processing Spans. | `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event. | `123e4567-e89b-12d3-a456-426614174000`; `0001` | Required | | `cloudevents.event_source` | string | The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | Required | | `cloudevents.event_spec_version` | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses. | `1.0` | Recommended | -| `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | Recommended | | `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | Recommended | +| `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | Recommended | diff --git a/docs/database/cassandra.md b/docs/database/cassandra.md index fc420a9f5d..41380ebedc 100644 --- a/docs/database/cassandra.md +++ b/docs/database/cassandra.md @@ -17,13 +17,13 @@ described on this page. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `db.cassandra.page_size` | int | The fetch size used for paging, i.e. how many rows will be returned at once. | `5000` | Recommended | | `db.cassandra.consistency_level` | string | The consistency level of the query. Based on consistency values from [CQL](https://docs.datastax.com/en/cassandra-oss/3.0/cassandra/dml/dmlConfigConsistency.html). | `all` | Recommended | -| `db.cassandra.table` | string | The name of the primary table that the operation is acting upon, including the keyspace name (if applicable). [1] | `mytable` | Recommended | +| `db.cassandra.coordinator.dc` | string | The data center of the coordinating node for a query. | `us-west-2` | Recommended | +| `db.cassandra.coordinator.id` | string | The ID of the coordinating node for a query. | `be13faa2-8574-4d71-926d-27f16cf8a7af` | Recommended | | `db.cassandra.idempotence` | boolean | Whether or not the query is idempotent. | | Recommended | +| `db.cassandra.page_size` | int | The fetch size used for paging, i.e. how many rows will be returned at once. | `5000` | Recommended | | `db.cassandra.speculative_execution_count` | int | The number of times a query was speculatively executed. Not set or `0` if the query was not executed speculatively. | `0`; `2` | Recommended | -| `db.cassandra.coordinator.id` | string | The ID of the coordinating node for a query. | `be13faa2-8574-4d71-926d-27f16cf8a7af` | Recommended | -| `db.cassandra.coordinator.dc` | string | The data center of the coordinating node for a query. | `us-west-2` | Recommended | +| `db.cassandra.table` | string | The name of the primary table that the operation is acting upon, including the keyspace name (if applicable). [1] | `mytable` | Recommended | | [`db.name`](database-spans.md) | string | The keyspace name in Cassandra. [2] | `mykeyspace` | Conditionally Required: If applicable. | **[1]:** This mirrors the db.sql.table attribute but references cassandra rather than sql. It is not recommended to attempt any client-side parsing of `db.statement` just to get this property, but it should be set if it is provided by the library being instrumented. If the operation is acting upon an anonymous table, or more than one table, this value MUST NOT be set. diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 83425d15bb..c5b2a1a836 100644 --- a/docs/database/cosmosdb.md +++ b/docs/database/cosmosdb.md @@ -21,13 +21,13 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `db.cosmosdb.client_id` | string | Unique Cosmos client instance id. | `3ba4827d-4422-483f-b59f-85b74211c11d` | Recommended | -| `db.cosmosdb.operation_type` | string | CosmosDB Operation Type. | `Invalid` | Conditionally Required: [1] | | `db.cosmosdb.connection_mode` | string | Cosmos client connection mode. | `gateway` | Conditionally Required: if not `direct` (or pick gw as default) | | `db.cosmosdb.container` | string | Cosmos DB container name. | `anystring` | Conditionally Required: if available | +| `db.cosmosdb.operation_type` | string | CosmosDB Operation Type. | `Invalid` | Conditionally Required: [1] | +| `db.cosmosdb.request_charge` | double | RU consumed for that operation | `46.18`; `1.0` | Conditionally Required: when available | | `db.cosmosdb.request_content_length` | int | Request payload size in bytes | | Recommended | | `db.cosmosdb.status_code` | int | Cosmos DB status code. | `200`; `201` | Conditionally Required: if response was received | | `db.cosmosdb.sub_status_code` | int | Cosmos DB sub status code. | `1000`; `1002` | Conditionally Required: [2] | -| `db.cosmosdb.request_charge` | double | RU consumed for that operation | `46.18`; `1.0` | Conditionally Required: when available | | `user_agent.original` | string | Full user-agent string is generated by Cosmos DB SDK [3] | `cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|` | Recommended | **[1]:** when performing one of the operations in this list @@ -38,6 +38,13 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it). Default value is "NS". +`db.cosmosdb.connection_mode` MUST be one of the following: + +| Value | Description | +|---|---| +| `gateway` | Gateway (HTTP) connections mode | +| `direct` | Direct connection. | + `db.cosmosdb.operation_type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. | Value | Description | @@ -57,13 +64,6 @@ Cosmos DB instrumentation includes call-level (public API) surface spans and net | `Batch` | batch | | `QueryPlan` | query_plan | | `ExecuteJavaScript` | execute_javascript | - -`db.cosmosdb.connection_mode` MUST be one of the following: - -| Value | Description | -|---|---| -| `gateway` | Gateway (HTTP) connections mode | -| `direct` | Direct connection. | In addition to Cosmos DB attributes, all spans include diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 544798808e..05314a27fd 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -64,8 +64,8 @@ Some database systems may allow a connection to switch to a different `db.user`, | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Required | | `db.connection_string` | string | The connection string used to connect to the database. It is recommended to remove embedded credentials. | `Server=(localdb)\v11.0;Integrated Security=true;` | Recommended | +| `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Required | | `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended | | [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended | | [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | @@ -185,14 +185,14 @@ Usually only one `db.name` will be used per connection though. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `db.name` | string | This attribute is used to report the name of the database being accessed. For commands that switch the database, this should be set to the target database (even if the command fails). [1] | `customers`; `main` | Conditionally Required: If applicable. | -| `db.statement` | string | The database statement being executed. | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | Recommended: [2] | -| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. [3] | `findAndModify`; `HMSET`; `SELECT` | Conditionally Required: If `db.statement` is not applicable. | +| `db.operation` | string | The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations) such as `findAndModify`, or the SQL keyword. [2] | `findAndModify`; `HMSET`; `SELECT` | Conditionally Required: If `db.statement` is not applicable. | +| `db.statement` | string | The database statement being executed. | `SELECT * FROM wuser_table`; `SET mykey "WuValue"` | Recommended: [3] | **[1]:** In some SQL databases, the database name to be used is called "schema name". In case there are multiple layers that could be considered for database name (e.g. Oracle instance name and schema name), the database name to be used is the more specific layer (e.g. Oracle schema name). -**[2]:** Should be collected by default only if there is sanitization that excludes sensitive information. +**[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]:** 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 diff --git a/docs/database/dynamodb.md b/docs/database/dynamodb.md index f37e918366..13a6ec9ce1 100644 --- a/docs/database/dynamodb.md +++ b/docs/database/dynamodb.md @@ -46,10 +46,10 @@ These attributes are filled in for all DynamoDB request types. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `aws.dynamodb.global_secondary_indexes` | string[] | The JSON-serialized value of each item of the `GlobalSecondaryIndexes` request field | `[{ "IndexName": "string", "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" }, "ProvisionedThroughput": { "ReadCapacityUnits": number, "WriteCapacityUnits": number } }]` | Recommended | -| `aws.dynamodb.local_secondary_indexes` | string[] | The JSON-serialized value of each item of the `LocalSecondaryIndexes` request field. | `[{ "IndexArn": "string", "IndexName": "string", "IndexSizeBytes": number, "ItemCount": number, "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" } }]` | Recommended | | `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | +| `aws.dynamodb.global_secondary_indexes` | string[] | The JSON-serialized value of each item of the `GlobalSecondaryIndexes` request field | `[{ "IndexName": "string", "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" }, "ProvisionedThroughput": { "ReadCapacityUnits": number, "WriteCapacityUnits": number } }]` | Recommended | | `aws.dynamodb.item_collection_metrics` | string | The JSON-serialized value of the `ItemCollectionMetrics` response field. | `{ "string" : [ { "ItemCollectionKey": { "string" : { "B": blob, "BOOL": boolean, "BS": [ blob ], "L": [ "AttributeValue" ], "M": { "string" : "AttributeValue" }, "N": "string", "NS": [ "string" ], "NULL": boolean, "S": "string", "SS": [ "string" ] } }, "SizeEstimateRangeGB": [ number ] } ] }` | Recommended | +| `aws.dynamodb.local_secondary_indexes` | string[] | The JSON-serialized value of each item of the `LocalSecondaryIndexes` request field. | `[{ "IndexArn": "string", "IndexName": "string", "IndexSizeBytes": number, "ItemCount": number, "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" } }]` | Recommended | | `aws.dynamodb.provisioned_read_capacity` | double | The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter. | `1.0`; `2.0` | Recommended | | `aws.dynamodb.provisioned_write_capacity` | double | The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter. | `1.0`; `2.0` | Recommended | | `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | @@ -98,8 +98,8 @@ These attributes are filled in for all DynamoDB request types. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `aws.dynamodb.exclusive_start_table` | string | The value of the `ExclusiveStartTableName` request parameter. | `Users`; `CatsTable` | Recommended | -| `aws.dynamodb.table_count` | int | The the number of items in the `TableNames` response parameter. | `20` | Recommended | | `aws.dynamodb.limit` | int | The value of the `Limit` request parameter. | `10` | Recommended | +| `aws.dynamodb.table_count` | int | The the number of items in the `TableNames` response parameter. | `20` | Recommended | ## DynamoDB.PutItem @@ -117,13 +117,13 @@ These attributes are filled in for all DynamoDB request types. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `aws.dynamodb.scan_forward` | boolean | The value of the `ScanIndexForward` request parameter. | | Recommended | | `aws.dynamodb.attributes_to_get` | string[] | The value of the `AttributesToGet` request parameter. | `[lives, id]` | Recommended | | `aws.dynamodb.consistent_read` | boolean | The value of the `ConsistentRead` request parameter. | | Recommended | | `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | | `aws.dynamodb.index_name` | string | The value of the `IndexName` request parameter. | `name_to_group` | Recommended | | `aws.dynamodb.limit` | int | The value of the `Limit` request parameter. | `10` | Recommended | | `aws.dynamodb.projection` | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | Recommended | +| `aws.dynamodb.scan_forward` | boolean | The value of the `ScanIndexForward` request parameter. | | Recommended | | `aws.dynamodb.select` | string | The value of the `Select` request parameter. | `ALL_ATTRIBUTES`; `COUNT` | Recommended | | `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | @@ -133,18 +133,18 @@ These attributes are filled in for all DynamoDB request types. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `aws.dynamodb.segment` | int | The value of the `Segment` request parameter. | `10` | Recommended | -| `aws.dynamodb.total_segments` | int | The value of the `TotalSegments` request parameter. | `100` | Recommended | -| `aws.dynamodb.count` | int | The value of the `Count` response parameter. | `10` | Recommended | -| `aws.dynamodb.scanned_count` | int | The value of the `ScannedCount` response parameter. | `50` | Recommended | | `aws.dynamodb.attributes_to_get` | string[] | The value of the `AttributesToGet` request parameter. | `[lives, id]` | Recommended | | `aws.dynamodb.consistent_read` | boolean | The value of the `ConsistentRead` request parameter. | | Recommended | | `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | +| `aws.dynamodb.count` | int | The value of the `Count` response parameter. | `10` | Recommended | | `aws.dynamodb.index_name` | string | The value of the `IndexName` request parameter. | `name_to_group` | Recommended | | `aws.dynamodb.limit` | int | The value of the `Limit` request parameter. | `10` | Recommended | | `aws.dynamodb.projection` | string | The value of the `ProjectionExpression` request parameter. | `Title`; `Title, Price, Color`; `Title, Description, RelatedItems, ProductReviews` | Recommended | +| `aws.dynamodb.scanned_count` | int | The value of the `ScannedCount` response parameter. | `50` | Recommended | +| `aws.dynamodb.segment` | int | The value of the `Segment` request parameter. | `10` | Recommended | | `aws.dynamodb.select` | string | The value of the `Select` request parameter. | `ALL_ATTRIBUTES`; `COUNT` | Recommended | | `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | +| `aws.dynamodb.total_segments` | int | The value of the `TotalSegments` request parameter. | `100` | Recommended | ## DynamoDB.UpdateItem @@ -163,8 +163,8 @@ These attributes are filled in for all DynamoDB request types. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `aws.dynamodb.attribute_definitions` | string[] | The JSON-serialized value of each item in the `AttributeDefinitions` request field. | `[{ "AttributeName": "string", "AttributeType": "string" }]` | Recommended | -| `aws.dynamodb.global_secondary_index_updates` | string[] | The JSON-serialized value of each item in the the `GlobalSecondaryIndexUpdates` request field. | `[{ "Create": { "IndexName": "string", "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" }, "ProvisionedThroughput": { "ReadCapacityUnits": number, "WriteCapacityUnits": number } }]` | Recommended | | `aws.dynamodb.consumed_capacity` | string[] | The JSON-serialized value of each item in the `ConsumedCapacity` response field. | `[{ "CapacityUnits": number, "GlobalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "LocalSecondaryIndexes": { "string" : { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number } }, "ReadCapacityUnits": number, "Table": { "CapacityUnits": number, "ReadCapacityUnits": number, "WriteCapacityUnits": number }, "TableName": "string", "WriteCapacityUnits": number }]` | Recommended | +| `aws.dynamodb.global_secondary_index_updates` | string[] | The JSON-serialized value of each item in the the `GlobalSecondaryIndexUpdates` request field. | `[{ "Create": { "IndexName": "string", "KeySchema": [ { "AttributeName": "string", "KeyType": "string" } ], "Projection": { "NonKeyAttributes": [ "string" ], "ProjectionType": "string" }, "ProvisionedThroughput": { "ReadCapacityUnits": number, "WriteCapacityUnits": number } }]` | Recommended | | `aws.dynamodb.provisioned_read_capacity` | double | The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter. | `1.0`; `2.0` | Recommended | | `aws.dynamodb.provisioned_write_capacity` | double | The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter. | `1.0`; `2.0` | Recommended | | `aws.dynamodb.table_names` | string[] | A single-element array with the value of the TableName request parameter. | `[Users]` | Recommended | diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 8dd4a5fc4d..cd0c069fd7 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -32,9 +32,9 @@ If the endpoint id is not available, the span name SHOULD be the `http.request.m | [`db.operation`](database-spans.md) | string | The endpoint identifier for the request. [4] | `search`; `ml.close_job`; `cat.aliases` | Required | | [`db.statement`](database-spans.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | Recommended: [5] | | `http.request.method` | string | HTTP request method. [6] | `GET`; `POST`; `HEAD` | Required | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [7] | `example.com` | See below | -| [`server.port`](../general/attributes.md) | int | Server port number [8] | `80`; `8080`; `443` | Recommended | -| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [9] | `https://localhost:9200/index/_search?q=user.id:kimchy` | Required | +| [`server.address`](../general/attributes.md) | string | Name of the database host. [7] | `example.com` | Conditionally Required: See alternative attributes below. | +| [`server.port`](../general/attributes.md) | int | Server port number [8] | `80`; `8080`; `443` | Conditionally Required: [9] | +| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [10] | `https://localhost:9200/index/_search?q=user.id:kimchy` | Required | **[1]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. @@ -66,7 +66,9 @@ the server address behind any intermediaries (e.g. proxies) if it's available. **[8]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. -**[9]:** 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. +**[9]:** If using a port other than the default port for this DBMS and if `server.address` is set. + +**[10]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. `url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password should be redacted and attribute's value should be `https://REDACTED:REDACTED@www.example.com/`. `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. diff --git a/docs/database/graphql.md b/docs/database/graphql.md index 8cc6409866..7e3d6a8a06 100644 --- a/docs/database/graphql.md +++ b/docs/database/graphql.md @@ -17,9 +17,9 @@ MAY be used as span name. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| `graphql.document` | string | The GraphQL document being executed. [1] | `query findBookById { bookById(id: ?) { name } }` | Recommended | | `graphql.operation.name` | string | The name of the operation being executed. | `findBookById` | Recommended | | `graphql.operation.type` | string | The type of the operation being executed. | `query`; `mutation`; `subscription` | Recommended | -| `graphql.document` | string | The GraphQL document being executed. [1] | `query findBookById { bookById(id: ?) { name } }` | Recommended | **[1]:** The value may be sanitized to exclude sensitive information. diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md index 8a90312273..e1e7066b32 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -41,8 +41,8 @@ If Spans following this convention are produced, a Resource of type `faas` MUST | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.invocation_id` | string | The invocation ID of the current function invocation. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | Recommended | | [`cloud.resource_id`](../resource/cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [1] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | Recommended | +| `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 | **[1]:** On some cloud providers, it may not be possible to determine the full ID at startup, @@ -200,9 +200,9 @@ FaaS instrumentations that produce `faas` spans with trigger `datasource`, SHOUL | 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.name` | string | The document name/table subjected to the operation. For example, in Cloud Storage or S3 is the name of the file, and in Cosmos DB the table name. | `myFile.txt`; `myTableName` | Recommended | `faas.document.operation` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. @@ -232,8 +232,8 @@ A function is scheduled to be executed regularly. The following additional attri | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.time` | string | A string containing the function invocation time in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | Recommended | | `faas.cron` | string | A string containing the schedule period as [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). | `0/5 * * * ? *` | Recommended | +| `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 | ### Other diff --git a/docs/general/attributes.md b/docs/general/attributes.md index e8160cfdb1..6111990606 100644 --- a/docs/general/attributes.md +++ b/docs/general/attributes.md @@ -68,8 +68,8 @@ if they do not cause breaking changes to HTTP semantic conventions. |---|---|---|---|---| | `server.address` | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `example.com` | Recommended | | `server.port` | int | Server port number [2] | `80`; `8080`; `443` | Recommended | -| `server.socket.domain` | string | Immediate server peer's domain name if available without reverse DNS lookup [3] | `proxy.example.com` | Recommended: If different than `server.address`. | -| `server.socket.address` | string | Server address of the socket connection - IP address or Unix domain socket name. [4] | `10.5.3.2` | Recommended: If different than `server.address`. | +| `server.socket.address` | string | Server address of the socket connection - IP address or Unix domain socket name. [3] | `10.5.3.2` | Recommended: If different than `server.address`. | +| `server.socket.domain` | string | Immediate server peer's domain name if available without reverse DNS lookup [4] | `proxy.example.com` | Recommended: If different than `server.address`. | | `server.socket.port` | int | Server port number of the socket connection. [5] | `16456` | Recommended: If different than `server.port`. | **[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent @@ -77,11 +77,11 @@ the server address behind any intermediaries (e.g. proxies) if it's available. **[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. -**[3]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. - -**[4]:** When observed from the client side, this SHOULD represent the immediate server peer address. +**[3]:** When observed from the client side, this SHOULD represent the immediate server peer address. When observed from the server side, this SHOULD represent the physical server address. +**[4]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. + **[5]:** When observed from the client side, this SHOULD represent the immediate server peer port. When observed from the server side, this SHOULD represent the physical server port. @@ -200,8 +200,8 @@ This also covers unidirectional UDP flows and peer-to-peer communication where t | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `source.domain` | string | The domain name of the source system. [1] | `foo.example.com` | Recommended | | `source.address` | string | Source address, for example IP address or Unix socket name. | `10.5.3.2` | Recommended | +| `source.domain` | string | The domain name of the source system. [1] | `foo.example.com` | Recommended | | `source.port` | int | Source port number | `3389`; `2888` | Recommended | **[1]:** This value may be a host name, a fully qualified domain name, or another host naming format. @@ -214,8 +214,8 @@ Destination fields capture details about the receiver of a network exchange/pack | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `destination.domain` | string | The domain name of the destination system. [1] | `foo.example.com` | Recommended | | `destination.address` | string | Destination address, for example IP address or UNIX socket name. | `10.5.3.2` | Recommended | +| `destination.domain` | string | The domain name of the destination system. [1] | `foo.example.com` | Recommended | | `destination.port` | int | Destination port number | `3389`; `2888` | Recommended | **[1]:** This value may be a host name, a fully qualified domain name, or another host naming format. @@ -233,22 +233,22 @@ if they do not cause breaking changes to HTTP semantic conventions. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended | -| `network.type` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | -| `network.protocol.name` | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `amqp`; `http`; `mqtt` | Recommended | -| `network.protocol.version` | string | Version of the protocol specified in `network.protocol.name`. [4] | `3.1.1` | Recommended | +| `network.protocol.name` | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [1] | `amqp`; `http`; `mqtt` | Recommended | +| `network.protocol.version` | string | Version of the protocol specified in `network.protocol.name`. [2] | `3.1.1` | Recommended | +| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` | Recommended | +| `network.type` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. +**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[3]:** The value SHOULD be normalized to lowercase. + Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport, for example different processes could be listening on TCP port 12345 and UDP port 12345. -**[2]:** The value SHOULD be normalized to lowercase. - -**[3]:** The value SHOULD be normalized to lowercase. - -**[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[4]:** The value SHOULD be normalized to lowercase. `network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. @@ -272,22 +272,12 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `network.connection.type` | string | The internet connection type. | `wifi` | Recommended | -| `network.connection.subtype` | string | This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. | `LTE` | Recommended | -| `network.carrier.name` | string | The name of the mobile carrier. | `sprint` | Recommended | +| `network.carrier.icc` | string | The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. | `DE` | Recommended | | `network.carrier.mcc` | string | The mobile carrier country code. | `310` | Recommended | | `network.carrier.mnc` | string | The mobile carrier network code. | `001` | Recommended | -| `network.carrier.icc` | string | The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. | `DE` | Recommended | - -`network.connection.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. - -| Value | Description | -|---|---| -| `wifi` | wifi | -| `wired` | wired | -| `cell` | cell | -| `unavailable` | unavailable | -| `unknown` | unknown | +| `network.carrier.name` | string | The name of the mobile carrier. | `sprint` | Recommended | +| `network.connection.subtype` | string | This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. | `LTE` | Recommended | +| `network.connection.type` | string | The internet connection type. | `wifi` | Recommended | `network.connection.subtype` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. @@ -314,6 +304,16 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | `nr` | 5G NR (New Radio) | | `nrnsa` | 5G NRNSA (New Radio Non-Standalone) | | `lte_ca` | LTE CA | + +`network.connection.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `wifi` | wifi | +| `wired` | wired | +| `cell` | cell | +| `unavailable` | unavailable | +| `unknown` | unknown | For `Unix` and `pipe`, since the connection goes over the file system instead of being directly to a known peer, `server.address` is the only attribute that usually makes sense (see description of `server.address` below). @@ -389,9 +389,9 @@ a thread that started a span. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| `thread.daemon` | boolean | Whether the thread is daemon or not. | | Recommended | | `thread.id` | int | Current "managed" thread ID (as opposed to OS thread ID). | `42` | Recommended | | `thread.name` | string | Current thread name. | `main` | Recommended | -| `thread.daemon` | boolean | Whether the thread is daemon or not. | | Recommended | Examples of where `thread.id` and `thread.name` can be extracted from: @@ -416,11 +416,11 @@ about the span. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `code.function` | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `serveRequest` | Recommended | -| `code.namespace` | string | The "namespace" within which `code.function` is defined. Usually the qualified class or module name, such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit. | `com.example.MyHttpService` | Recommended | +| `code.column` | int | The column number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `16` | Recommended | | `code.filepath` | string | The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). | `/usr/local/MyApplication/content_root/app/index.php` | Recommended | +| `code.function` | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `serveRequest` | Recommended | | `code.lineno` | int | The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `42` | Recommended | -| `code.column` | int | The column number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `16` | Recommended | +| `code.namespace` | string | The "namespace" within which `code.function` is defined. Usually the qualified class or module name, such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit. | `com.example.MyHttpService` | Recommended | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/general/events.md b/docs/general/events.md index bb05d9a015..92747e77d9 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -43,8 +43,8 @@ that identify the class of Events but not the instance of the Event. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `event.name` | string | The name identifies the event. | `click`; `exception` | Required | | `event.domain` | string | The domain identifies the business context for the events. [1] | `browser` | Required | +| `event.name` | string | The name identifies the event. | `click`; `exception` | Required | **[1]:** Events across different domains may have same `event.name`, yet be unrelated events. diff --git a/docs/general/logs.md b/docs/general/logs.md index 0ccdbb7c73..555530f58a 100644 --- a/docs/general/logs.md +++ b/docs/general/logs.md @@ -60,8 +60,8 @@ As such, these should be recorded as Log Record attributes when applicable. They | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `log.file.name` | string | The basename of the file. | `audit.log` | Recommended | -| `log.file.path` | string | The full path to the file. | `/var/log/mysql/audit.log` | Opt-In | | `log.file.name_resolved` | string | The basename of the file, with symlinks resolved. | `uuid.log` | Opt-In | +| `log.file.path` | string | The full path to the file. | `/var/log/mysql/audit.log` | Opt-In | | `log.file.path_resolved` | string | The full path to the file, with symlinks resolved. | `/var/lib/docker/uuid.log` | Opt-In | diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index f4fa7a8fc9..c406fa9e9e 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -76,20 +76,17 @@ 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 | |---|---|---|---|---| -| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | -| `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required | +| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | +| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | +| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | | [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `3.1.1` | Recommended | | [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com` | Opt-In | | [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [7] | `80`; `8080`; `443` | Opt-In | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | -**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. -SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. - -**[2]:** If the request fails with an error before response status code was sent or received, +**[1]:** If the request fails with an error before response status code was sent or received, `error.type` SHOULD be set to exception type or a component-specific low cardinality error code. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), @@ -105,7 +102,7 @@ additional filters are applied. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[3]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). @@ -120,6 +117,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. +**[3]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. +SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. + **[4]:** The value SHOULD be normalized to lowercase. **[5]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. @@ -248,20 +248,17 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | -| `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required | +| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | +| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | +| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | | [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `3.1.1` | Recommended | | [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com` | Opt-In | | [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [7] | `80`; `8080`; `443` | Opt-In | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | -**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. -SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. - -**[2]:** If the request fails with an error before response status code was sent or received, +**[1]:** If the request fails with an error before response status code was sent or received, `error.type` SHOULD be set to exception type or a component-specific low cardinality error code. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), @@ -277,7 +274,7 @@ additional filters are applied. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[3]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). @@ -292,6 +289,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. +**[3]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. +SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. + **[4]:** The value SHOULD be normalized to lowercase. **[5]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. @@ -352,20 +352,17 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | -| `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required | +| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | +| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | +| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | | [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `3.1.1` | Recommended | | [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com` | Opt-In | | [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [7] | `80`; `8080`; `443` | Opt-In | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | -**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. -SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. - -**[2]:** If the request fails with an error before response status code was sent or received, +**[1]:** If the request fails with an error before response status code was sent or received, `error.type` SHOULD be set to exception type or a component-specific low cardinality error code. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), @@ -381,7 +378,7 @@ additional filters are applied. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[3]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). @@ -396,6 +393,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. +**[3]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. +SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. + **[4]:** The value SHOULD be normalized to lowercase. **[5]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 929b81c027..0548eaf01e 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -115,31 +115,21 @@ sections below. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| `http.request.method_original` | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | Conditionally Required: [1] | +| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | | `http.request.body.size` | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | -| `http.response.body.size` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | | `http.request.header.` | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [2] | `http.request.header.content_type=["application/json"]`; `http.request.header.x_forwarded_for=["1.2.3.4", "1.2.3.5"]` | Opt-In | -| `http.response.header.` | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [3] | `http.response.header.content_type=["application/json"]`; `http.response.header.my_custom_header=["abc", "def"]` | Opt-In | -| `error.type` | string | Describes a class of error the operation ended with. [4] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. | -| `http.request.method` | string | HTTP request method. [5] | `GET`; `POST`; `HEAD` | Required | +| `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required | +| `http.request.method_original` | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | Conditionally Required: [4] | +| `http.response.body.size` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | +| `http.response.header.` | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [5] | `http.response.header.content_type=["application/json"]`; `http.response.header.my_custom_header=["abc", "def"]` | Opt-In | +| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [6] | `http`; `spdy` | Recommended: if not default (`http`). | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [7] | `1.0`; `1.1`; `2`; `3` | Recommended | | [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [8] | `tcp`; `udp` | Conditionally Required: [9] | | [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [10] | `ipv4`; `ipv6` | Recommended | | `user_agent.original` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended | -**[1]:** If and only if it's different than `http.request.method`. - -**[2]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information. -The `User-Agent` header is already captured in the `user_agent.original` attribute. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. -The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. - -**[3]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. -Users MAY explicitly configure instrumentations to capture them even though it is not recommended. -The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. - -**[4]:** If the request fails with an error before response status code was sent or received, +**[1]:** If the request fails with an error before response status code was sent or received, `error.type` SHOULD be set to exception type or a component-specific low cardinality error code. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), @@ -155,7 +145,11 @@ additional filters are applied. If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. -**[5]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[2]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +The `User-Agent` header is already captured in the `user_agent.original` attribute. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. +The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. + +**[3]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). @@ -170,6 +164,12 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. +**[4]:** If and only if it's different than `http.request.method`. + +**[5]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +Users MAY explicitly configure instrumentations to capture them even though it is not recommended. +The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. + **[6]:** The value SHOULD be normalized to lowercase. **[7]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. @@ -375,11 +375,11 @@ For an HTTP server span, `SpanKind` MUST be `Server`. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| [`client.address`](../general/attributes.md) | string | Client address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [2] | `83.164.160.102` | Recommended | -| [`client.port`](../general/attributes.md) | int | The port of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) or a similar header). Otherwise, the immediate client peer port. [3] | `65123` | Recommended | -| [`client.socket.address`](../general/attributes.md) | string | Client address of the socket connection - IP address or Unix domain socket name. [4] | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | -| [`client.socket.port`](../general/attributes.md) | int | Client port number of the socket connection. [5] | `35555` | Recommended: If different than `client.port`. | +| [`client.address`](../general/attributes.md) | string | Client address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `83.164.160.102` | Recommended | +| [`client.port`](../general/attributes.md) | int | The port of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) or a similar header). Otherwise, the immediate client peer port. [2] | `65123` | Recommended | +| [`client.socket.address`](../general/attributes.md) | string | Client address of the socket connection - IP address or Unix domain socket name. [3] | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | +| [`client.socket.port`](../general/attributes.md) | int | Client port number of the socket connection. [4] | `35555` | Recommended: If different than `client.port`. | +| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [5] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | | [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com` | Recommended | | [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [7] | `80`; `8080`; `443` | Recommended: [8] | | [`server.socket.address`](../general/attributes.md) | string | Local socket address. Useful in case of a multi-IP host. [9] | `10.5.3.2` | Opt-In | @@ -388,19 +388,19 @@ For an HTTP server span, `SpanKind` MUST be `Server`. | [`url.query`](../url/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [12] | `q=OpenTelemetry` | Conditionally Required: If and only if one was received/sent. | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | -**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. -SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. - -**[2]:** The IP address of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded), [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For), or a similar header). Otherwise, the immediate client peer address. +**[1]:** The IP address of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded), [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For), or a similar header). Otherwise, the immediate client peer address. -**[3]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries (e.g. proxies) if it's available. +**[2]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries (e.g. proxies) if it's available. -**[4]:** When observed from the server side, this SHOULD represent the immediate client peer address. +**[3]:** When observed from the server side, this SHOULD represent the immediate client peer address. When observed from the client side, this SHOULD represent the physical client address. -**[5]:** When observed from the server side, this SHOULD represent the immediate client peer port. +**[4]:** When observed from the server side, this SHOULD represent the immediate client peer port. When observed from the client side, this SHOULD represent the physical client port. +**[5]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. +SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. + **[6]:** Determined by using the first of the following that applies - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only diff --git a/docs/jvm/jvm-metrics.md b/docs/jvm/jvm-metrics.md index 6272e494fe..efcf94ca6e 100644 --- a/docs/jvm/jvm-metrics.md +++ b/docs/jvm/jvm-metrics.md @@ -57,8 +57,8 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | | `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | +| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | **[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). @@ -84,8 +84,8 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | | `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | +| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | **[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). @@ -111,8 +111,8 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | | `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | +| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | **[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). @@ -138,8 +138,8 @@ This metric is obtained from [`MemoryPoolMXBean#getCollectionUsage()`](https://d | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | | `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | +| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | **[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). @@ -174,12 +174,12 @@ of `[]` (single bucket histogram capturing count, sum, min, max). | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `jvm.gc.name` | string | Name of the garbage collector. [1] | `G1 Young Generation`; `G1 Old Generation` | Recommended | -| `jvm.gc.action` | string | Name of the garbage collector action. [2] | `end of minor GC`; `end of major GC` | Recommended | +| `jvm.gc.action` | string | Name of the garbage collector action. [1] | `end of minor GC`; `end of major GC` | Recommended | +| `jvm.gc.name` | string | Name of the garbage collector. [2] | `G1 Young Generation`; `G1 Old Generation` | Recommended | -**[1]:** Garbage collector name is generally obtained via [GarbageCollectionNotificationInfo#getGcName()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcName()). +**[1]:** Garbage collector action is generally obtained via [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()). -**[2]:** Garbage collector action is generally obtained via [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()). +**[2]:** Garbage collector name is generally obtained via [GarbageCollectionNotificationInfo#getGcName()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcName()). ## JVM Threads @@ -322,8 +322,8 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | | `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended | +| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended | **[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()). diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index 052bebacb8..90fd518580 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -27,9 +27,9 @@ For Apache Kafka, the following additional attributes are defined: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `messaging.kafka.message.key` | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message.id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [1] | `myKey` | Recommended | | `messaging.kafka.consumer.group` | string | Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. | `my-group` | Recommended | | `messaging.kafka.destination.partition` | int | Partition the message is sent to. | `2` | Recommended | +| `messaging.kafka.message.key` | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message.id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [1] | `myKey` | Recommended | | `messaging.kafka.message.offset` | int | The offset of a record in the corresponding Kafka partition. | `42` | Recommended | | `messaging.kafka.message.tombstone` | boolean | A boolean that is true if the message is a tombstone. | | Conditionally Required: [2] | diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index b1505e49d7..8faceefe39 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -217,18 +217,18 @@ The following operations related to messages are defined for these semantic conv | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required | -| `messaging.operation` | string | A string identifying the kind of messaging operation as defined in the [Operation names](#operation-names) section above. [1] | `publish` | Required | -| `messaging.batch.message_count` | int | The number of messages sent, received, or processed in the scope of the batching operation. [2] | `0`; `1`; `2` | Conditionally Required: [3] | +| `messaging.batch.message_count` | int | The number of messages sent, received, or processed in the scope of the batching operation. [1] | `0`; `1`; `2` | Conditionally Required: [2] | | `messaging.client_id` | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | Recommended: If a client id is available | -| `messaging.destination.anonymous` | boolean | A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name). | | Conditionally Required: [4] | -| `messaging.destination.name` | string | The message destination name [5] | `MyQueue`; `MyTopic` | Conditionally Required: [6] | -| `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [7] | `/customers/{customerId}` | Conditionally Required: [8] | -| `messaging.destination.temporary` | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | Conditionally Required: [9] | -| `messaging.message.body.size` | int | The size of the message body in bytes. [10] | `1439` | Recommended: [11] | -| `messaging.message.conversation_id` | string | The [conversation ID](#conversations) identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended: [12] | -| `messaging.message.envelope.size` | int | The size of the message body and metadata in bytes. [13] | `2738` | Recommended: [14] | -| `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [15] | +| `messaging.destination.anonymous` | boolean | A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name). | | Conditionally Required: [3] | +| `messaging.destination.name` | string | The message destination name [4] | `MyQueue`; `MyTopic` | Conditionally Required: [5] | +| `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [6] | `/customers/{customerId}` | Conditionally Required: [7] | +| `messaging.destination.temporary` | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | Conditionally Required: [8] | +| `messaging.message.body.size` | int | The size of the message body in bytes. [9] | `1439` | Recommended: [10] | +| `messaging.message.conversation_id` | string | The [conversation ID](#conversations) identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended: [11] | +| `messaging.message.envelope.size` | int | The size of the message body and metadata in bytes. [12] | `2738` | Recommended: [13] | +| `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [14] | +| `messaging.operation` | string | A string identifying the kind of messaging operation as defined in the [Operation names](#operation-names) section above. [15] | `publish` | Required | +| `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required | | [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [16] | `amqp`; `mqtt` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [17] | `3.1.1` | Recommended | | [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [18] | `tcp`; `udp` | Recommended | @@ -238,38 +238,38 @@ The following operations related to messages are defined for these semantic conv | [`server.socket.domain`](../general/attributes.md) | string | Immediate server peer's domain name if available without reverse DNS lookup [22] | `proxy.example.com` | Recommended: [23] | | [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [24] | `16456` | Recommended: If different than `server.port`. | -**[1]:** If a custom value is used, it MUST be of low cardinality. +**[1]:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs. -**[2]:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs. +**[2]:** If the span describes an operation on a batch of messages. -**[3]:** If the span describes an operation on a batch of messages. +**[3]:** If value is `true`. When missing, the value is assumed to be `false`. -**[4]:** If value is `true`. When missing, the value is assumed to be `false`. - -**[5]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If +**[4]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If the broker does not have such notion, the destination name SHOULD uniquely identify the broker. -**[6]:** If span describes operation on a single message or if the value applies to all messages in the batch. +**[5]:** If span describes operation on a single message or if the value applies to all messages in the batch. -**[7]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. +**[6]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. -**[8]:** If available. Instrumentations MUST NOT use `messaging.destination.name` as template unless low-cardinality of destination name is guaranteed. +**[7]:** If available. Instrumentations MUST NOT use `messaging.destination.name` as template unless low-cardinality of destination name is guaranteed. -**[9]:** If value is `true`. When missing, the value is assumed to be `false`. +**[8]:** If value is `true`. When missing, the value is assumed to be `false`. -**[10]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed +**[9]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed body size should be used. -**[11]:** Only if span represents operation on a single message. +**[10]:** Only if span represents operation on a single message. -**[12]:** Only if span represents operation on a single message. +**[11]:** Only if span represents operation on a single message. -**[13]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed +**[12]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed size should be used. -**[14]:** Only if span represents operation on a single message. +**[13]:** Only if span represents operation on a single message. + +**[14]:** Only for spans that represent an operation on a single message. -**[15]:** Only for spans that represent an operation on a single message. +**[15]:** If a custom value is used, it MUST be of low cardinality. **[16]:** The value SHOULD be normalized to lowercase. @@ -339,8 +339,8 @@ under the namespace `messaging.destination_publish.*` | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `messaging.destination_publish.name` | string | The name of the original destination the message was published to [1] | `MyQueue`; `MyTopic` | Recommended | | `messaging.destination_publish.anonymous` | boolean | A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name). | | Recommended | +| `messaging.destination_publish.name` | string | The name of the original destination the message was published to [1] | `MyQueue`; `MyTopic` | Recommended | **[1]:** The name SHOULD uniquely identify a specific queue, topic, or other entity within the broker. If the broker does not have such notion, the original destination name SHOULD uniquely identify the broker. diff --git a/docs/messaging/rocketmq.md b/docs/messaging/rocketmq.md index a0b88daa06..cf7c88c194 100644 --- a/docs/messaging/rocketmq.md +++ b/docs/messaging/rocketmq.md @@ -19,19 +19,26 @@ Specific attributes for Apache RocketMQ are defined below. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `messaging.rocketmq.namespace` | string | Namespace of RocketMQ resources, resources in different namespaces are individual. | `myNamespace` | Required | | `messaging.rocketmq.client_group` | string | Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. | `myConsumerGroup` | Required | -| `messaging.rocketmq.message.delivery_timestamp` | int | The timestamp in milliseconds that the delay message is expected to be delivered to consumer. | `1665987217045` | Conditionally Required: [1] | -| `messaging.rocketmq.message.delay_time_level` | int | The delay time level for delay message, which determines the message delay time. | `3` | Conditionally Required: [2] | +| `messaging.rocketmq.consumption_model` | string | Model of message consumption. This only applies to consumer spans. | `clustering` | Recommended | +| `messaging.rocketmq.message.delay_time_level` | int | The delay time level for delay message, which determines the message delay time. | `3` | Conditionally Required: [1] | +| `messaging.rocketmq.message.delivery_timestamp` | int | The timestamp in milliseconds that the delay message is expected to be delivered to consumer. | `1665987217045` | Conditionally Required: [2] | | `messaging.rocketmq.message.group` | string | It is essential for FIFO message. Messages that belong to the same message group are always processed one by one within the same consumer group. | `myMessageGroup` | Conditionally Required: If the message type is FIFO. | -| `messaging.rocketmq.message.type` | string | Type of message. | `normal` | Recommended | -| `messaging.rocketmq.message.tag` | string | The secondary classifier of message besides topic. | `tagA` | Recommended | | `messaging.rocketmq.message.keys` | string[] | Key(s) of message, another way to mark message besides message id. | `[keyA, keyB]` | Recommended | -| `messaging.rocketmq.consumption_model` | string | Model of message consumption. This only applies to consumer spans. | `clustering` | Recommended | +| `messaging.rocketmq.message.tag` | string | The secondary classifier of message besides topic. | `tagA` | Recommended | +| `messaging.rocketmq.message.type` | string | Type of message. | `normal` | Recommended | +| `messaging.rocketmq.namespace` | string | Namespace of RocketMQ resources, resources in different namespaces are individual. | `myNamespace` | Required | + +**[1]:** If the message type is delay and delivery timestamp is not specified. -**[1]:** If the message type is delay and delay time level is not specified. +**[2]:** If the message type is delay and delay time level is not specified. + +`messaging.rocketmq.consumption_model` MUST be one of the following: -**[2]:** If the message type is delay and delivery timestamp is not specified. +| Value | Description | +|---|---| +| `clustering` | Clustering consumption model | +| `broadcasting` | Broadcasting consumption model | `messaging.rocketmq.message.type` MUST be one of the following: @@ -41,13 +48,6 @@ Specific attributes for Apache RocketMQ are defined below. | `fifo` | FIFO message | | `delay` | Delay message | | `transaction` | Transaction message | - -`messaging.rocketmq.consumption_model` MUST be one of the following: - -| Value | Description | -|---|---| -| `clustering` | Clustering consumption model | -| `broadcasting` | Broadcasting consumption model | `messaging.client_id` SHOULD be set to the client ID that is automatically generated by the Apache RocketMQ SDK. diff --git a/docs/object-stores/s3.md b/docs/object-stores/s3.md index 71d6c56360..904d9c0ad0 100644 --- a/docs/object-stores/s3.md +++ b/docs/object-stores/s3.md @@ -15,16 +15,27 @@ described on this page. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `aws.s3.bucket` | string | The S3 bucket name the request refers to. Corresponds to the `--bucket` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. [1] | `some-bucket-name` | Recommended | -| `aws.s3.key` | string | The S3 object key the request refers to. Corresponds to the `--key` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. [2] | `someFile.yml` | Recommended | -| `aws.s3.copy_source` | string | The source object (in the form `bucket`/`key`) for the copy operation. [3] | `someFile.yml` | Recommended | -| `aws.s3.upload_id` | string | Upload ID that identifies the multipart upload. [4] | `dfRtDYWFbkRONycy.Yxwh66Yjlx.cph0gtNBtJ` | Recommended | -| `aws.s3.delete` | string | The delete request container that specifies the objects to be deleted. [5] | `Objects=[{Key=string,VersionId=string},{Key=string,VersionId=string}],Quiet=boolean` | Recommended | -| `aws.s3.part_number` | int | The part number of the part being uploaded in a multipart-upload operation. This is a positive integer between 1 and 10,000. [6] | `3456` | Recommended | +| `aws.s3.copy_source` | string | The source object (in the form `bucket`/`key`) for the copy operation. [2] | `someFile.yml` | Recommended | +| `aws.s3.delete` | string | The delete request container that specifies the objects to be deleted. [3] | `Objects=[{Key=string,VersionId=string},{Key=string,VersionId=string}],Quiet=boolean` | Recommended | +| `aws.s3.key` | string | The S3 object key the request refers to. Corresponds to the `--key` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) operations. [4] | `someFile.yml` | Recommended | +| `aws.s3.part_number` | int | The part number of the part being uploaded in a multipart-upload operation. This is a positive integer between 1 and 10,000. [5] | `3456` | Recommended | +| `aws.s3.upload_id` | string | Upload ID that identifies the multipart upload. [6] | `dfRtDYWFbkRONycy.Yxwh66Yjlx.cph0gtNBtJ` | Recommended | **[1]:** The `bucket` attribute is applicable to all S3 operations that reference a bucket, i.e. that require the bucket name as a mandatory parameter. This applies to almost all S3 operations except `list-buckets`. -**[2]:** The `key` attribute is applicable to all object-related S3 operations, i.e. that require the object key as a mandatory parameter. +**[2]:** The `copy_source` attribute applies to S3 copy operations and corresponds to the `--copy-source` parameter +of the [copy-object operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html). +This applies in particular to the following operations: + +- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html) +- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) + +**[3]:** The `delete` attribute is only applicable to the [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) operation. +The `delete` attribute corresponds to the `--delete` parameter of the +[delete-objects operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-objects.html). + +**[4]:** The `key` attribute is applicable to all object-related S3 operations, i.e. that require the object key as a mandatory parameter. This applies in particular to the following operations: - [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html) @@ -41,14 +52,12 @@ This applies in particular to the following operations: - [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) - [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) -**[3]:** The `copy_source` attribute applies to S3 copy operations and corresponds to the `--copy-source` parameter -of the [copy-object operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html). -This applies in particular to the following operations: - -- [copy-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/copy-object.html) -- [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) +**[5]:** The `part_number` attribute is only applicable to the [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) +and [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) operations. +The `part_number` attribute corresponds to the `--part-number` parameter of the +[upload-part operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html). -**[4]:** The `upload_id` attribute applies to S3 multipart-upload operations and corresponds to the `--upload-id` parameter +**[6]:** The `upload_id` attribute applies to S3 multipart-upload operations and corresponds to the `--upload-id` parameter of the [S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) multipart operations. This applies in particular to the following operations: @@ -57,15 +66,6 @@ This applies in particular to the following operations: - [list-parts](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-parts.html) - [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) - [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) - -**[5]:** The `delete` attribute is only applicable to the [delete-object](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-object.html) operation. -The `delete` attribute corresponds to the `--delete` parameter of the -[delete-objects operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/delete-objects.html). - -**[6]:** The `part_number` attribute is only applicable to the [upload-part](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html) -and [upload-part-copy](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part-copy.html) operations. -The `part_number` attribute corresponds to the `--part-number` parameter of the -[upload-part operation within the S3 API](https://docs.aws.amazon.com/cli/latest/reference/s3api/upload-part.html). [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/README.md b/docs/resource/README.md index c7637f565f..312200f716 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -99,12 +99,12 @@ as specified in the [Resource SDK specification](https://github.com/open-telemet | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `service.namespace` | string | A namespace for `service.name`. [1] | `Shop` | Recommended | -| `service.instance.id` | string | The string ID of the service instance. [2] | `my-k8s-pod-deployment-1`; `627cc493-f310-47de-96bd-71410b7dec09` | Recommended | +| `service.instance.id` | string | The string ID of the service instance. [1] | `my-k8s-pod-deployment-1`; `627cc493-f310-47de-96bd-71410b7dec09` | Recommended | +| `service.namespace` | string | A namespace for `service.name`. [2] | `Shop` | Recommended | -**[1]:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. +**[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). -**[2]:** MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words `service.namespace,service.name,service.instance.id` triplet MUST be globally unique). The ID helps to distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled service). It is preferable for the ID to be persistent and stay the same for the lifetime of the service instance, however it is acceptable that the ID is ephemeral and changes during important lifetime events for the service (e.g. service restarts). If the service has no inherent unique ID that can be used as the value of this attribute it is recommended to generate a random Version 1 or Version 4 RFC 4122 UUID (services aiming for reproducible UUIDs may also use Version 5, see RFC 4122 for more recommendations). +**[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. Note: `service.namespace` and `service.name` are not intended to be concatenated for the purpose of forming a single globally unique name for the service. For example the following 2 sets of attributes actually describe 2 different services (despite the fact that the concatenation would result in the same string): @@ -132,8 +132,8 @@ service.name = Shop.shoppingcart | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. [1] | `opentelemetry` | Required | | `telemetry.sdk.language` | string | The language of the telemetry SDK. | `cpp` | Required | +| `telemetry.sdk.name` | string | The name of the telemetry SDK as defined above. [1] | `opentelemetry` | Required | | `telemetry.sdk.version` | string | The version string of the telemetry SDK. | `1.2.3` | Required | **[1]:** The OpenTelemetry SDK MUST set the `telemetry.sdk.name` attribute to `opentelemetry`. diff --git a/docs/resource/browser.md b/docs/resource/browser.md index a914a1f24e..9f5b164d88 100644 --- a/docs/resource/browser.md +++ b/docs/resource/browser.md @@ -12,19 +12,19 @@ All of these attributes can be provided by the user agent itself in the form of | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `browser.brands` | string[] | Array of brand name and version separated by a space [1] | `[ Not A;Brand 99, Chromium 99, Chrome 99]` | Recommended | -| `browser.platform` | string | The platform on which the browser is running [2] | `Windows`; `macOS`; `Android` | Recommended | +| `browser.language` | string | Preferred language of the user using the browser [2] | `en`; `en-US`; `fr`; `fr-FR` | Recommended | | `browser.mobile` | boolean | A boolean that is true if the browser is running on a mobile device [3] | | Recommended | -| `browser.language` | string | Preferred language of the user using the browser [4] | `en`; `en-US`; `fr`; `fr-FR` | Recommended | +| `browser.platform` | string | The platform on which the browser is running [4] | `Windows`; `macOS`; `Android` | Recommended | | `user_agent.original` | string | Full user-agent string provided by the browser [5] | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36` | Recommended | **[1]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.brands`). -**[2]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent. -The list of possible values is defined in the [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). Note that some (but not all) of these values can overlap with values in the [`os.type` and `os.name` attributes](./os.md). However, for consistency, the values in the `browser.platform` attribute should capture the exact value that the user agent provides. +**[2]:** This value is intended to be taken from the Navigator API `navigator.language`. **[3]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.mobile`). If unavailable, this attribute SHOULD be left unset. -**[4]:** This value is intended to be taken from the Navigator API `navigator.language`. +**[4]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent. +The list of possible values is defined in the [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). Note that some (but not all) of these values can overlap with values in the [`os.type` and `os.name` attributes](./os.md). However, for consistency, the values in the `browser.platform` attribute should capture the exact value that the user agent provides. **[5]:** The user-agent value SHOULD be provided only from browsers that do not have a mechanism to retrieve brands and platform individually from the User-Agent Client Hints API. To retrieve the value, the legacy `navigator.userAgent` API can be used. diff --git a/docs/resource/cloud-provider/aws/ecs.md b/docs/resource/cloud-provider/aws/ecs.md index ba3ae6183b..eefbee3103 100644 --- a/docs/resource/cloud-provider/aws/ecs.md +++ b/docs/resource/cloud-provider/aws/ecs.md @@ -9,8 +9,8 @@ | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `aws.ecs.container.arn` | string | The Amazon Resource Name (ARN) of an [ECS container instance](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_instances.html). | `arn:aws:ecs:us-west-1:123456789123:container/32624152-9086-4f0e-acae-1a75b14fe4d9` | Recommended | | `aws.ecs.cluster.arn` | string | The ARN of an [ECS cluster](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/clusters.html). | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | Recommended | +| `aws.ecs.container.arn` | string | The Amazon Resource Name (ARN) of an [ECS container instance](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_instances.html). | `arn:aws:ecs:us-west-1:123456789123:container/32624152-9086-4f0e-acae-1a75b14fe4d9` | Recommended | | `aws.ecs.launchtype` | string | The [launch type](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/launch_types.html) for an ECS task. | `ec2` | Recommended | | `aws.ecs.task.arn` | string | The ARN of an [ECS task definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html). | `arn:aws:ecs:us-west-1:123456789123:task/10838bed-421f-43ef-870a-f43feacbbb5b` | Recommended | | `aws.ecs.task.family` | string | The task definition family this task definition is a member of. | `opentelemetry-family` | Recommended | diff --git a/docs/resource/cloud-provider/aws/logs.md b/docs/resource/cloud-provider/aws/logs.md index d2238e68d6..5001849225 100644 --- a/docs/resource/cloud-provider/aws/logs.md +++ b/docs/resource/cloud-provider/aws/logs.md @@ -9,14 +9,14 @@ | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `aws.log.group.names` | string[] | The name(s) of the AWS log group(s) an application is writing to. [1] | `[/aws/lambda/my-function, opentelemetry-service]` | Recommended | -| `aws.log.group.arns` | string[] | The Amazon Resource Name(s) (ARN) of the AWS log group(s). [2] | `[arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:*]` | Recommended | -| `aws.log.stream.names` | string[] | The name(s) of the AWS log stream(s) an application is writing to. | `[logs/main/10838bed-421f-43ef-870a-f43feacbbb5b]` | Recommended | +| `aws.log.group.arns` | string[] | The Amazon Resource Name(s) (ARN) of the AWS log group(s). [1] | `[arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:*]` | Recommended | +| `aws.log.group.names` | string[] | The name(s) of the AWS log group(s) an application is writing to. [2] | `[/aws/lambda/my-function, opentelemetry-service]` | Recommended | | `aws.log.stream.arns` | string[] | The ARN(s) of the AWS log stream(s). [3] | `[arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:log-stream:logs/main/10838bed-421f-43ef-870a-f43feacbbb5b]` | Recommended | +| `aws.log.stream.names` | string[] | The name(s) of the AWS log stream(s) an application is writing to. | `[logs/main/10838bed-421f-43ef-870a-f43feacbbb5b]` | Recommended | -**[1]:** Multiple log groups must be supported for cases like multi-container applications, where a single application has sidecar containers, and each write to their own log group. +**[1]:** See the [log group ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). -**[2]:** See the [log group ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). +**[2]:** Multiple log groups must be supported for cases like multi-container applications, where a single application has sidecar containers, and each write to their own log group. **[3]:** See the [log stream ARN format documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format). One log group can contain several log streams, so these ARNs necessarily identify both a log group and a log stream. diff --git a/docs/resource/cloud-provider/gcp/gce.md b/docs/resource/cloud-provider/gcp/gce.md index 49d9954643..986ce0fbe5 100644 --- a/docs/resource/cloud-provider/gcp/gce.md +++ b/docs/resource/cloud-provider/gcp/gce.md @@ -7,6 +7,6 @@ | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `gcp.gce.instance.name` | string | The instance name of a GCE instance. This is the value provided by `host.name`, the visible name of the instance in the Cloud Console UI, and the prefix for the default hostname of the instance as defined by the [default internal DNS name](https://cloud.google.com/compute/docs/internal-dns#instance-fully-qualified-domain-names). | `instance-1`; `my-vm-name` | Recommended | | `gcp.gce.instance.hostname` | string | 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). | `my-host1234.example.com`; `sample-vm.us-west1-b.c.my-project.internal` | Recommended | +| `gcp.gce.instance.name` | string | The instance name of a GCE instance. This is the value provided by `host.name`, the visible name of the instance in the Cloud Console UI, and the prefix for the default hostname of the instance as defined by the [default internal DNS name](https://cloud.google.com/compute/docs/internal-dns#instance-fully-qualified-domain-names). | `instance-1`; `my-vm-name` | Recommended | diff --git a/docs/resource/cloud-provider/heroku.md b/docs/resource/cloud-provider/heroku.md index fb0171cd75..2344373f0a 100644 --- a/docs/resource/cloud-provider/heroku.md +++ b/docs/resource/cloud-provider/heroku.md @@ -9,9 +9,9 @@ | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `heroku.release.creation_timestamp` | string | Time and date the release was created | `2022-10-23T18:00:42Z` | Opt-In | -| `heroku.release.commit` | string | Commit hash for the current release | `e6134959463efd8966b20e75b913cafe3f5ec` | Opt-In | | `heroku.app.id` | string | Unique identifier for the application | `2daa2797-e42b-4624-9322-ec3f968df4da` | Opt-In | +| `heroku.release.commit` | string | Commit hash for the current release | `e6134959463efd8966b20e75b913cafe3f5ec` | Opt-In | +| `heroku.release.creation_timestamp` | string | Time and date the release was created | `2022-10-23T18:00:42Z` | Opt-In | **Mapping:** diff --git a/docs/resource/cloud.md b/docs/resource/cloud.md index 7967c30976..871c36f5bd 100644 --- a/docs/resource/cloud.md +++ b/docs/resource/cloud.md @@ -9,16 +9,20 @@ | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `cloud.provider` | string | Name of the cloud provider. | `alibaba_cloud` | Recommended | | `cloud.account.id` | string | The cloud account ID the resource is assigned to. | `111111111111`; `opentelemetry` | Recommended | -| `cloud.region` | string | The geographical region the resource is running. [1] | `us-central1`; `us-east-1` | Recommended | -| `cloud.resource_id` | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [2] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | Recommended | -| `cloud.availability_zone` | string | Cloud regions often have multiple, isolated locations known as zones to increase availability. Availability zone represents the zone where the resource is running. [3] | `us-east-1c` | Recommended | -| `cloud.platform` | string | The cloud platform in use. [4] | `alibaba_cloud_ecs` | Recommended | +| `cloud.availability_zone` | string | Cloud regions often have multiple, isolated locations known as zones to increase availability. Availability zone represents the zone where the resource is running. [1] | `us-east-1c` | Recommended | +| `cloud.platform` | string | The cloud platform in use. [2] | `alibaba_cloud_ecs` | Recommended | +| `cloud.provider` | string | Name of the cloud provider. | `alibaba_cloud` | Recommended | +| `cloud.region` | string | The geographical region the resource is running. [3] | `us-central1`; `us-east-1` | Recommended | +| `cloud.resource_id` | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [4] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | Recommended | + +**[1]:** Availability zones are called "zones" on Alibaba Cloud and Google Cloud. + +**[2]:** The prefix of the service SHOULD match the one specified in `cloud.provider`. -**[1]:** Refer to your provider's docs to see the available regions, for example [Alibaba Cloud regions](https://www.alibabacloud.com/help/doc-detail/40654.htm), [AWS regions](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/), [Azure regions](https://azure.microsoft.com/en-us/global-infrastructure/geographies/), [Google Cloud regions](https://cloud.google.com/about/locations), or [Tencent Cloud regions](https://www.tencentcloud.com/document/product/213/6091). +**[3]:** Refer to your provider's docs to see the available regions, for example [Alibaba Cloud regions](https://www.alibabacloud.com/help/doc-detail/40654.htm), [AWS regions](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/), [Azure regions](https://azure.microsoft.com/en-us/global-infrastructure/geographies/), [Google Cloud regions](https://cloud.google.com/about/locations), or [Tencent Cloud regions](https://www.tencentcloud.com/document/product/213/6091). -**[2]:** On some cloud providers, it may not be possible to determine the full ID at startup, +**[4]:** On some cloud providers, it may not be possible to determine the full ID at startup, so it may be necessary to set `cloud.resource_id` as a span attribute instead. The exact value to use for `cloud.resource_id` depends on the cloud provider. @@ -36,22 +40,6 @@ The following well-known definitions MUST be used if you set this attribute and This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share a TracerProvider. -**[3]:** Availability zones are called "zones" on Alibaba Cloud and Google Cloud. - -**[4]:** The prefix of the service SHOULD match the one specified in `cloud.provider`. - -`cloud.provider` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. - -| Value | Description | -|---|---| -| `alibaba_cloud` | Alibaba Cloud | -| `aws` | Amazon Web Services | -| `azure` | Microsoft Azure | -| `gcp` | Google Cloud Platform | -| `heroku` | Heroku Platform as a Service | -| `ibm_cloud` | IBM Cloud | -| `tencent_cloud` | Tencent Cloud | - `cloud.platform` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. | Value | Description | @@ -83,6 +71,18 @@ The following well-known definitions MUST be used if you set this attribute and | `tencent_cloud_cvm` | Tencent Cloud Cloud Virtual Machine (CVM) | | `tencent_cloud_eks` | Tencent Cloud Elastic Kubernetes Service (EKS) | | `tencent_cloud_scf` | Tencent Cloud Serverless Cloud Function (SCF) | + +`cloud.provider` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `alibaba_cloud` | Alibaba Cloud | +| `aws` | Amazon Web Services | +| `azure` | Microsoft Azure | +| `gcp` | Google Cloud Platform | +| `heroku` | Heroku Platform as a Service | +| `ibm_cloud` | IBM Cloud | +| `tencent_cloud` | Tencent Cloud | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/container.md b/docs/resource/container.md index cc9ff9fd34..7c4a014932 100644 --- a/docs/resource/container.md +++ b/docs/resource/container.md @@ -9,25 +9,25 @@ | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `container.name` | string | Container name used by container runtime. | `opentelemetry-autoconf` | Recommended | +| `container.command` | string | The command used to run the container (i.e. the command name). [1] | `otelcontribcol` | Opt-In | +| `container.command_args` | string[] | All the command arguments (including the command/executable itself) run by the container. [2] | `[otelcontribcol, --config, config.yaml]` | Opt-In | +| `container.command_line` | string | The full command run by the container as a single string representing the full command. [2] | `otelcontribcol --config config.yaml` | Opt-In | | `container.id` | string | Container ID. Usually a UUID, as for example used to [identify Docker containers](https://docs.docker.com/engine/reference/run/#container-identification). The UUID might be abbreviated. | `a3bf90e006b2` | Recommended | -| `container.runtime` | string | The container runtime managing this container. | `docker`; `containerd`; `rkt` | Recommended | +| `container.image.id` | string | Runtime specific image identifier. Usually a hash algorithm followed by a UUID. [2] | `sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f` | Recommended | | `container.image.name` | string | Name of the image the container was built on. | `gcr.io/opentelemetry/operator` | Recommended | +| `container.image.repo_digests` | string[] | Repo digests of the container image as provided by the container runtime. [3] | `[example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb, internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578]` | Recommended | | `container.image.tags` | string[] | Container image tags. An example can be found in [Docker Image Inspect](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect). Should be only the `` section of the full name for example from `registry.example.com/my-org/my-image:`. | `[v1.27.1, 3.5.7-0]` | Recommended | -| `container.image.id` | string | Runtime specific image identifier. Usually a hash algorithm followed by a UUID. [1] | `sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f` | Recommended | -| `container.image.repo_digests` | string[] | Repo digests of the container image as provided by the container runtime. [2] | `[example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb, internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578]` | Recommended | -| `container.command` | string | The command used to run the container (i.e. the command name). [3] | `otelcontribcol` | Opt-In | -| `container.command_line` | string | The full command run by the container as a single string representing the full command. [2] | `otelcontribcol --config config.yaml` | Opt-In | -| `container.command_args` | string[] | All the command arguments (including the command/executable itself) run by the container. [2] | `[otelcontribcol, --config, config.yaml]` | Opt-In | | `container.labels.` | string | Container labels, `` being the label name, the value being the label value. | `container.labels.app=nginx` | Recommended | +| `container.name` | string | Container name used by container runtime. | `opentelemetry-autoconf` | Recommended | +| `container.runtime` | string | The container runtime managing this container. | `docker`; `containerd`; `rkt` | Recommended | -**[1]:** Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker container inspect [API](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerInspect) endpoint. +**[1]:** If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage. + +**[2]:** Docker defines a sha256 of the image id; `container.image.id` corresponds to the `Image` field from the Docker container inspect [API](https://docs.docker.com/engine/api/v1.43/#tag/Container/operation/ContainerInspect) endpoint. K8s defines a link to the container registry repository with digest `"imageID": "registry.azurecr.io /namespace/service/dockerfile@sha256:bdeabd40c3a8a492eaf9e8e44d0ebbb84bac7ee25ac0cf8a7159d25f62555625"`. The ID is assinged by the container runtime and can vary in different environments. Consider using `oci.manifest.digest` if it is important to identify the same image in different environments/runtimes. -**[2]:** [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field. - -**[3]:** If using embedded credentials or sensitive data, it is recommended to remove them to prevent potential leakage. +**[3]:** [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field. ## Open Container Initiative (OCI) diff --git a/docs/resource/device.md b/docs/resource/device.md index 174057e861..5aa502c9a0 100644 --- a/docs/resource/device.md +++ b/docs/resource/device.md @@ -10,17 +10,17 @@ | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `device.id` | string | A unique identifier representing the device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | Recommended | -| `device.model.identifier` | string | The model identifier for the device [2] | `iPhone3,4`; `SM-G920F` | Recommended | -| `device.model.name` | string | The marketing name for the device model [3] | `iPhone 6s Plus`; `Samsung Galaxy S6` | Recommended | -| `device.manufacturer` | string | The name of the device manufacturer [4] | `Apple`; `Samsung` | Recommended | +| `device.manufacturer` | string | The name of the device manufacturer [2] | `Apple`; `Samsung` | Recommended | +| `device.model.identifier` | string | The model identifier for the device [3] | `iPhone3,4`; `SM-G920F` | Recommended | +| `device.model.name` | string | The marketing name for the device model [4] | `iPhone 6s Plus`; `Samsung Galaxy S6` | Recommended | **[1]:** The device identifier MUST only be defined using the values outlined below. This value is not an advertising identifier and MUST NOT be used as such. On iOS (Swift or Objective-C), this value MUST be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor). On Android (Java or Kotlin), this value MUST be equal to the Firebase Installation ID or a globally unique UUID which is persisted across sessions in your application. More information can be found [here](https://developer.android.com/training/articles/user-data-ids) on best practices and exact implementation details. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence. -**[2]:** It's recommended this value represents a machine readable version of the model identifier rather than the market or consumer-friendly name of the device. +**[2]:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`. -**[3]:** It's recommended this value represents a human readable version of the device model rather than a machine readable alternative. +**[3]:** It's recommended this value represents a machine readable version of the model identifier rather than the market or consumer-friendly name of the device. -**[4]:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`. +**[4]:** It's recommended this value represents a human readable version of the device model rather than a machine readable alternative. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/faas.md b/docs/resource/faas.md index 4de83ef8d7..1c92319818 100644 --- a/docs/resource/faas.md +++ b/docs/resource/faas.md @@ -16,13 +16,35 @@ See also: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.name` | string | The name of the single function that this runtime instance executes. [1] | `my-function`; `myazurefunctionapp/some-function-name` | Required | -| `faas.version` | string | The immutable version of the function being executed. [2] | `26`; `pinkfroid-00002` | Recommended | -| `faas.instance` | string | The execution environment ID as a string, that will be potentially reused for other invocations to the same function/function version. [3] | `2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de` | Recommended | -| `faas.max_memory` | int | The amount of memory available to the serverless function converted to Bytes. [4] | `134217728` | Recommended | -| [`cloud.resource_id`](cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [5] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | Recommended | +| [`cloud.resource_id`](cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [1] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | Recommended | +| `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 | -**[1]:** This is the name of the function as configured/deployed on the FaaS +**[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. + +The exact value to use for `cloud.resource_id` depends on the cloud provider. +The following well-known definitions MUST be used if you set this attribute and they apply: + +* **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html). + Take care not to use the "invoked ARN" directly but replace any + [alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) + with the resolved function version, as the same runtime instance may be invokable with + multiple different aliases. +* **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names) +* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/en-us/rest/api/resources/resources/get-by-id) of the invoked function, + *not* the function app, having the form + `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/`. + This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share + a TracerProvider. + +**[2]:** * **AWS Lambda:** Use the (full) log stream name. + +**[3]:** 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). + +**[4]:** 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) @@ -39,7 +61,7 @@ definition of function name MUST be used for this attribute app can host multiple functions that would usually share a TracerProvider (see also the `cloud.resource_id` attribute). -**[2]:** Depending on the cloud provider and platform, use: +**[5]:** 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). @@ -48,28 +70,6 @@ definition of function name MUST be used for this attribute * **Google Cloud Functions:** The value of the [`K_REVISION` environment variable](https://cloud.google.com/functions/docs/env-var#runtime_environment_variables_set_automatically). * **Azure Functions:** Not applicable. Do not set this attribute. - -**[3]:** * **AWS Lambda:** Use the (full) log stream name. - -**[4]:** It's recommended to set this attribute since e.g. too little memory can easily stop a Java AWS Lambda function from working correctly. On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` provides this information (which must be multiplied by 1,048,576). - -**[5]:** On some cloud providers, it may not be possible to determine the full ID at startup, -so it may be necessary to set `cloud.resource_id` as a span attribute instead. - -The exact value to use for `cloud.resource_id` depends on the cloud provider. -The following well-known definitions MUST be used if you set this attribute and they apply: - -* **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html). - Take care not to use the "invoked ARN" directly but replace any - [alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) - with the resolved function version, as the same runtime instance may be invokable with - multiple different aliases. -* **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names) -* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/en-us/rest/api/resources/resources/get-by-id) of the invoked function, - *not* the function app, having the form - `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/`. - This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share - a TracerProvider. Note: The resource attribute `faas.instance` differs from the span attribute `faas.invocation_id`. For more information see the [Semantic conventions for FaaS spans](/docs/faas/faas-spans.md#difference-between-invocation-and-instance). diff --git a/docs/resource/host.md b/docs/resource/host.md index 7469f8f40f..f216a78c92 100644 --- a/docs/resource/host.md +++ b/docs/resource/host.md @@ -12,13 +12,13 @@ To report host metrics, the `system.*` namespace SHOULD be used. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `host.id` | string | Unique host ID. For Cloud, this must be the instance_id assigned by the cloud provider. For non-containerized systems, this should be the `machine-id`. See the table below for the sources to use to determine the `machine-id` based on operating system. | `fdbf79e8af94cb7f9e8df36789187052` | Recommended | -| `host.name` | string | Name of the host. On Unix systems, it may contain what the hostname command returns, or the fully qualified hostname, or another name specified by the user. | `opentelemetry-test` | Recommended | -| `host.type` | string | Type of host. For Cloud, this must be the machine type. | `n1-standard-1` | Recommended | | `host.arch` | string | The CPU architecture the host system is running on. | `amd64` | Recommended | -| `host.image.name` | string | Name of the VM image or OS install the host was instantiated from. | `infra-ami-eks-worker-node-7d4ec78312`; `CentOS-8-x86_64-1905` | Recommended | +| `host.id` | string | Unique host ID. For Cloud, this must be the instance_id assigned by the cloud provider. For non-containerized systems, this should be the `machine-id`. See the table below for the sources to use to determine the `machine-id` based on operating system. | `fdbf79e8af94cb7f9e8df36789187052` | Recommended | | `host.image.id` | string | VM image ID or host OS image ID. For Cloud, this value is from the provider. | `ami-07b06b442921831e5` | Recommended | +| `host.image.name` | string | Name of the VM image or OS install the host was instantiated from. | `infra-ami-eks-worker-node-7d4ec78312`; `CentOS-8-x86_64-1905` | Recommended | | `host.image.version` | string | The version string of the VM image or host OS as defined in [Version Attributes](README.md#version-attributes). | `0.1` | Recommended | +| `host.name` | string | Name of the host. On Unix systems, it may contain what the hostname command returns, or the fully qualified hostname, or another name specified by the user. | `opentelemetry-test` | Recommended | +| `host.type` | string | Type of host. For Cloud, this must be the machine type. | `n1-standard-1` | Recommended | `host.arch` 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. @@ -39,12 +39,12 @@ To report host metrics, the `system.*` namespace SHOULD be used. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `host.cpu.vendor.id` | string | Processor manufacturer identifier. A maximum 12-character string. [1] | `GenuineIntel` | Opt-In | +| `host.cpu.cache.l2.size` | int | The amount of level 2 memory cache available to the processor (in Bytes). | `12288000` | Opt-In | | `host.cpu.family` | int | Numeric value specifying the family or generation of the CPU. | `6` | Opt-In | | `host.cpu.model.id` | int | Model identifier. It provides more granular information about the CPU, distinguishing it from other CPUs within the same family. | `6` | Opt-In | | `host.cpu.model.name` | string | Model designation of the processor. | `11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz` | Opt-In | | `host.cpu.stepping` | int | Stepping or core revisions. | `1` | Opt-In | -| `host.cpu.cache.l2.size` | int | The amount of level 2 memory cache available to the processor (in Bytes). | `12288000` | Opt-In | +| `host.cpu.vendor.id` | string | Processor manufacturer identifier. A maximum 12-character string. [1] | `GenuineIntel` | Opt-In | **[1]:** [CPUID](https://wiki.osdev.org/CPUID) command returns the vendor ID string in EBX, EDX and ECX registers. Writing these to memory in this order results in a 12-character string. diff --git a/docs/resource/k8s.md b/docs/resource/k8s.md index 6aada5e772..c0f5769094 100644 --- a/docs/resource/k8s.md +++ b/docs/resource/k8s.md @@ -91,8 +91,8 @@ containers on your cluster. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `k8s.pod.uid` | string | The UID of the Pod. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | | `k8s.pod.name` | string | The name of the Pod. | `opentelemetry-pod-autoconf` | Recommended | +| `k8s.pod.uid` | string | The UID of the Pod. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | ## Container @@ -127,8 +127,8 @@ any given time. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `k8s.replicaset.uid` | string | The UID of the ReplicaSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | | `k8s.replicaset.name` | string | The name of the ReplicaSet. | `opentelemetry` | Recommended | +| `k8s.replicaset.uid` | string | The UID of the ReplicaSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | ## Deployment @@ -144,8 +144,8 @@ distributed among the nodes of a cluster. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `k8s.deployment.uid` | string | The UID of the Deployment. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | | `k8s.deployment.name` | string | The name of the Deployment. | `opentelemetry` | Recommended | +| `k8s.deployment.uid` | string | The UID of the Deployment. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | ## StatefulSet @@ -160,8 +160,8 @@ about the ordering and uniqueness of these Pods. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `k8s.statefulset.uid` | string | The UID of the StatefulSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | | `k8s.statefulset.name` | string | The name of the StatefulSet. | `opentelemetry` | Recommended | +| `k8s.statefulset.uid` | string | The UID of the StatefulSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | ## DaemonSet @@ -175,8 +175,8 @@ A DaemonSet ensures that all (or some) Nodes run a copy of a Pod. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `k8s.daemonset.uid` | string | The UID of the DaemonSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | | `k8s.daemonset.name` | string | The name of the DaemonSet. | `opentelemetry` | Recommended | +| `k8s.daemonset.uid` | string | The UID of the DaemonSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | ## Job @@ -191,8 +191,8 @@ successfully terminate. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `k8s.job.uid` | string | The UID of the Job. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | | `k8s.job.name` | string | The name of the Job. | `opentelemetry` | Recommended | +| `k8s.job.uid` | string | The UID of the Job. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | ## CronJob @@ -206,8 +206,8 @@ A CronJob creates Jobs on a repeating schedule. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `k8s.cronjob.uid` | string | The UID of the CronJob. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | | `k8s.cronjob.name` | string | The name of the CronJob. | `opentelemetry` | Recommended | +| `k8s.cronjob.uid` | string | The UID of the CronJob. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/resource/os.md b/docs/resource/os.md index 585c29d10c..a868349619 100644 --- a/docs/resource/os.md +++ b/docs/resource/os.md @@ -11,11 +11,11 @@ In case of virtualized environments, this is the operating system as it is obser | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `os.type` | string | The operating system type. | `windows` | Required | +| `os.build_id` | string | Unique identifier for a particular build or compilation of the operating system. | `TQ3C.230805.001.B2`; `20E247`; `22621` | Recommended | | `os.description` | string | Human readable (not intended to be parsed) OS version information, like e.g. reported by `ver` or `lsb_release -a` commands. | `Microsoft Windows [Version 10.0.18363.778]`; `Ubuntu 18.04.1 LTS` | Recommended | | `os.name` | string | Human readable operating system name. | `iOS`; `Android`; `Ubuntu` | Recommended | +| `os.type` | string | The operating system type. | `windows` | Required | | `os.version` | string | The version string of the operating system as defined in [Version Attributes](/docs/resource/README.md#version-attributes). | `14.2.1`; `18.04.1` | Recommended | -| `os.build_id` | string | Unique identifier for a particular build or compilation of the operating system. | `TQ3C.230805.001.B2`; `20E247`; `22621` | Recommended | `os.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. diff --git a/docs/resource/process.md b/docs/resource/process.md index 388f26129c..24d1e7b8f9 100644 --- a/docs/resource/process.md +++ b/docs/resource/process.md @@ -27,14 +27,14 @@ | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `process.pid` | int | Process identifier (PID). | `1234` | Recommended | -| `process.parent_pid` | int | Parent Process identifier (PID). | `111` | Recommended | -| `process.executable.name` | string | The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | Conditionally Required: See alternative attributes below. | -| `process.executable.path` | string | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | Conditionally Required: See alternative attributes below. | | `process.command` | string | The command used to launch the process (i.e. the command name). On Linux based systems, can be set to the zeroth string in `proc/[pid]/cmdline`. On Windows, can be set to the first parameter extracted from `GetCommandLineW`. | `cmd/otelcol` | Conditionally Required: See alternative attributes below. | -| `process.command_line` | string | The full command used to launch the process as a single string representing the full command. On Windows, can be set to the result of `GetCommandLineW`. Do not set this if you have to assemble it just for monitoring; use `process.command_args` instead. | `C:\cmd\otecol --config="my directory\config.yaml"` | Conditionally Required: See alternative attributes below. | | `process.command_args` | string[] | All the command arguments (including the command/executable itself) as received by the process. On Linux-based systems (and some other Unixoid systems supporting procfs), can be set according to the list of null-delimited strings extracted from `proc/[pid]/cmdline`. For libc-based executables, this would be the full argv vector passed to `main`. | `[cmd/otecol, --config=config.yaml]` | Conditionally Required: See alternative attributes below. | +| `process.command_line` | string | The full command used to launch the process as a single string representing the full command. On Windows, can be set to the result of `GetCommandLineW`. Do not set this if you have to assemble it just for monitoring; use `process.command_args` instead. | `C:\cmd\otecol --config="my directory\config.yaml"` | Conditionally Required: See alternative attributes below. | +| `process.executable.name` | string | The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | Conditionally Required: See alternative attributes below. | +| `process.executable.path` | string | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | Conditionally Required: See alternative attributes below. | | `process.owner` | string | The username of the user that owns the process. | `root` | Recommended | +| `process.parent_pid` | int | Parent Process identifier (PID). | `111` | Recommended | +| `process.pid` | int | Process identifier (PID). | `1234` | Recommended | **Additional attribute requirements:** At least one of the following sets of attributes is required: @@ -62,9 +62,9 @@ In that case it MUST be interpreted as if it was `process.command_args`. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| `process.runtime.description` | string | An additional description about the runtime of the process, for example a specific vendor customization of the runtime environment. | `Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0` | Recommended | | `process.runtime.name` | string | The name of the runtime of this process. For compiled native binaries, this SHOULD be the name of the compiler. | `OpenJDK Runtime Environment` | Recommended | | `process.runtime.version` | string | The version of the runtime of this process, as returned by the runtime without modification. | `14.0.2` | Recommended | -| `process.runtime.description` | string | An additional description about the runtime of the process, for example a specific vendor customization of the runtime environment. | `Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0` | Recommended | How to set these attributes for particular runtime kinds is described in the following subsections. diff --git a/docs/resource/webengine.md b/docs/resource/webengine.md index 8b3a0985c7..72d61d2613 100644 --- a/docs/resource/webengine.md +++ b/docs/resource/webengine.md @@ -9,9 +9,9 @@ | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| `webengine.description` | string | Additional description of the web engine (e.g. detailed version and edition information). | `WildFly Full 21.0.0.Final (WildFly Core 13.0.1.Final) - 2.2.2.Final` | Recommended | | `webengine.name` | string | The name of the web engine. | `WildFly` | Required | | `webengine.version` | string | The version of the web engine. | `21.0.0` | Recommended | -| `webengine.description` | string | Additional description of the web engine (e.g. detailed version and edition information). | `WildFly Full 21.0.0.Final (WildFly Core 13.0.1.Final) - 2.2.2.Final` | Recommended | Information describing the web engine SHOULD be captured using the values acquired from the API provided by the web engine, preferably during runtime, to avoid maintenance burden on engine version upgrades. As an example - Java engines are often but not always packaged as application servers. For Java application servers supporting Servlet API the required information MAY be captured by invoking `ServletContext.getServerInfo()` during runtime and parsing the result. diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md index dd24a1ffa6..b02ab58cc9 100644 --- a/docs/rpc/grpc.md +++ b/docs/rpc/grpc.md @@ -19,9 +19,9 @@ Below is a table of attributes that SHOULD be included on client and server gRPC | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `rpc.grpc.status_code` | int | The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. | `0` | Required | | `rpc.grpc.request.metadata.` | string[] | gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.grpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]` | Opt-In | | `rpc.grpc.response.metadata.` | string[] | gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [2] | `rpc.grpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]` | Opt-In | +| `rpc.grpc.status_code` | int | The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request. | `0` | Required | **[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. diff --git a/docs/rpc/json-rpc.md b/docs/rpc/json-rpc.md index 3c26a8eeb9..9ceed93d14 100644 --- a/docs/rpc/json-rpc.md +++ b/docs/rpc/json-rpc.md @@ -17,10 +17,10 @@ described on this page. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `rpc.jsonrpc.version` | string | Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 does not specify this, the value can be omitted. | `2.0`; `1.0` | Conditionally Required: If other than the default version (`1.0`) | -| `rpc.jsonrpc.request_id` | string | `id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. | `10`; `request-7`; `` | Recommended | | `rpc.jsonrpc.error_code` | int | `error.code` property of response if it is an error response. | `-32700`; `100` | Conditionally Required: If response is not successful. | | `rpc.jsonrpc.error_message` | string | `error.message` property of response if it is an error response. | `Parse error`; `User already exists` | Recommended | +| `rpc.jsonrpc.request_id` | string | `id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. | `10`; `request-7`; `` | Recommended | +| `rpc.jsonrpc.version` | string | Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 does not specify this, the value can be omitted. | `2.0`; `1.0` | Conditionally Required: If other than the default version (`1.0`) | | [`rpc.method`](rpc-spans.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [1] | `exampleMethod` | Required | **[1]:** This is always required for jsonrpc. See the note in the general RPC conventions for more information. diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index d45cf2c6ea..98d753e20f 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -85,27 +85,27 @@ Examples of span names: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | +| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [3] | `exampleMethod` | Recommended | +| `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [4] | `myservice.EchoService` | Recommended | | `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | -| `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended | -| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended | -| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | Recommended | | [`server.address`](../general/attributes.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [5] | `example.com` | Required | | [`server.port`](../general/attributes.md) | int | Server port number [6] | `80`; `8080`; `443` | Conditionally Required: See below | | [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [7] | `10.5.3.2` | See below | | [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [8] | `16456` | Recommended: [9] | -**[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). - -**[2]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). - -**[3]:** The value SHOULD be normalized to lowercase. +**[1]:** The value SHOULD be normalized to lowercase. Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport, for example different processes could be listening on TCP port 12345 and UDP port 12345. -**[4]:** The value SHOULD be normalized to lowercase. +**[2]:** The value SHOULD be normalized to lowercase. + +**[3]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). + +**[4]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). **[5]:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. @@ -206,9 +206,9 @@ The event name MUST be `message`. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `message.type` | string | Whether this is a received or sent message. | `SENT` | Recommended | -| `message.id` | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] | | Recommended | | `message.compressed_size` | int | Compressed size of the message in bytes. | | Recommended | +| `message.id` | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] | | Recommended | +| `message.type` | string | Whether this is a received or sent message. | `SENT` | Recommended | | `message.uncompressed_size` | int | Uncompressed size of the message in bytes. | | Recommended | **[1]:** This way we guarantee that the values will be consistent between different implementations. diff --git a/docs/url/url.md b/docs/url/url.md index 0661c8dd8f..9f20f62170 100644 --- a/docs/url/url.md +++ b/docs/url/url.md @@ -25,11 +25,11 @@ This document defines semantic conventions that describe URL and its components. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Recommended | +| `url.fragment` | string | The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component | `SemConv` | Recommended | | `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | | `url.path` | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [2] | `/search` | Recommended | | `url.query` | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [3] | `q=OpenTelemetry` | Recommended | -| `url.fragment` | string | The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component | `SemConv` | Recommended | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Recommended | **[1]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. `url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password should be redacted and attribute's value should be `https://REDACTED:REDACTED@www.example.com/`. diff --git a/internal/tools/schema_check.sh b/internal/tools/schema_check.sh index f89a391e2b..32c489d1a7 100755 --- a/internal/tools/schema_check.sh +++ b/internal/tools/schema_check.sh @@ -6,13 +6,13 @@ set -e -BUILD_TOOL_SCHEMAS_VERSION=0.21.0 +BUILD_TOOL_SCHEMAS_VERSION=0.22.0 # List of versions that do not require or have a schema. declare -a skip_versions=("1.0.0" "1.0.1" "1.1.0" "1.2.0" "1.3.0" "1.6.0") # Verifies remote avilability of a schema file. -# +# # If the schema file is available for download, THEN we make sure it is exactly # what is in the repository. If the file is not available for download, # we pass this check. This is to allow releases to be checked in, where @@ -38,10 +38,10 @@ verify_remote_availability() { # 1 - version number verify_local_availability() { local ver="$1" - + file="$schemas_dir/$ver" echo -n "Ensure schema file $file exists... " - + # Check that the schema for the version exists. if [ -f "$file" ]; then echo "OK, exists." @@ -72,7 +72,7 @@ for file in $schemas_dir/*; do echo -n "Checking schema file $file for version $ver... " - # Check that the version is defined in the schema file. + # Check that the version is defined in the schema file. if ! grep -q "\s$ver:" $file; then echo "FAILED: $ver version definition is not found in $file" exit 1 diff --git a/model/README.md b/model/README.md index b80573074f..f32a08bb12 100644 --- a/model/README.md +++ b/model/README.md @@ -14,12 +14,12 @@ Semantic conventions for the spec MUST adhere to the [attribute requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/common/attribute-requirement-level.md), and [metric requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md) conventions. -Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.21.0/semantic-conventions/syntax.md) +Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.22.0/semantic-conventions/syntax.md) for how to write the YAML files for semantic conventions and what the YAML properties mean. A schema file for VS code is configured in the `/.vscode/settings.json` of this repository, enabling auto-completion and additional checks. Refer to -[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.21.0/semantic-conventions/README.md) for what extension you need. +[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.22.0/semantic-conventions/README.md) for what extension you need. ## Generating markdown @@ -30,7 +30,7 @@ formatted Markdown tables for all semantic conventions in the specification. Run make table-generation ``` -For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.21.0/semantic-conventions) +For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.22.0/semantic-conventions) in the OpenTelemetry build tools repository. Using this build tool, it is also possible to generate code for use in OpenTelemetry language projects.