From b3c6d06442b33f02bbea2d6356d58011a26ee78c Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 5 Apr 2023 19:35:12 -0700 Subject: [PATCH] ECS onboarding for HTTP attributes --- semantic_conventions/http-common.yaml | 54 +++++++++-- semantic_conventions/metrics/http.yaml | 28 +++--- semantic_conventions/trace/http.yaml | 27 ++---- semantic_conventions/url.yaml | 27 ++++++ specification/common/attribute-naming.md | 6 +- .../common/attribute-requirement-level.md | 4 +- .../prometheus_and_openmetrics.md | 2 +- specification/logs/data-model-appendix.md | 6 +- specification/metrics/api.md | 4 +- .../semantic_conventions/http-metrics.md | 43 +++++---- .../trace/semantic_conventions/http.md | 93 ++++++++++--------- .../instrumentation/aws-lambda.md | 14 ++- 12 files changed, 184 insertions(+), 124 deletions(-) create mode 100644 semantic_conventions/url.yaml diff --git a/semantic_conventions/http-common.yaml b/semantic_conventions/http-common.yaml index faf7ff1ba84..f9a69067674 100644 --- a/semantic_conventions/http-common.yaml +++ b/semantic_conventions/http-common.yaml @@ -1,15 +1,56 @@ 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.bytes` instead.' + stability: deprecated + examples: 3495 + - id: response_content_length + type: int + brief: 'Deprecated, use `http.response.body.bytes` instead.' + stability: deprecated + examples: 3495 + - id: attributes.http.common type: attribute_group 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. @@ -47,17 +88,13 @@ groups: note: > When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. + - ref: url.full - id: attributes.http.server prefix: http 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 +133,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"] \ No newline at end of file diff --git a/semantic_conventions/metrics/http.yaml b/semantic_conventions/metrics/http.yaml index ed1fc781844..cbb62da1138 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: net.protocol.name - ref: net.protocol.version @@ -20,8 +20,8 @@ groups: instrument: updowncounter unit: "{request}" attributes: - - ref: http.method - - ref: http.scheme + - ref: http.request.method + - ref: url.scheme - ref: net.host.name requirement_level: required brief: > @@ -60,8 +60,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: net.protocol.name - ref: net.protocol.version @@ -74,8 +74,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: net.protocol.name - ref: net.protocol.version @@ -87,8 +87,8 @@ groups: unit: "ms" extends: attributes.http.client attributes: - - ref: http.method - - ref: http.status_code + - ref: http.request.method + - ref: http.response.status_code - ref: net.protocol.name - ref: net.protocol.version - ref: net.sock.peer.addr @@ -102,8 +102,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: net.protocol.name - ref: net.protocol.version - ref: net.sock.peer.addr @@ -117,8 +117,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: net.protocol.name - ref: net.protocol.version - ref: net.sock.peer.addr diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml index e5de352f0f3..919c9f61d39 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.bytes 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.bytes 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: net.sock.peer.addr - ref: net.sock.peer.port @@ -38,17 +38,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: > @@ -91,12 +80,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'] - id: client_ip type: string brief: > @@ -115,7 +98,7 @@ groups: one is at least somewhat confident that the address is not that of the closest proxy. examples: '83.164.160.102' - - ref: http.scheme + - ref: http.request.method sampling_relevant: true - ref: net.host.name requirement_level: required @@ -149,3 +132,5 @@ groups: - ref: net.sock.host.addr requirement_level: opt_in - ref: net.sock.host.port + - ref: url.path + - ref: url.query \ No newline at end of file diff --git a/semantic_conventions/url.yaml b/semantic_conventions/url.yaml new file mode 100644 index 00000000000..60f9004b434 --- /dev/null +++ b/semantic_conventions/url.yaml @@ -0,0 +1,27 @@ +groups: + - id: url + brief: "Describes URL." + type: attribute_group + prefix: url + attributes: + - id: scheme + type: string + brief: 'The URI scheme identifying the used protocol.' + examples: ["http", "https"] + - id: full + type: string + 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: > + `url.full` 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/`. + examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv'] + - id: path + type: string + brief: 'The URI path' + examples: ['/search'] + - id: query + type: string + brief: 'The URI query' + examples: ["?q=OpenTelemetry#SemConv"] \ No newline at end of file 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 e9da7f07025..a8babd44ce7 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 `net.peer.name` 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.bytes` when `Content-Length` header is not available diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md index 1acb3b7d570..76eab805eed 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: | ----------------------- | ----------- | | `net.host.name` | The `` portion of the target's URL that was scraped | | `net.host.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 f0dd017d752..f23c7cc2041 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 d044bc348a6..09814a9e437 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -728,14 +728,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 e18bb475bae..4f1b50b428c 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -41,14 +41,14 @@ This metric is required. | 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. | | [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [2] | `localhost` | Required | | [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [3] | `8080` | Conditionally Required: [4] | | [`net.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`net.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [5] | `3.1.1` | Recommended | +| `url.scheme` | string | The URI scheme 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. @@ -88,10 +88,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 | | [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [1] | `localhost` | Required | | [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [2] | `8080` | Conditionally Required: [3] | +| `url.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Recommended | **[1]:** Determined by using the first of the following that applies @@ -126,14 +126,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. | | [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [2] | `localhost` | Required | | [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [3] | `8080` | Conditionally Required: [4] | | [`net.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`net.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [5] | `3.1.1` | Recommended | +| `url.scheme` | string | The URI scheme 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. @@ -173,14 +173,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. | | [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [2] | `localhost` | Required | | [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [3] | `8080` | Conditionally Required: [4] | | [`net.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`net.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [5] | `3.1.1` | Recommended | +| `url.scheme` | string | The URI scheme 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. @@ -222,13 +222,14 @@ This metric is required. | 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. | | [`net.peer.name`](../../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. [1] | `example.com` | Required | | [`net.peer.port`](../../trace/semantic_conventions/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. [2] | `80`; `8080`; `443` | Conditionally Required: [3] | | [`net.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`net.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | | [`net.sock.peer.addr`](../../trace/semantic_conventions/span-general.md) | string | Remote socket peer address: IPv4 or IPv6 for internet protocols, path for local communication, [etc](https://man7.org/linux/man-pages/man7/address_families.7.html). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | +| `url.full` | 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. [5] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | Recommended | **[1]:** Determined by using the first of the following that applies @@ -243,6 +244,8 @@ SHOULD NOT be set if capturing it would require an extra DNS lookup. **[3]:** If not default (`80` for `http` scheme, `443` for `https`). **[4]:** `net.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]:** `url.full` 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/`. ### Metric: `http.client.request.size` @@ -258,13 +261,14 @@ 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. | | [`net.peer.name`](../../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. [1] | `example.com` | Required | | [`net.peer.port`](../../trace/semantic_conventions/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. [2] | `80`; `8080`; `443` | Conditionally Required: [3] | | [`net.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`net.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | | [`net.sock.peer.addr`](../../trace/semantic_conventions/span-general.md) | string | Remote socket peer address: IPv4 or IPv6 for internet protocols, path for local communication, [etc](https://man7.org/linux/man-pages/man7/address_families.7.html). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | +| `url.full` | 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. [5] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | Recommended | **[1]:** Determined by using the first of the following that applies @@ -279,6 +283,8 @@ SHOULD NOT be set if capturing it would require an extra DNS lookup. **[3]:** If not default (`80` for `http` scheme, `443` for `https`). **[4]:** `net.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]:** `url.full` 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/`. ### Metric: `http.client.response.size` @@ -294,13 +300,14 @@ 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. | | [`net.peer.name`](../../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. [1] | `example.com` | Required | | [`net.peer.port`](../../trace/semantic_conventions/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. [2] | `80`; `8080`; `443` | Conditionally Required: [3] | | [`net.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`net.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | | [`net.sock.peer.addr`](../../trace/semantic_conventions/span-general.md) | string | Remote socket peer address: IPv4 or IPv6 for internet protocols, path for local communication, [etc](https://man7.org/linux/man-pages/man7/address_families.7.html). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | +| `url.full` | 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. [5] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | Recommended | **[1]:** Determined by using the first of the following that applies @@ -315,4 +322,6 @@ SHOULD NOT be set if capturing it would require an extra DNS lookup. **[3]:** If not default (`80` for `http` scheme, `443` for `https`). **[4]:** `net.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]:** `url.full` 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/`. diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 636683beeb0..9893117b171 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -30,7 +30,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. @@ -54,7 +54,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 @@ -65,10 +65,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.bytes` | 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.bytes` | 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 | | [`net.protocol.name`](span-general.md) | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `http`; `spdy` | Recommended: if not default (`http`). | | [`net.protocol.version`](span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `1.0`; `1.1`; `2.0` | Recommended | | [`net.sock.family`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet`; `inet6` | Conditionally Required: [2] | @@ -87,7 +87,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` `net.sock.family` 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. @@ -112,7 +112,7 @@ It is recommended to also use the general [socket-level attributes][] - `net.soc **[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. @@ -123,22 +123,20 @@ This span type represents an outbound HTTP request. For an HTTP client span, `SpanKind` MUST be `Client`. -If set, `http.url` must be the originally requested URL, +If set, `url.full` must be the originally requested URL, before any HTTP-redirects that may happen when executing the request. | 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. | -| [`net.peer.name`](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 | -| [`net.peer.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. | +| [`net.peer.name`](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 | +| [`net.peer.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] | +| `url.full` | 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. [5] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | Recommended | -**[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 @@ -147,13 +145,14 @@ before any HTTP-redirects that may happen when executing the request. If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `net.peer.name` 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, `net.peer.name` 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, `net.peer.name` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). +**[4]:** If not default (`80` for `http` scheme, `443` for `https`). + +**[5]:** `url.full` 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/`. Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: -* `http.url` * [`net.peer.name`](span-general.md) * [`net.peer.port`](span-general.md) @@ -236,13 +235,15 @@ 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 | | `http.client_ip` | string | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [2] | `83.164.160.102` | Recommended | -| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | +| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | [`net.host.name`](span-general.md) | string | Name of the local HTTP server that received the request. [3] | `localhost` | Required | | [`net.host.port`](span-general.md) | int | Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] | | [`net.sock.host.addr`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host. | `192.168.0.1` | Opt-In | | [`net.sock.host.port`](span-general.md) | int | Local socket port number. | `35555` | Conditionally Required: [6] | +| `url.path` | string | The URI path | `/search` | Recommended | +| `url.query` | string | The URI query | `?q=OpenTelemetry#SemConv` | Recommended | +| `url.scheme` | string | The URI scheme 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. @@ -282,8 +283,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi 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` +* `http.request.method` * [`net.host.name`](span-general.md) * [`net.host.port`](span-general.md) @@ -300,33 +300,34 @@ As an example, if a browser request for `https://example.com:8080/webshop/articl Span name: `GET` -| Attribute name | Value | -| :------------------- | :-------------------------------------------------------| -| `http.method` | `"GET"` | -| `http.flavor` | `"1.1"` | -| `http.url` | `"https://example.com:8080/webshop/articles/4?s=1"` | -| `net.peer.name` | `example.com` | -| `net.peer.port` | 8080 | -| `net.sock.peer.addr` | `"192.0.2.5"` | -| `http.status_code` | `200` | +| Attribute name | Value | +| :-------------------------- | :-------------------------------------------------------| +| `http.request.method` | `"GET"` | +| `net.protocol.version` | ` "1.1"` | +| `url.full` | `"https://example.com:8080/webshop/articles/4?s=1"` | +| `net.peer.name` | `example.com` | +| `net.peer.port` | 8080 | +| `net.sock.peer.addr` | `"192.0.2.5"` | +| `http.response.status_code` | `200` | The corresponding server Span may look like this: Span name: `GET /webshop/articles/:article_id`. -| Attribute name | Value | -| :------------------- | :---------------------------------------------- | -| `http.method` | `"GET"` | -| `http.flavor` | `"1.1"` | -| `http.target` | `"/webshop/articles/4?s=1"` | -| `net.host.name` | `"example.com"` | -| `net.host.port` | `8080` | -| `http.scheme` | `"https"` | -| `http.route` | `"/webshop/articles/:article_id"` | -| `http.status_code` | `200` | -| `http.client_ip` | `"192.0.2.4"` | -| `net.sock.peer.addr` | `"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"` | +| Attribute name | Value | +| :-------------------------- | :---------------------------------------------- | +| `http.request.method` | `"GET"` | +| `http.protocol.version` | `"1.1"` | +| `url.path` | `"/webshop/articles/4"` | +| `url.query` | `"?s=1"` | +| `net.host.name` | `"example.com"` | +| `net.host.port` | `8080` | +| `url.scheme` | `"https"` | +| `http.route` | `"/webshop/articles/:article_id"` | +| `http.response.status_code` | `200` | +| `http.client_ip` | `"192.0.2.4"` | +| `net.sock.peer.addr` | `"192.0.2.5"` (the client goes through a proxy) | +| `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 9c2eb2ae99f..57562f83fa5 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -165,15 +165,13 @@ Function F: | Span Function | | `faas.trigger` | | `http` | | `cloud.account.id` | | `12345678912` | | `net.peer.name` | `foo.execute-api.us-east-1.amazonaws.com` | | -| `net.peer.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` | +| `http.request.method` | `GET` | `GET` | +| `user_agent.original` | `okhttp 3.0` | `okhttp 3.0` | +| `url.full` | `https://foo.execute-api.us-east-1.amazonaws.com/pets/10` | | +| `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)