From ea50a0d2e13f215047b897133e29fd3efad093b6 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Thu, 12 Oct 2023 15:24:35 -0400 Subject: [PATCH 1/6] Add sections to changelog for easier user consumption on release. (#397) --- CHANGELOG.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7f6fa6005d..e7c4e4dcec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,12 @@ release. ## Unreleased +### Breaking + +### Features + +### Fixes + ## v1.22.0 (2023-10-12) - Remove experimental Kafka metrics ([#338](https://github.com/open-telemetry/semantic-conventions/pull/338)) From 612d101d104899f456ec9b6c77f2ba9acf6f1be9 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 13 Oct 2023 04:35:40 -0700 Subject: [PATCH 2/6] Clarify that `error.type` should be the fully-qualified exception class name (if applicable) when it represents an exception type (#387) --- CHANGELOG.md | 4 ++++ docs/http/http-metrics.md | 42 ++++++++++++++++++++++----------------- docs/http/http-spans.md | 7 ++++--- model/error.yaml | 2 +- model/http-common.yaml | 7 ++++--- 5 files changed, 37 insertions(+), 25 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e7c4e4dcec..91249c0b5d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,10 @@ release. ### Fixes +- Clarify that `error.type` should be the fully-qualified exception class name + when it represents an exception type. + ([#387](https://github.com/open-telemetry/semantic-conventions/pull/387)) + ## v1.22.0 (2023-10-12) - Remove experimental Kafka metrics ([#338](https://github.com/open-telemetry/semantic-conventions/pull/338)) diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 58c7d7c18b..0aa1e339fe 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -76,7 +76,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `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. | +| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | [`http.response.status_code`](../attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`http.route`](../attributes-registry/http.md) | string | The matched route (path template in the format used by the respective server framework). See note below [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | @@ -87,10 +87,11 @@ 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 | [`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]:** 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. +`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) +or a component-specific low cardinality error identifier. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), -`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error code. +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. @@ -248,7 +249,7 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `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. | +| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | [`http.response.status_code`](../attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`http.route`](../attributes-registry/http.md) | string | The matched route (path template in the format used by the respective server framework). See note below [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | @@ -259,10 +260,11 @@ This metric is optional. | [`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]:** 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. +`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) +or a component-specific low cardinality error identifier. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), -`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error code. +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. @@ -352,7 +354,7 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `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. | +| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | [`http.response.status_code`](../attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`http.route`](../attributes-registry/http.md) | string | The matched route (path template in the format used by the respective server framework). See note below [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | @@ -363,10 +365,11 @@ This metric is optional. | [`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]:** 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. +`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) +or a component-specific low cardinality error identifier. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), -`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error code. +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. @@ -462,7 +465,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `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. | +| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | [`http.response.status_code`](../attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `http`; `spdy` | Recommended: if not default (`http`). | @@ -472,10 +475,11 @@ 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 | [`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, -`error.type` SHOULD be set to exception type or a component-specific low cardinality error code. +`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) +or a component-specific low cardinality error identifier. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), -`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error code. +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. @@ -558,7 +562,7 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `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. | +| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | [`http.response.status_code`](../attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `http`; `spdy` | Recommended: if not default (`http`). | @@ -568,10 +572,11 @@ This metric is optional. | [`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, -`error.type` SHOULD be set to exception type or a component-specific low cardinality error code. +`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) +or a component-specific low cardinality error identifier. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), -`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error code. +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. @@ -654,7 +659,7 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `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. | +| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | [`http.response.status_code`](../attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `http`; `spdy` | Recommended: if not default (`http`). | @@ -664,10 +669,11 @@ This metric is optional. | [`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, -`error.type` SHOULD be set to exception type or a component-specific low cardinality error code. +`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) +or a component-specific low cardinality error identifier. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), -`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error code. +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index a127fde446..257ead144c 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -115,7 +115,7 @@ sections below. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `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. | +| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | Conditionally Required: If request has ended with an error. | | [`http.request.body.size`](../attributes-registry/http.md) | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | | [`http.request.header.`](../attributes-registry/http.md) | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [2] | `http.request.header.content_type=["application/json"]`; `http.request.header.x_forwarded_for=["1.2.3.4", "1.2.3.5"]` | Opt-In | | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required | @@ -130,10 +130,11 @@ sections below. | `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 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. +`error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) +or a component-specific low cardinality error identifier. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), -`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error code. +`error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. diff --git a/model/error.yaml b/model/error.yaml index cdfc587800..01b7b05f5f 100644 --- a/model/error.yaml +++ b/model/error.yaml @@ -26,6 +26,6 @@ groups: If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. - If a specific domain defines its own set of error codes (such as HTTP or gRPC status codes), + If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), it's RECOMMENDED to use a domain-specific attribute and also set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. diff --git a/model/http-common.yaml b/model/http-common.yaml index 54e53fc72a..f10e7de342 100644 --- a/model/http-common.yaml +++ b/model/http-common.yaml @@ -11,13 +11,14 @@ groups: - ref: error.type requirement_level: conditionally_required: If request has ended with an error. - examples: ['timeout', 'name_resolution_error', '500'] + examples: ['timeout', 'java.net.UnknownHostException', 'server_certificate_invalid', '500'] note: | 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. + `error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) + or a component-specific low cardinality error identifier. If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), - `error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error code. + `error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. The `error.type` value SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. From 63231257a0b62e22d699c3399043826186095832 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 13 Oct 2023 07:46:22 -0700 Subject: [PATCH 3/6] Add cardinality warning about two opt-in HTTP metric attributes (#401) Co-authored-by: Joao Grassi --- CHANGELOG.md | 2 ++ docs/http/http-metrics.md | 6 ++++++ model/metrics/http.yaml | 6 ++++++ 3 files changed, 14 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 91249c0b5d..64d9b2c8ba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,8 @@ release. - Clarify that `error.type` should be the fully-qualified exception class name when it represents an exception type. ([#387](https://github.com/open-telemetry/semantic-conventions/pull/387)) +- Add cardinality warning about two opt-in HTTP metric attributes + ([#401](https://github.com/open-telemetry/semantic-conventions/pull/401)) ## v1.22.0 (2023-10-12) diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 0aa1e339fe..2da82c97d6 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -209,6 +209,9 @@ 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. +Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker +to trigger cardinality limits, degrading the usefulness of the metric. + **[3]:** Determined by using the first of the following that applies - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. @@ -216,6 +219,9 @@ SHOULD NOT be set if only IP address is available and capturing name would requi if it's sent in absolute-form. - Port identifier of the `Host` header +Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker +to trigger cardinality limits, degrading the usefulness of the metric. + `http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. | Value | Description | diff --git a/model/metrics/http.yaml b/model/metrics/http.yaml index e9015a92d9..2596a06f08 100644 --- a/model/metrics/http.yaml +++ b/model/metrics/http.yaml @@ -52,6 +52,9 @@ groups: SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. + Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker + to trigger cardinality limits, degrading the usefulness of the metric. + - ref: server.port requirement_level: opt_in brief: > @@ -64,6 +67,9 @@ groups: if it's sent in absolute-form. - Port identifier of the `Host` header + Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker + to trigger cardinality limits, degrading the usefulness of the metric. + - id: metric.http.server.request.body.size type: metric metric_name: http.server.request.body.size From 5778d7d9a365e2e08d6baea672dbedf9f171d2c8 Mon Sep 17 00:00:00 2001 From: Michael Klishin Date: Sun, 15 Oct 2023 15:59:20 -0400 Subject: [PATCH 4/6] RabbitMQ, not RibbitMQ (#405) --- docs/messaging/rabbitmq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/messaging/rabbitmq.md b/docs/messaging/rabbitmq.md index fcc120f338..61f37c15d5 100644 --- a/docs/messaging/rabbitmq.md +++ b/docs/messaging/rabbitmq.md @@ -6,7 +6,7 @@ linkTitle: RabbitMQ **Status**: [Experimental][DocumentStatus] -The Semantic Conventions for [RibbitMQ](https://www.rabbitmq.com/) extend and override the [Messaging Semantic Conventions](README.md) +The Semantic Conventions for [RabbitMQ](https://www.rabbitmq.com/) extend and override the [Messaging Semantic Conventions](README.md) that describe common messaging operations attributes in addition to the Semantic Conventions described on this page. From d21d653031728e610bc2510d8f3e07fe3541e76f Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Sun, 15 Oct 2023 22:35:57 -0700 Subject: [PATCH 5/6] Rename `http.resend_count` to `http.request.resend_count` (#374) Co-authored-by: Alexander Wert Co-authored-by: Joao Grassi --- CHANGELOG.md | 3 +++ docs/attributes-registry/http.md | 2 +- docs/http/http-spans.md | 2 +- model/registry/http.yaml | 2 +- model/trace/http.yaml | 2 +- schema-next.yaml | 4 ++++ 6 files changed, 11 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 64d9b2c8ba..15bfd73710 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ release. ### Breaking +- BREAKING: Rename http.resend_count to http.request.resend_count. + ([#374](https://github.com/open-telemetry/semantic-conventions/pull/374)) + ### Features ### Fixes diff --git a/docs/attributes-registry/http.md b/docs/attributes-registry/http.md index 7a62cc8498..7f8602c372 100644 --- a/docs/attributes-registry/http.md +++ b/docs/attributes-registry/http.md @@ -12,7 +12,7 @@ | `http.request.header.` | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [1] | `http.request.header.content_type=["application/json"]`; `http.request.header.x_forwarded_for=["1.2.3.4", "1.2.3.5"]` | | `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | | `http.request.method_original` | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | -| `http.resend_count` | int | The ordinal number of request resending attempt (for any reason, including redirects). [3] | `3` | +| `http.request.resend_count` | int | The ordinal number of request resending attempt (for any reason, including redirects). [3] | `3` | | `http.response.body.size` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | | `http.response.header.` | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [4] | `http.response.header.content_type=["application/json"]`; `http.response.header.my_custom_header=["abc", "def"]` | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 257ead144c..67351f738c 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -244,7 +244,7 @@ For an HTTP client span, `SpanKind` MUST be `Client`. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`http.resend_count`](../attributes-registry/http.md) | int | The ordinal number of request resending attempt (for any reason, including redirects). [1] | `3` | Recommended: if and only if request was retried. | +| [`http.request.resend_count`](../attributes-registry/http.md) | int | The ordinal number of request resending attempt (for any reason, including redirects). [1] | `3` | Recommended: if and only if request was retried. | | [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended: If different than `server.address`. | | [`network.peer.port`](../general/attributes.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | | [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | diff --git a/model/registry/http.yaml b/model/registry/http.yaml index 1d6f0192fa..05483ec79b 100644 --- a/model/registry/http.yaml +++ b/model/registry/http.yaml @@ -81,7 +81,7 @@ groups: type: string brief: Original HTTP method sent by the client in the request line. examples: ["GeT", "ACL", "foo"] - - id: resend_count + - id: request.resend_count type: int brief: > The ordinal number of request resending attempt (for any reason, including redirects). diff --git a/model/trace/http.yaml b/model/trace/http.yaml index adb3534875..c0cfdaf71c 100644 --- a/model/trace/http.yaml +++ b/model/trace/http.yaml @@ -31,7 +31,7 @@ groups: span_kind: client brief: 'Semantic Convention for HTTP Client' attributes: - - ref: http.resend_count + - ref: http.request.resend_count requirement_level: recommended: if and only if request was retried. - ref: server.address diff --git a/schema-next.yaml b/schema-next.yaml index b238dd19c5..8fe76165a9 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -9,6 +9,10 @@ versions: - rename_attributes: attribute_map: messaging.message.payload_size_bytes: messaging.message.body.size + # https://github.com/open-telemetry/opentelemetry-specification/pull/374 + - rename_attributes: + attribute_map: + http.resend_count: http.request.resend_count metrics: changes: # https://github.com/open-telemetry/semantic-conventions/pull/224 From cee22ec91448808ebcfa53df689c800c7171c9e1 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Sun, 15 Oct 2023 22:42:58 -0700 Subject: [PATCH 6/6] Make `server.port` conditionally required on HTTP server semconv (#399) Co-authored-by: Joao Grassi Co-authored-by: Alexander Wert --- CHANGELOG.md | 2 ++ docs/http/http-spans.md | 2 +- model/http-common.yaml | 2 +- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 15bfd73710..2efc35c494 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,8 @@ release. ([#387](https://github.com/open-telemetry/semantic-conventions/pull/387)) - Add cardinality warning about two opt-in HTTP metric attributes ([#401](https://github.com/open-telemetry/semantic-conventions/pull/401)) +- Change `server.port` from recommended to conditionally required on HTTP server semconv. + ([#399](https://github.com/open-telemetry/semantic-conventions/pull/399)) ## v1.22.0 (2023-10-12) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 67351f738c..a5e74fdd29 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -375,7 +375,7 @@ For an HTTP server span, `SpanKind` MUST be `Server`. | [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`network.peer.port`](../general/attributes.md) | int | Peer port number of the network connection. | `65123` | Recommended | | [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Recommended: [6] | +| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | | [`url.path`](../url/url.md) | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [7] | `/search` | Required | | [`url.query`](../url/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [8] | `q=OpenTelemetry` | Conditionally Required: If and only if one was received/sent. | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | diff --git a/model/http-common.yaml b/model/http-common.yaml index f10e7de342..921f3f1e3a 100644 --- a/model/http-common.yaml +++ b/model/http-common.yaml @@ -96,7 +96,7 @@ groups: if it's sent in absolute-form. - Port identifier of the `Host` header requirement_level: - recommended: If not default (`80` for `http` scheme, `443` for `https`). + conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). - ref: url.scheme requirement_level: required examples: ["http", "https"]