From 650be8f5239bb257d51402c14e51f891f27f375e Mon Sep 17 00:00:00 2001 From: Mike Koltsov <6823298+ItsLastDay@users.noreply.github.com> Date: Fri, 22 Sep 2023 18:48:36 +0200 Subject: [PATCH 1/7] Add system.linux.memory.available metric (#323) --- CHANGELOG.md | 2 ++ CONTRIBUTING.md | 8 ++++---- docs/system/system-metrics.md | 15 +++++++++++++++ model/metrics/system-metrics.yaml | 14 ++++++++++++++ 4 files changed, 35 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 39fcf53427..ac4db6bbb1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -105,6 +105,8 @@ release. - BREAKING: Rename `messaging.message.payload_size_bytes` to `messaging.message.body.size`, remove `messaging.message.payload_compressed_size_bytes`. ([#229](https://github.com/open-telemetry/semantic-conventions/pull/229)) +- Add `system.linux.memory.available` metric. + ([#323](https://github.com/open-telemetry/semantic-conventions/pull/323)) - BREAKING: Rename `http.server.request.size` metric to `http.server.request.body.size` and `http.server.response.size` metric to `http.server.response.body.size` ([#247](https://github.com/open-telemetry/semantic-conventions/pull/247)) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5721670ffa..3bfe45c930 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,18 +21,18 @@ key, but non-obvious, aspects: - All descriptions, normative language are defined in the `docs/` directory. - We provide tooling to generate Markdown documentation from the formal - YAML definitons. See [Yaml to Markdown](#yaml-to-markdown). + YAML definitons. See [Yaml to Markdown](#yaml-to-markdown). - We use Hugo to render [semantic conventions on our website](https://opentelemetry.io/docs/specs/semconv/). You will see ` @@ -739,3 +740,17 @@ an `{os}` prefix to split this metric across OSes. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.22.0/specification/document-status.md [MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.22.0/specification/metrics/metric-requirement-level.md#recommended + +### Metric: `system.linux.memory.available` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `system.linux.memory.available` | UpDownCounter | `By` | An estimate of how much memory is available for starting new applications, without causing swapping [1] | + +**[1]:** This is an alternative to `system.memory.usage` metric with `state=free`. +Linux starting from 3.14 exports "available" memory. It takes "free" memory as a baseline, and then factors in kernel-specific values. +This is supposed to be more accurate than just "free" memory. +For reference, see the calculations [here](https://superuser.com/a/980821). +See also `MemAvailable` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html). + diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml index 2759d1f66f..cfd20979f2 100644 --- a/model/metrics/system-metrics.yaml +++ b/model/metrics/system-metrics.yaml @@ -490,3 +490,17 @@ groups: brief: "Total number of processes created over uptime of the host" instrument: counter unit: "{process}" + + # system.linux.* metrics + - id: metric.system.linux.memory.available + type: metric + metric_name: system.linux.memory.available + brief: "An estimate of how much memory is available for starting new applications, without causing swapping" + note: | + This is an alternative to `system.memory.usage` metric with `state=free`. + Linux starting from 3.14 exports "available" memory. It takes "free" memory as a baseline, and then factors in kernel-specific values. + This is supposed to be more accurate than just "free" memory. + For reference, see the calculations [here](https://superuser.com/a/980821). + See also `MemAvailable` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html). + instrument: updowncounter + unit: "By" From e4b67282cc60084656296115b9025d794293e2d6 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 22 Sep 2023 09:55:56 -0700 Subject: [PATCH 2/7] Move non-`network.*` attributes out of network.yaml (#296) Co-authored-by: Joao Grassi --- CHANGELOG.md | 2 ++ model/general.yaml | 89 ++++++++++++++++++++++++++++++++++++++++++++++ model/network.yaml | 88 --------------------------------------------- 3 files changed, 91 insertions(+), 88 deletions(-) create mode 100644 model/general.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index ac4db6bbb1..331790d89d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -110,6 +110,8 @@ release. - BREAKING: Rename `http.server.request.size` metric to `http.server.request.body.size` and `http.server.response.size` metric to `http.server.response.body.size` ([#247](https://github.com/open-telemetry/semantic-conventions/pull/247)) +- Move non-`network.*` attributes out of network.yaml. + ([#296](https://github.com/open-telemetry/semantic-conventions/pull/296)) ## v1.21.0 (2023-07-13) diff --git a/model/general.yaml b/model/general.yaml new file mode 100644 index 0000000000..4f387bac6f --- /dev/null +++ b/model/general.yaml @@ -0,0 +1,89 @@ +groups: + - id: peer + prefix: peer + type: span + brief: "Operations that access some remote service." + attributes: + - id: service + type: string + brief: > + The [`service.name`](/docs/resource/README.md#service) + of the remote service. SHOULD be equal to the actual `service.name` + resource attribute of the remote service if any. + examples: "AuthTokenCache" + - id: identity + prefix: enduser + type: span + brief: > + These attributes may be used for any operation with an authenticated and/or authorized enduser. + attributes: + - id: id + type: string + brief: > + Username or client_id extracted from the access token or + [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) + header in the inbound request from outside the system. + examples: 'username' + - id: role + type: string + brief: 'Actual/assumed role the client is making the request under extracted from token or application security context.' + examples: 'admin' + - id: scope + type: string + brief: > + Scopes or granted authorities the client currently possesses extracted from token + or application security context. The value would come from the scope associated + with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3) + or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). + examples: 'read:message, write:files' + - id: thread + prefix: thread + type: span + brief: > + These attributes may be used for any operation to store information about a thread that started a span. + attributes: + - id: id + type: int + brief: > + Current "managed" thread ID (as opposed to OS thread ID). + examples: 42 + - id: name + type: string + brief: > + Current thread name. + examples: main + - id: daemon + brief: "Whether the thread is daemon or not." + type: boolean + - id: code + prefix: code + type: span + brief: > + These attributes allow to report this unit of code and therefore to provide more context about the span. + attributes: + - id: function + type: string + brief: > + The method or function name, or equivalent (usually rightmost part of the code unit's name). + examples: serveRequest + - id: namespace + type: string + brief: > + The "namespace" within which `code.function` is defined. Usually the qualified class or module name, + such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit. + examples: com.example.MyHttpService + - id: filepath + type: string + brief: > + The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). + examples: /usr/local/MyApplication/content_root/app/index.php + - id: lineno + type: int + brief: > + The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. + examples: 42 + - id: column + type: int + brief: > + The column number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. + examples: 16 diff --git a/model/network.yaml b/model/network.yaml index 478937c110..fa83e62099 100644 --- a/model/network.yaml +++ b/model/network.yaml @@ -162,91 +162,3 @@ groups: type: string brief: "The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network." examples: "DE" - - id: peer - prefix: peer - type: span - brief: "Operations that access some remote service." - attributes: - - id: service - type: string - brief: > - The [`service.name`](/docs/resource/README.md#service) - of the remote service. SHOULD be equal to the actual `service.name` - resource attribute of the remote service if any. - examples: "AuthTokenCache" - - id: identity - prefix: enduser - type: span - brief: > - These attributes may be used for any operation with an authenticated and/or authorized enduser. - attributes: - - id: id - type: string - brief: > - Username or client_id extracted from the access token or - [Authorization](https://tools.ietf.org/html/rfc7235#section-4.2) - header in the inbound request from outside the system. - examples: 'username' - - id: role - type: string - brief: 'Actual/assumed role the client is making the request under extracted from token or application security context.' - examples: 'admin' - - id: scope - type: string - brief: > - Scopes or granted authorities the client currently possesses extracted from token - or application security context. The value would come from the scope associated - with an [OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3) - or an attribute value in a [SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). - examples: 'read:message, write:files' - - id: thread - prefix: thread - type: span - brief: > - These attributes may be used for any operation to store information about a thread that started a span. - attributes: - - id: id - type: int - brief: > - Current "managed" thread ID (as opposed to OS thread ID). - examples: 42 - - id: name - type: string - brief: > - Current thread name. - examples: main - - id: daemon - brief: "Whether the thread is daemon or not." - type: boolean - - id: code - prefix: code - type: span - brief: > - These attributes allow to report this unit of code and therefore to provide more context about the span. - attributes: - - id: function - type: string - brief: > - The method or function name, or equivalent (usually rightmost part of the code unit's name). - examples: serveRequest - - id: namespace - type: string - brief: > - The "namespace" within which `code.function` is defined. Usually the qualified class or module name, - such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit. - examples: com.example.MyHttpService - - id: filepath - type: string - brief: > - The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). - examples: /usr/local/MyApplication/content_root/app/index.php - - id: lineno - type: int - brief: > - The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. - examples: 42 - - id: column - type: int - brief: > - The column number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. - examples: 16 From 65eed24c6c03058c090f1106ff62909aa999e2dd Mon Sep 17 00:00:00 2001 From: Surbhi A <138259843+surbhiia@users.noreply.github.com> Date: Fri, 22 Sep 2023 10:02:30 -0700 Subject: [PATCH 3/7] Add android.yaml and android.os.api.level resource attribute (#328) Co-authored-by: Alexander Wert Co-authored-by: Joao Grassi --- CHANGELOG.md | 2 ++ docs/resource/android.md | 15 +++++++++++++++ model/resource/android.yaml | 14 ++++++++++++++ 3 files changed, 31 insertions(+) create mode 100644 docs/resource/android.md create mode 100644 model/resource/android.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index 331790d89d..5dd4e7098a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -112,6 +112,8 @@ release. ([#247](https://github.com/open-telemetry/semantic-conventions/pull/247)) - Move non-`network.*` attributes out of network.yaml. ([#296](https://github.com/open-telemetry/semantic-conventions/pull/296)) +- Introducing Android `android.os.api_level` resource attribute. + ([#328](https://github.com/open-telemetry/semantic-conventions/pull/328)) ## v1.21.0 (2023-07-13) diff --git a/docs/resource/android.md b/docs/resource/android.md new file mode 100644 index 0000000000..bbef3af2d0 --- /dev/null +++ b/docs/resource/android.md @@ -0,0 +1,15 @@ +# Android + +**Status**: [Experimental][DocumentStatus] + +**type:** `android` + +**Description**: The Android platform on which the Android application is running. + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `android.os.api_level` | string | Uniquely identifies the framework API revision offered by a version (`os.version`) of the android operating system. More information can be found [here](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels). | `33`; `32` | Recommended | + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/model/resource/android.yaml b/model/resource/android.yaml new file mode 100644 index 0000000000..dcc236d846 --- /dev/null +++ b/model/resource/android.yaml @@ -0,0 +1,14 @@ +groups: + - id: android + prefix: android + type: resource + brief: > + The Android platform on which the Android application is running. + attributes: + - id: os.api_level + type: string + brief: > + Uniquely identifies the framework API revision offered by a version + (`os.version`) of the android operating system. More information can be found + [here](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels). + examples: ['33', '32'] From c7b094d36428ea7c7628533bfa4ab79fa153aa37 Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Mon, 25 Sep 2023 23:44:03 +0900 Subject: [PATCH 4/7] Remove service.version from list of attributes with dedicated env var (#261) Co-authored-by: Josh Suereth Co-authored-by: Joao Grassi --- docs/resource/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/resource/README.md b/docs/resource/README.md index 0426bd6249..c7637f565f 100644 --- a/docs/resource/README.md +++ b/docs/resource/README.md @@ -62,7 +62,6 @@ These are the attributes which MAY be configurable via a dedicated environment v as specified in [OpenTelemetry Environment Variable Specification](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/configuration/sdk-environment-variables.md): - [`service.name`](#service) -- [`service.version`](#service) ## Semantic Attributes with SDK-provided Default Value From 1d3d63b3d6ef85d658c96f463d44f33029de9cc7 Mon Sep 17 00:00:00 2001 From: Goutham Veeramachaneni Date: Mon, 25 Sep 2023 16:49:20 +0200 Subject: [PATCH 5/7] Update span name recommendation for HTTP Server (#287) Signed-off-by: Goutham Co-authored-by: Trask Stalnaker Co-authored-by: Johannes Tax Co-authored-by: Josh Suereth --- docs/http/http-spans.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 914a859f0c..0449089215 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -368,10 +368,6 @@ This span type represents an inbound HTTP request. For an HTTP server span, `SpanKind` MUST be `Server`. -Given an inbound request for a route (e.g. `"/users/:userID?"`) the `name` attribute of the span SHOULD be set to this route. - -If the route cannot be determined, the `name` attribute MUST be set as defined in the general semantic conventions for HTTP. - | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| From 984079ee2b98a5700b139989db9737b044ab40e6 Mon Sep 17 00:00:00 2001 From: Surbhi A <138259843+surbhiia@users.noreply.github.com> Date: Mon, 25 Sep 2023 07:56:22 -0700 Subject: [PATCH 6/7] Adding os.build_id resource attribute and discussion why os.sdk.version isn't required (#293) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Joao Grassi Co-authored-by: Christian Neumüller Co-authored-by: Joao Grassi Co-authored-by: Josh Suereth --- CHANGELOG.md | 2 ++ docs/resource/os.md | 1 + model/resource/os.yaml | 4 ++++ 3 files changed, 7 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5dd4e7098a..613d3c8278 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -114,6 +114,8 @@ release. ([#296](https://github.com/open-telemetry/semantic-conventions/pull/296)) - Introducing Android `android.os.api_level` resource attribute. ([#328](https://github.com/open-telemetry/semantic-conventions/pull/328)) +- Added `os.build_id` resource attribute. + ([#293](https://github.com/open-telemetry/semantic-conventions/pull/293)) ## v1.21.0 (2023-07-13) diff --git a/docs/resource/os.md b/docs/resource/os.md index 2b73acea08..585c29d10c 100644 --- a/docs/resource/os.md +++ b/docs/resource/os.md @@ -15,6 +15,7 @@ In case of virtualized environments, this is the operating system as it is obser | `os.description` | string | Human readable (not intended to be parsed) OS version information, like e.g. reported by `ver` or `lsb_release -a` commands. | `Microsoft Windows [Version 10.0.18363.778]`; `Ubuntu 18.04.1 LTS` | Recommended | | `os.name` | string | Human readable operating system name. | `iOS`; `Android`; `Ubuntu` | Recommended | | `os.version` | string | The version string of the operating system as defined in [Version Attributes](/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/model/resource/os.yaml b/model/resource/os.yaml index 083b88495e..78636f8461 100644 --- a/model/resource/os.yaml +++ b/model/resource/os.yaml @@ -63,3 +63,7 @@ groups: The version string of the operating system as defined in [Version Attributes](/docs/resource/README.md#version-attributes). examples: ['14.2.1', '18.04.1'] + - id: build_id + type: string + brief: 'Unique identifier for a particular build or compilation of the operating system.' + examples: ['TQ3C.230805.001.B2', '20E247', '22621'] From 2ef85e6e84de3b173dd374eff66d7bbf414cefd7 Mon Sep 17 00:00:00 2001 From: Alexander Wert Date: Tue, 26 Sep 2023 09:55:47 +0200 Subject: [PATCH 7/7] Moved template attributes to yaml model files (#315) Co-authored-by: Trask Stalnaker Co-authored-by: Joao Grassi --- docs/database/elasticsearch.md | 40 ++++++++++++-------------------- docs/http/http-spans.md | 42 +++++++++++++++------------------- docs/rpc/connect-rpc.md | 16 +++++-------- docs/rpc/grpc.md | 16 +++++-------- model/trace/database.yaml | 13 +++++++++++ model/trace/http.yaml | 31 +++++++++++++++++++++++++ model/trace/rpc.yaml | 36 +++++++++++++++++++++++++++++ 7 files changed, 125 insertions(+), 69 deletions(-) diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index 43003ddc8b..8dd4a5fc4d 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -21,19 +21,6 @@ name, as the path could contain dynamic values. The endpoint id is the `name` fi [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json). If the endpoint id is not available, the span name SHOULD be the `http.request.method`. -## URL path parts - -Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format -`db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD -reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) -in order to map the path part values to their names. - -| Attribute | Type | Description | Examples | Requirement Level | -|-------------------------------------|---|---------------------------------------|------------------------------------------------------------------------------------------|---| -| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | Conditionally Required: [1] | - -**[1]:** when the url has dynamic values - ## Call-level attributes @@ -41,22 +28,25 @@ in order to map the path part values to their names. |---|---|---|---|---| | `db.elasticsearch.cluster.name` | string | Represents the identifier of an Elasticsearch cluster. | `e9106fc68e3044f0b1475b04bf4ffd5f` | Recommended: [1] | | `db.elasticsearch.node.name` | string | Represents the human-readable identifier of the node/instance to which a request was routed. | `instance-0000000001` | Recommended: [2] | -| [`db.operation`](database-spans.md) | string | The endpoint identifier for the request. [3] | `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: [4] | -| `http.request.method` | string | HTTP request method. [5] | `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. [6] | `example.com` | See below | -| [`server.port`](../general/attributes.md) | int | Server port number [7] | `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) [8] | `https://localhost:9200/index/_search?q=user.id:kimchy` | Required | +| `db.elasticsearch.path_parts.` | string | A dynamic value in the url path. [3] | `db.elasticsearch.path_parts.index=test-index`; `db.elasticsearch.path_parts.doc_id=123` | Conditionally Required: when the url has dynamic values | +| [`db.operation`](database-spans.md) | string | The endpoint identifier for the request. [4] | `search`; `ml.close_job`; `cat.aliases` | Required | +| [`db.statement`](database-spans.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | Recommended: [5] | +| `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 | **[1]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. **[2]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Instance" HTTP response header. -**[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]:** Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) in order to map the path part values to their names. + +**[4]:** 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. -**[4]:** Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information. +**[5]:** Should be collected by default for search-type queries and only if there is sanitization that excludes sensitive information. -**[5]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[6]:** 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). @@ -71,12 +61,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. -**[6]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent +**[7]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries (e.g. proxies) if it's available. -**[7]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. +**[8]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. -**[8]:** 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]:** 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/http/http-spans.md b/docs/http/http-spans.md index 0449089215..ee2128f460 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -17,7 +17,6 @@ and various HTTP versions like 1.1, 2 and SPDY. - [Name](#name) - [Status](#status) - [Common Attributes](#common-attributes) - * [HTTP request and response headers](#http-request-and-response-headers) - [HTTP client](#http-client) * [HTTP client span duration](#http-client-span-duration) * [HTTP request retries and redirects](#http-request-retries-and-redirects) @@ -120,17 +119,27 @@ sections below. | `http.request.method_original` | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | Conditionally Required: [1] | | `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 | -| `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.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 | | [`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. [4] | `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. | `tcp`; `udp` | Conditionally Required: [5] | +| [`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. | `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 | | `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]:** If the request fails with an error before response status code was sent or received, +**[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, `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), @@ -146,7 +155,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. +**[5]:** 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). @@ -161,9 +170,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. -**[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`. +**[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`. -**[5]:** If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`). +**[7]:** If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`). Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: @@ -207,21 +216,6 @@ Following attributes MUST be provided **at span creation time** (when provided a | `ipv6` | IPv6 | -### HTTP request and response headers - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|-------------------| -| `http.request.header.` | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [1] [2] | `http.request.header.content_type=["application/json"]`; `http.request.header.x_forwarded_for=["1.2.3.4", "1.2.3.5"]` | Opt-In | -| `http.response.header.` | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [1] [2] | `http.response.header.content_type=["application/json"]`; `http.response.header.my_custom_header=["abc", "def"]` | Opt-In | - -**[1]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. -Including all request/response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. - -The `User-Agent` header is already captured in the `user_agent.original` attribute. -Users MAY explicitly configure instrumentations to capture them even though it is not recommended. - -**[2]:** The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. - ## HTTP client This span type represents an outbound HTTP request. There are two ways this can be achieved in an instrumentation: diff --git a/docs/rpc/connect-rpc.md b/docs/rpc/connect-rpc.md index f383bf7703..55ec272b40 100644 --- a/docs/rpc/connect-rpc.md +++ b/docs/rpc/connect-rpc.md @@ -20,9 +20,15 @@ Below is a table of attributes that SHOULD be included on client and server Conn | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `rpc.connect_rpc.error_code` | string | The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values. | `cancelled` | Conditionally Required: [1] | +| `rpc.connect_rpc.request.metadata.` | string[] | Connect request metadata, `` being the normalized Connect Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [2] | `rpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]` | Opt-In | +| `rpc.connect_rpc.response.metadata.` | string[] | Connect response metadata, `` being the normalized Connect Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [3] | `rpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]` | Opt-In | **[1]:** If response is not successful and if error code available. +**[2]:** 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. + +**[3]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + `rpc.connect_rpc.error_code` MUST be one of the following: | Value | Description | @@ -49,14 +55,4 @@ Below is a table of attributes that SHOULD be included on client and server Conn If `rpc.connect_rpc.error_code` is set, [Span Status](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/trace/api.md#set-status) MUST be set to `Error` and left unset in all other cases. -## Connect RPC Request and Response Metadata - -| Attribute | Type | Description | Examples | Requirement Level | -|-------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|-------------------| -| `rpc.connect_rpc.request.metadata.` | string[] | Connect request metadata, `` being the normalized Connect Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]` | Optional | -| `rpc.connect_rpc.response.metadata.` | string[] | Connect response metadata, `` being the normalized Connect Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]` | Optional | - -**[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. -Including all request/response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. - [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/rpc/grpc.md b/docs/rpc/grpc.md index c5f140bf6f..dd24a1ffa6 100644 --- a/docs/rpc/grpc.md +++ b/docs/rpc/grpc.md @@ -20,6 +20,12 @@ 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 | + +**[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + +**[2]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. `rpc.grpc.status_code` MUST be one of the following: @@ -72,14 +78,4 @@ and [Span Kind](https://github.com/open-telemetry/opentelemetry-specification/tr | DATA_LOSS | `Error` | `Error` | | UNAUTHENTICATED | unset | `Error` | -## gRPC Request and Response Metadata - -| Attribute | Type | Description | Examples | Requirement Level | -|-------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|-------------------| -| `rpc.grpc.request.metadata.` | string[] | gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.grpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]` | Opt-In | -| `rpc.grpc.response.metadata.` | string[] | gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.grpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]` | Opt-In | - -**[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. -Including all request/response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. - [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/model/trace/database.yaml b/model/trace/database.yaml index 2348a2a0f0..aeb68fc6af 100644 --- a/model/trace/database.yaml +++ b/model/trace/database.yaml @@ -472,6 +472,19 @@ groups: brief: > Represents the human-readable identifier of the node/instance to which a request was routed. examples: ["instance-0000000001"] + - id: path_parts + type: template[string] + requirement_level: + conditionally_required: when the url has dynamic values + tag: call-level-tech-specific + brief: > + A dynamic value in the url path. + note: > + Many Elasticsearch url paths allow dynamic values. These SHOULD be recorded in span attributes in the format + `db.elasticsearch.path_parts.`, where `` is the url path part name. The implementation SHOULD + reference the [elasticsearch schema](https://raw.githubusercontent.com/elastic/elasticsearch-specification/main/output/schema/schema.json) + in order to map the path part values to their names. + examples: ['db.elasticsearch.path_parts.index=test-index', 'db.elasticsearch.path_parts.doc_id=123'] - id: db.sql prefix: 'db.sql' diff --git a/model/trace/http.yaml b/model/trace/http.yaml index 53898fb483..ae362604ca 100644 --- a/model/trace/http.yaml +++ b/model/trace/http.yaml @@ -28,6 +28,37 @@ groups: is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. examples: 3495 + - id: request.header + type: template[string[]] + requirement_level: opt_in + brief: > + HTTP request headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. + note: > + Instrumentations SHOULD require an explicit configuration of which headers are to be captured. + Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information. + + 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. + examples: ['http.request.header.content_type=["application/json"]', 'http.request.header.x_forwarded_for=["1.2.3.4", "1.2.3.5"]'] + - id: response.header + type: template[string[]] + requirement_level: opt_in + brief: > + HTTP response headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. + note: > + Instrumentations SHOULD require an explicit configuration of which headers are to be captured. + Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. + + 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. + examples: ['http.response.header.content_type=["application/json"]', 'http.response.header.my_custom_header=["abc", "def"]'] - ref: http.request.method sampling_relevant: true - ref: network.transport diff --git a/model/trace/rpc.yaml b/model/trace/rpc.yaml index d2aab9a5ed..38a25016e0 100644 --- a/model/trace/rpc.yaml +++ b/model/trace/rpc.yaml @@ -156,6 +156,24 @@ groups: value: 16 requirement_level: required brief: "The [numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) of the gRPC request." + - id: request.metadata + type: template[string[]] + requirement_level: opt_in + brief: > + gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. + note: > + Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. + Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + examples: ['rpc.grpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]'] + - id: response.metadata + type: template[string[]] + requirement_level: opt_in + brief: > + gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. + note: > + Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. + Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + examples: ['rpc.grpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]'] - id: rpc.jsonrpc prefix: rpc.jsonrpc @@ -261,3 +279,21 @@ groups: requirement_level: conditionally_required: If response is not successful and if error code available. brief: "The [error codes](https://connect.build/docs/protocol/#error-codes) of the Connect request. Error codes are always string values." + - id: request.metadata + type: template[string[]] + requirement_level: opt_in + brief: > + Connect request metadata, `` being the normalized Connect Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. + note: > + Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. + Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + examples: ['rpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]'] + - id: response.metadata + type: template[string[]] + requirement_level: opt_in + brief: > + Connect response metadata, `` being the normalized Connect Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. + note: > + Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. + Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. + examples: ['rpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]']