diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c1dc5603da..3560898191e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -78,6 +78,15 @@ release. `net.host.connection.*` to `network.connection.*`, and `net.host.carrier.*` to `network.carrier.*`. ([#3426](https://github.com/open-telemetry/opentelemetry-specification/pull/3426)) +- BREAKING: Adopt ECS attributes in HTTP semantic conventions. + Renames: `http.method` to `http.request.method`, + `http.status_code` to `http.response.status_code`, + `http.request_content_length` to `http.request.body.size`, + `http.response_content_length` to `http.response.body.size`, + `http.url` to `url.full`, + `http.scheme` to `url.scheme`, + and removes `http.target` breaking it down to `http.target` to `url.path`, `url.query`, and `url.fragment`. + ([#3355](https://github.com/open-telemetry/opentelemetry-specification/pull/3355)) ### Compatibility diff --git a/schemas/1.21.0 b/schemas/1.21.0 index 554580815fe..7831021ee0b 100644 --- a/schemas/1.21.0 +++ b/schemas/1.21.0 @@ -36,6 +36,15 @@ versions: net.host.carrier.mcc: network.carrier.mcc net.host.carrier.mnc: network.carrier.mnc net.host.carrier.icc: network.carrier.icc + # https://github.com/open-telemetry/opentelemetry-specification/pull/3355 + - rename_attributes: + attribute_map: + http.method: http.request.method + http.status_code: http.response.status_code + http.scheme: url.scheme + http.url: url.full + http.request_content_length: http.request.body.size + http.response_content_length: http.response.body.size 1.20.0: spans: changes: diff --git a/semantic_conventions/deprecated/http.yaml b/semantic_conventions/deprecated/http.yaml new file mode 100644 index 00000000000..f904126c672 --- /dev/null +++ b/semantic_conventions/deprecated/http.yaml @@ -0,0 +1,41 @@ +groups: + - id: attributes.http.deprecated + type: attribute_group + brief: "Describes deprecated HTTP attributes." + prefix: http + attributes: + - id: method + type: string + brief: 'Deprecated, use `http.request.method` instead.' + stability: deprecated + examples: ["GET", "POST", "HEAD"] + - id: status_code + type: int + brief: 'Deprecated, use `http.response.status_code` instead.' + stability: deprecated + examples: [200] + - id: scheme + type: string + brief: 'Deprecated, use `url.scheme` instead.' + stability: deprecated + examples: ['http', 'https'] + - id: url + type: string + brief: 'Deprecated, use `url.full` instead.' + stability: deprecated + examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv'] + - id: target + type: string + brief: 'Deprecated, use `url.path` and `url.query` instead.' + stability: deprecated + examples: ['/search?q=OpenTelemetry#SemConv'] + - id: request_content_length + type: int + brief: 'Deprecated, use `http.request.body.size` instead.' + stability: deprecated + examples: 3495 + - id: response_content_length + type: int + brief: 'Deprecated, use `http.response.body.size` instead.' + stability: deprecated + examples: 3495 diff --git a/semantic_conventions/http-common.yaml b/semantic_conventions/http-common.yaml index 0f258022cc8..32957620073 100644 --- a/semantic_conventions/http-common.yaml +++ b/semantic_conventions/http-common.yaml @@ -4,12 +4,12 @@ groups: brief: "Describes HTTP attributes." prefix: http attributes: - - id: method + - id: request.method type: string requirement_level: required brief: 'HTTP request method.' examples: ["GET", "POST", "HEAD"] - - id: status_code + - id: response.status_code type: int requirement_level: conditionally_required: If and only if one was received/sent. @@ -53,11 +53,6 @@ groups: type: attribute_group brief: 'HTTP Server spans attributes' attributes: - - id: scheme - type: string - brief: 'The URI scheme identifying the used protocol.' - requirement_level: required - examples: ["http", "https"] - id: route type: string requirement_level: @@ -96,3 +91,6 @@ groups: - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header + - ref: url.scheme + requirement_level: required + examples: ["http", "https"] diff --git a/semantic_conventions/metrics/http.yaml b/semantic_conventions/metrics/http.yaml index 630db47924a..6a5089b6de1 100644 --- a/semantic_conventions/metrics/http.yaml +++ b/semantic_conventions/metrics/http.yaml @@ -8,8 +8,8 @@ groups: extends: attributes.http.server attributes: # todo (lmolkova) build tools don't populate grandparent attributes - - ref: http.method - - ref: http.status_code + - ref: http.request.method + - ref: http.response.status_code - ref: network.protocol.name - ref: network.protocol.version @@ -20,8 +20,10 @@ groups: instrument: updowncounter unit: "{request}" attributes: - - ref: http.method - - ref: http.scheme + - ref: http.request.method + - ref: url.scheme + requirement_level: required + examples: ["http", "https"] - ref: server.address requirement_level: required brief: > @@ -60,8 +62,8 @@ groups: # TODO (trask) below attributes are identical to above in metric.http.server.duration attributes: # todo (lmolkova) build tools don't populate grandparent attributes - - ref: http.method - - ref: http.status_code + - ref: http.request.method + - ref: http.response.status_code - ref: network.protocol.name - ref: network.protocol.version @@ -74,8 +76,8 @@ groups: extends: attributes.http.server # TODO (trask) below attributes are identical to above in metric.http.server.duration attributes: - - ref: http.method - - ref: http.status_code + - ref: http.request.method + - ref: http.response.status_code - ref: network.protocol.name - ref: network.protocol.version @@ -87,12 +89,11 @@ groups: unit: "s" extends: attributes.http.client attributes: - - ref: http.method - - ref: http.status_code + - ref: http.request.method + - ref: http.response.status_code - ref: network.protocol.name - ref: network.protocol.version - ref: server.socket.address - - id: metric.http.client.request.size type: metric metric_name: http.client.request.size @@ -102,8 +103,8 @@ groups: extends: attributes.http.client # TODO (trask) below attributes are identical to above in metric.http.client.duration attributes: - - ref: http.method - - ref: http.status_code + - ref: http.request.method + - ref: http.response.status_code - ref: network.protocol.name - ref: network.protocol.version - ref: server.socket.address @@ -117,8 +118,8 @@ groups: extends: attributes.http.client # TODO (trask) below attributes are identical to above in metric.http.client.duration attributes: - - ref: http.method - - ref: http.status_code + - ref: http.request.method + - ref: http.response.status_code - ref: network.protocol.name - ref: network.protocol.version - ref: server.socket.address diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml index 86feb34786a..2b5ac998679 100644 --- a/semantic_conventions/trace/http.yaml +++ b/semantic_conventions/trace/http.yaml @@ -8,21 +8,21 @@ groups: These conventions can be used for http and https schemes and various HTTP versions like 1.1, 2 and SPDY. attributes: - - id: request_content_length + - id: request.body.size type: int brief: > 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. examples: 3495 - - id: response_content_length + - id: response.body.size type: int brief: > 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. examples: 3495 - - ref: http.method + - ref: http.request.method sampling_relevant: true - ref: network.transport requirement_level: @@ -37,17 +37,6 @@ groups: span_kind: client brief: 'Semantic Convention for HTTP Client' attributes: - - id: url - type: string - requirement_level: required - brief: > - Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. - Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. - note: > - `http.url` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. - In such case the attribute's value should be `https://www.example.com/`. - sampling_relevant: true - examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv'] - id: resend_count type: int brief: > @@ -85,6 +74,10 @@ groups: - ref: server.socket.domain - ref: server.socket.address - ref: server.socket.port + - ref: url.full + sampling_relevant: true + requirement_level: required + - id: trace.http.server prefix: http @@ -93,14 +86,6 @@ groups: span_kind: server brief: 'Semantic Convention for HTTP Server' attributes: - - id: target - type: string - brief: 'The full request target as passed in a HTTP request line or equivalent.' - requirement_level: required - sampling_relevant: true - examples: ['/users/12314/?q=ddds'] - - ref: http.scheme - sampling_relevant: true - ref: server.address requirement_level: required sampling_relevant: true @@ -149,3 +134,12 @@ groups: Otherwise, the immediate client peer port. - ref: client.socket.address - ref: client.socket.port + - ref: url.path + requirement_level: required + sampling_relevant: true + - ref: url.query + sampling_relevant: true + - ref: url.scheme + sampling_relevant: true + requirement_level: required + examples: ["http", "https"] diff --git a/semantic_conventions/url.yaml b/semantic_conventions/url.yaml new file mode 100644 index 00000000000..6e839fc3940 --- /dev/null +++ b/semantic_conventions/url.yaml @@ -0,0 +1,39 @@ +groups: + - id: url + brief: Attributes describing URL. + type: attribute_group + prefix: url + attributes: + - id: scheme + type: string + brief: 'The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol.' + examples: ["https", "ftp", "telnet"] + - id: full + type: string + brief: Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) + note: > + For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment + is not transmitted over HTTP, but if it is known, it should be included nevertheless. + + `url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. + In such case username and password should be redacted and attribute's value should be `https://REDACTED:REDACTED@www.example.com/`. + + `url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) + and SHOULD NOT be validated or modified except for sanitizing purposes. + examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv', '//localhost'] + tag: sensitive-information + - id: path + type: string + brief: 'The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component' + examples: ['/search'] + note: When missing, the value is assumed to be `/` + - id: query + type: string + brief: 'The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component' + examples: ["q=OpenTelemetry"] + note: Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. + tag: sensitive-information + - id: fragment + type: string + brief: 'The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component' + examples: ["SemConv"] diff --git a/specification/common/attribute-naming.md b/specification/common/attribute-naming.md index d761b5f9fd3..67aee0ad094 100644 --- a/specification/common/attribute-naming.md +++ b/specification/common/attribute-naming.md @@ -44,7 +44,7 @@ Names SHOULD follow these rules: purpose should primarily drive the decision about forming nested namespaces. - For each multi-word dot-delimited component of the attribute name separate the - words by underscores (i.e. use snake_case). For example `http.status_code` + words by underscores (i.e. use snake_case). For example `http.response.status_code` denotes the status code in the http namespace. - Names SHOULD NOT coincide with namespaces. For example if @@ -96,8 +96,8 @@ denote old attribute names in rename operations). - Semantic conventions exist for four areas: for Resource, Span, Log, and Metric attribute names. In addition, for spans we have two more areas: Event and Link attribute names. Identical namespaces or names in all these areas MUST have - identical meanings. For example the `http.method` span attribute name denotes - exactly the same concept as the `http.method` metric attribute, has the same + identical meanings. For example the `http.request.method` span attribute name denotes + exactly the same concept as the `http.request.method` metric attribute, has the same data type and the same set of possible values (in both cases it records the value of the HTTP protocol's request method as a string). diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index fc3f5b89d38..52f8e34f269 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -38,7 +38,7 @@ For example, [Database semantic convention](../trace/semantic_conventions/databa ## Required -All instrumentations MUST populate the attribute. A semantic convention defining a Required attribute expects an absolute majority of instrumentation libraries and applications are able to efficiently retrieve and populate it, and can additionally meet requirements for cardinality, security, and any others specific to the signal defined by the convention. `http.method` is an example of a Required attribute. +All instrumentations MUST populate the attribute. A semantic convention defining a Required attribute expects an absolute majority of instrumentation libraries and applications are able to efficiently retrieve and populate it, and can additionally meet requirements for cardinality, security, and any others specific to the signal defined by the convention. `http.request.method` is an example of a Required attribute. _Note: Consumers of telemetry can detect if a telemetry item follows a specific semantic convention by checking for the presence of a `Required` attribute defined by such convention. For example, the presence of the `db.system` attribute on a span can be used as an indication that the span follows database semantics._ @@ -71,4 +71,4 @@ Here are several examples of expensive operations to be avoided by default: - DNS lookups to populate `server.address` when only an IP address is available to the instrumentation. Caching lookup results does not solve the issue for all possible cases and should be avoided by default too. - forcing an `http.route` calculation before the HTTP framework calculates it -- reading response stream to find `http.response_content_length` when `Content-Length` header is not available +- reading response stream to find `http.response.body.size` when `Content-Length` header is not available diff --git a/specification/common/url.md b/specification/common/url.md new file mode 100644 index 00000000000..bbe041ba67e --- /dev/null +++ b/specification/common/url.md @@ -0,0 +1,45 @@ +# Semantic conventions for URL + +**Status**: [Experimental](../document-status.md) + +This document defines semantic conventions that describe URL and its components. + +
+Table of Contents + + + +- [Attributes](#attributes) +- [Sensitive information](#sensitive-information) + + + +
+ +## Attributes + + +| 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.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 | + +**[1]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. +`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password should be redacted and attribute's value should be `https://REDACTED:REDACTED@www.example.com/`. +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) and SHOULD NOT be validated or modified except for sanitizing purposes. + +**[2]:** When missing, the value is assumed to be `/` + +**[3]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. + + +## Sensitive information + +Capturing URL and its components MAY impose security risk. User and password information, when they are provided in [User Information](https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1) subcomponent, MUST NOT be recorded. + +Instrumentations that are aware of specific sensitive query string parameters MUST scrub their values before capturing `url.query` attribute. For example, native instrumentation of a client library that passes credentials or user location in URL, must scrub corresponding properties. + +_Note: Applications and telemetry consumers should scrub sensitive information from URL attributes on collected telemetry. In systems unable to identify sensitive information, certain attribute values may be redacted entirely._ diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md index 52152541e41..1831a6e2a92 100644 --- a/specification/compatibility/prometheus_and_openmetrics.md +++ b/specification/compatibility/prometheus_and_openmetrics.md @@ -198,7 +198,7 @@ attributes, and MUST NOT be added as metric attributes: | ----------------------- | ----------- | | `server.address` | The `` portion of the target's URL that was scraped | | `server.port` | The `` portion of the target's URL that was scraped | -| `http.scheme` | `http` or `https` | +| `url.scheme` | `http` or `https` | In addition to the attributes above, the [target_info](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#supporting-target-metadata-in-both-push-based-and-pull-based-systems) diff --git a/specification/logs/data-model-appendix.md b/specification/logs/data-model-appendix.md index 96bd5d4a5ea..c3ba20c6c42 100644 --- a/specification/logs/data-model-appendix.md +++ b/specification/logs/data-model-appendix.md @@ -409,19 +409,19 @@ When mapping from the unified model to HEC, we apply this additional mapping: %m string The request method. - Attributes["http.method"] + Attributes["http.request.method"] %v,%p,%U,%q string Multiple fields that can be composed into URL. - Attributes["http.url"] + Attributes["url.full"] %>s string Response status. - Attributes["http.status_code"] + Attributes["http.response.status_code"] All other fields diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 0caef3bbe51..4dbca234bcb 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -757,14 +757,14 @@ API](../overview.md#api) authors might consider: ```python # Python -http_server_duration.Record(50, {"http.method": "POST", "http.scheme": "https"}) +http_server_duration.Record(50, {"http.request.method": "POST", "url.scheme": "https"}) http_server_duration.Record(100, http_method="GET", http_scheme="http") ``` ```csharp // C# -httpServerDuration.Record(50, ("http.method", "POST"), ("http.scheme", "https")); +httpServerDuration.Record(50, ("http.request.method", "POST"), ("url.scheme", "https")); httpServerDuration.Record(100, new HttpRequestAttributes { method = "GET", scheme = "http" }); ``` diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index a9b3316180f..8535d5dc0a6 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -69,14 +69,14 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | | `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 | -| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| `http.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` | string | HTTP request method. | `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`](../../trace/semantic_conventions/span-general.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`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | | [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required | | [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`url.scheme`](../../common/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](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. @@ -116,10 +116,10 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | +| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [1] | `example.com` | Required | | [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [2] | `80`; `8080`; `443` | Conditionally Required: [3] | +| [`url.scheme`](../../common/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]:** Determined by using the first of the following that applies @@ -154,14 +154,14 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | | `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 | -| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| `http.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` | string | HTTP request method. | `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`](../../trace/semantic_conventions/span-general.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`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | | [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required | | [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`url.scheme`](../../common/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](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. @@ -201,14 +201,14 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | | `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 | -| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| `http.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` | string | HTTP request method. | `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`](../../trace/semantic_conventions/span-general.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`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | | [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required | | [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`url.scheme`](../../common/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](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. @@ -254,8 +254,8 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| `http.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` | string | HTTP request method. | `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`](../../trace/semantic_conventions/span-general.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`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | | [`server.address`](../../trace/semantic_conventions/span-general.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` | Required | @@ -290,8 +290,8 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| `http.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` | string | HTTP request method. | `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`](../../trace/semantic_conventions/span-general.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`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | | [`server.address`](../../trace/semantic_conventions/span-general.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` | Required | @@ -326,8 +326,8 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| `http.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` | string | HTTP request method. | `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`](../../trace/semantic_conventions/span-general.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`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | | [`server.address`](../../trace/semantic_conventions/span-general.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` | Required | diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 25dd8882108..eea84660c21 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -54,7 +54,7 @@ and various HTTP versions like 1.1, 2 and SPDY. ## Name HTTP spans MUST follow the overall [guidelines for span names](../api.md#span). -HTTP server span names SHOULD be `{http.method} {http.route}` if there is a +HTTP server span names SHOULD be `{http.request.method} {http.route}` if there is a (low-cardinality) `http.route` available. HTTP server span names SHOULD be `{http.method}` if there is no (low-cardinality) `http.route` available. @@ -78,7 +78,7 @@ and MUST be set to `Error` in case of `SpanKind.CLIENT`. For HTTP status codes in the 5xx range, as well as any other code the client failed to interpret, span status MUST be set to `Error`. -Don't set the span status description if the reason can be inferred from `http.status_code`. +Don't set the span status description if the reason can be inferred from `http.response.status_code`. ## Common Attributes @@ -89,10 +89,10 @@ sections below. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.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_content_length` | 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_content_length` | 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.method` | string | HTTP request method. | `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.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.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | [`network.protocol.name`](span-general.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`](span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `1.0`; `1.1`; `2.0` | Recommended | | [`network.transport`](span-general.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: [2] | @@ -105,7 +105,7 @@ sections below. Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: -* `http.method` +* `http.request.method` `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. @@ -134,7 +134,7 @@ Following attributes MUST be provided **at span creation time** (when provided a **[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 `http.user_agent` attribute. +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. @@ -149,26 +149,24 @@ This span type represents an outbound HTTP request. There are two ways this can 2. If for some reason it is not possible to emit a span for each send attempt (because e.g. the instrumented library does not expose hooks that would allow this), instrumentations MAY create an HTTP span for the top-most operation of the HTTP client. - In this case, the `http.url` MUST be the originally requested URL, before any HTTP-redirects that may happen when executing the request. + In this case, the `url.full` MUST be the absolute URL that was originally requested, before any HTTP-redirects that may happen when executing the request. For an HTTP client span, `SpanKind` MUST be `Client`. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.url` | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | Required | -| `http.resend_count` | int | The ordinal number of request resending attempt (for any reason, including redirects). [2] | `3` | Recommended: if and only if request was retried. | -| [`server.address`](span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | -| [`server.port`](span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| `http.resend_count` | int | The ordinal number of request resending attempt (for any reason, including redirects). [1] | `3` | Recommended: if and only if request was retried. | +| [`server.address`](span-general.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` | Required | +| [`server.port`](span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | [`server.socket.address`](span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. | -| [`server.socket.domain`](span-general.md) | string | The domain name of an immediate peer. [6] | `proxy.example.com` | Recommended | +| [`server.socket.domain`](span-general.md) | string | The domain name of an immediate peer. [5] | `proxy.example.com` | Recommended | | [`server.socket.port`](span-general.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | +| [`url.full`](../../common/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [6] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Required | -**[1]:** `http.url` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case the attribute's value should be `https://www.example.com/`. +**[1]:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other). -**[2]:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other). - -**[3]:** Determined by using the first of the following that applies +**[2]:** Determined by using the first of the following that applies - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form @@ -177,17 +175,21 @@ For an HTTP client span, `SpanKind` MUST be `Client`. If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. -**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. +**[3]:** 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. + +**[4]:** If not default (`80` for `http` scheme, `443` for `https`). -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). +**[5]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. -**[6]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. +**[6]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. +`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password should be redacted and attribute's value should be `https://REDACTED:REDACTED@www.example.com/`. +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) and SHOULD NOT be validated or modified except for sanitizing purposes. Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: -* `http.url` * [`server.address`](span-general.md) * [`server.port`](span-general.md) +* [`url.full`](../../common/url.md) Note that in some cases host and port identifiers in the `Host` header might be different from the `server.address` and `server.port`, in this case instrumentation MAY populate `Host` header on `http.request.header.host` attribute even if it's not enabled by user. @@ -269,16 +271,17 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i | 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 | -| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/users/12314/?q=ddds` | Required | | [`client.address`](span-general.md) | string | Client address - unix domain socket name, IPv4 or IPv6 address. [2] | `83.164.160.102` | Recommended | | [`client.port`](span-general.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`](span-general.md) | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | | [`client.socket.port`](span-general.md) | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. | -| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | | [`server.address`](span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Required | | [`server.port`](span-general.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | | [`server.socket.address`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.5.3.2` | Opt-In | | [`server.socket.port`](span-general.md) | int | Local socket port. Useful in case of a multi-port host. | `16456` | Opt-In | +| [`url.path`](../../common/url.md) | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [7] | `/search` | Required | +| [`url.query`](../../common/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [8] | `q=OpenTelemetry` | Recommended | +| [`url.scheme`](../../common/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](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. @@ -306,12 +309,17 @@ SHOULD NOT be set if only IP address is available and capturing name would requi **[6]:** If not default (`80` for `http` scheme, `443` for `https`). +**[7]:** When missing, the value is assumed to be `/` + +**[8]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. + Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: -* `http.target` -* `http.scheme` * [`server.address`](span-general.md) * [`server.port`](span-general.md) +* [`url.path`](../../common/url.md) +* [`url.query`](../../common/url.md) +* [`url.scheme`](../../common/url.md) `http.route` MUST be provided at span creation time if and only if it's already available. If it becomes available after span starts, instrumentation MUST populate it anytime before span ends. @@ -328,13 +336,13 @@ Span name: `GET` | Attribute name | Value | | :------------------- | :-------------------------------------------------------| -| `http.method` | `"GET"` | -| `http.flavor` | `"1.1"` | -| `http.url` | `"https://example.com:8080/webshop/articles/4?s=1"` | +| `http.request.method`| `"GET"` | +| `network.protocol.version` | `"1.1"` | +| `url.full` | `"https://example.com:8080/webshop/articles/4?s=1"` | | `server.address` | `example.com` | | `server.port` | 8080 | | `server.socket.address` | `"192.0.2.5"` | -| `http.status_code` | `200` | +| `http.response.status_code` | `200` | The corresponding server Span may look like this: @@ -342,17 +350,18 @@ Span name: `GET /webshop/articles/:article_id`. | Attribute name | Value | | :------------------- | :---------------------------------------------- | -| `http.method` | `"GET"` | -| `http.flavor` | `"1.1"` | -| `http.target` | `"/webshop/articles/4?s=1"` | +| `http.request.method`| `"GET"` | +| `network.protocol.version` | `"1.1"` | +| `url.path` | `"/webshop/articles/4"` | +| `url.query` | `"?s=1"` | | `server.address` | `"example.com"` | | `server.port` | `8080` | -| `http.scheme` | `"https"` | +| `url.scheme` | `"https"` | | `http.route` | `"/webshop/articles/:article_id"` | -| `http.status_code` | `200` | +| `http.response.status_code` | `200` | | `client.address` | `"192.0.2.4"` | | `client.socket.address` | `"192.0.2.5"` (the client goes through a proxy) | -| `http.user_agent` | `"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:72.0) Gecko/20100101 Firefox/72.0"` | +| `user_agent.original` | `"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:72.0) Gecko/20100101 Firefox/72.0"` | ### HTTP client retries examples diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index 53dac43a94e..59b38229a38 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -167,13 +167,11 @@ Function F: | Span Function | | `server.address` | `foo.execute-api.us-east-1.amazonaws.com` | | | `server.port` | `413` | | | `http.method` | `GET` | `GET` | -| `http.user_agent` | `okhttp 3.0` | `okhttp 3.0` | -| `http.url` | `https://foo.execute-api.us-east-1.amazonaws.com/pets/10` | | -| `http.scheme` | | `https` | -| `http.host` | | `foo.execute-api.us-east-1.amazonaws.com` | -| `http.target` | | `/pets/10` | +| `user_agent.original` | `okhttp 3.0` | `okhttp 3.0` | +| `url.scheme` | | `https` | +| `url.path` | | `/pets/10` | | `http.route` | | `/pets/{petId}` | -| `http.status_code` | `200` | `200` | +| `http.response.status_code` | `200` | `200` | ### API Gateway Request Proxy (Lambda tracing active)