From 789d5da6bd2a293b9ad4546fbe3bf29f43d846de Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 8 May 2023 13:01:23 -0700 Subject: [PATCH] add note on method case-sensitivity --- semantic_conventions/http-common.yaml | 4 +- .../semantic_conventions/http-metrics.md | 160 +++++++++++------- .../trace/semantic_conventions/http.md | 56 +++--- 3 files changed, 135 insertions(+), 85 deletions(-) diff --git a/semantic_conventions/http-common.yaml b/semantic_conventions/http-common.yaml index 056a3d31b39..d88da70a959 100644 --- a/semantic_conventions/http-common.yaml +++ b/semantic_conventions/http-common.yaml @@ -41,12 +41,14 @@ groups: requirement_level: required brief: 'HTTP request method.' examples: ["GET", "POST", "HEAD"] - note: > + note: | HTTP request method SHOULD be one of the methods defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) or the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). Instrumentation MAY additionally support the closed set of custom HTTP methods defined in [HTTP method registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml) or a private registry. Instrumentation MUST set the `http.method` attribute to `OTHER` if the HTTP request method is not known to the instrumentation. + + HTTP method names are case-sensitive and `http.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly. - id: status_code type: int requirement_level: diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index e9a4b5b0163..43338f3a3c3 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -69,19 +69,25 @@ 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. [2] | `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. | -| [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `localhost` | Required | -| [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] | -| [`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. [6] | `3.1.1` | Recommended | +| `http.scheme` | string | **Stable**
The URI scheme identifying the used protocol. | `http`; `https` | Required | +| `http.route` | string | **Stable**
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 | **Stable**
HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | +| `http.status_code` | int | **Stable**
[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 | **Stable**
Name of the local HTTP server that received the request. [3] | `localhost` | Required | +| [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | **Stable**
Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] | +| [`net.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | **Stable**
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 | **Stable**
Version of the application layer protocol used. See note below. [6] | `3.1.1` | Recommended | **[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. -**[2]:** HTTP request method SHOULD be one of the methods defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) or the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). Instrumentation MAY additionally support the closed set of custom HTTP methods defined in [HTTP method registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml) or a private registry. Instrumentation MUST set the `http.method` attribute to `OTHER` if the HTTP request method is not known to the instrumentation. +**[2]:** HTTP request method SHOULD be one of the methods defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +or the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). +Instrumentation MAY additionally support the closed set of custom HTTP methods defined in +[HTTP method registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml) or a private registry. +Instrumentation MUST set the `http.method` attribute to `OTHER` if the HTTP request method is not known to the instrumentation. + +HTTP method names are case-sensitive and `http.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly. **[3]:** Determined by using the first of the following that applies @@ -133,12 +139,18 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | -| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | -| [`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] | +| `http.method` | string | **Stable**
HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| `http.scheme` | string | **Stable**
The URI scheme identifying the used protocol. | `http`; `https` | Required | +| [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | **Stable**
Name of the local HTTP server that received the request. [2] | `localhost` | Required | +| [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | **Stable**
Port of the local HTTP server that received the request. [3] | `8080` | Conditionally Required: [4] | + +**[1]:** HTTP request method SHOULD be one of the methods defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +or the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). +Instrumentation MAY additionally support the closed set of custom HTTP methods defined in +[HTTP method registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml) or a private registry. +Instrumentation MUST set the `http.method` attribute to `OTHER` if the HTTP request method is not known to the instrumentation. -**[1]:** HTTP request method SHOULD be one of the methods defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) or the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). Instrumentation MAY additionally support the closed set of custom HTTP methods defined in [HTTP method registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml) or a private registry. Instrumentation MUST set the `http.method` attribute to `OTHER` if the HTTP request method is not known to the instrumentation. +HTTP method names are case-sensitive and `http.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly. **[2]:** Determined by using the first of the following that applies @@ -188,19 +200,25 @@ 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. [2] | `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. | -| [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `localhost` | Required | -| [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] | -| [`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. [6] | `3.1.1` | Recommended | +| `http.scheme` | string | **Stable**
The URI scheme identifying the used protocol. | `http`; `https` | Required | +| `http.route` | string | **Stable**
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 | **Stable**
HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | +| `http.status_code` | int | **Stable**
[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 | **Stable**
Name of the local HTTP server that received the request. [3] | `localhost` | Required | +| [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | **Stable**
Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] | +| [`net.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | **Stable**
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 | **Stable**
Version of the application layer protocol used. See note below. [6] | `3.1.1` | Recommended | **[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. -**[2]:** HTTP request method SHOULD be one of the methods defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) or the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). Instrumentation MAY additionally support the closed set of custom HTTP methods defined in [HTTP method registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml) or a private registry. Instrumentation MUST set the `http.method` attribute to `OTHER` if the HTTP request method is not known to the instrumentation. +**[2]:** HTTP request method SHOULD be one of the methods defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +or the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). +Instrumentation MAY additionally support the closed set of custom HTTP methods defined in +[HTTP method registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml) or a private registry. +Instrumentation MUST set the `http.method` attribute to `OTHER` if the HTTP request method is not known to the instrumentation. + +HTTP method names are case-sensitive and `http.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly. **[3]:** Determined by using the first of the following that applies @@ -252,19 +270,25 @@ 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. [2] | `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. | -| [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `localhost` | Required | -| [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] | -| [`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. [6] | `3.1.1` | Recommended | +| `http.scheme` | string | **Stable**
The URI scheme identifying the used protocol. | `http`; `https` | Required | +| `http.route` | string | **Stable**
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 | **Stable**
HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | +| `http.status_code` | int | **Stable**
[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 | **Stable**
Name of the local HTTP server that received the request. [3] | `localhost` | Required | +| [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | **Stable**
Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] | +| [`net.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | **Stable**
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 | **Stable**
Version of the application layer protocol used. See note below. [6] | `3.1.1` | Recommended | **[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. -**[2]:** HTTP request method SHOULD be one of the methods defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) or the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). Instrumentation MAY additionally support the closed set of custom HTTP methods defined in [HTTP method registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml) or a private registry. Instrumentation MUST set the `http.method` attribute to `OTHER` if the HTTP request method is not known to the instrumentation. +**[2]:** HTTP request method SHOULD be one of the methods defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +or the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). +Instrumentation MAY additionally support the closed set of custom HTTP methods defined in +[HTTP method registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml) or a private registry. +Instrumentation MUST set the `http.method` attribute to `OTHER` if the HTTP request method is not known to the instrumentation. + +HTTP method names are case-sensitive and `http.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly. **[3]:** Determined by using the first of the following that applies @@ -322,15 +346,21 @@ 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. [1] | `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. | -| [`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. [2] | `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. [3] | `80`; `8080`; `443` | 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 | -| [`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 | - -**[1]:** HTTP request method SHOULD be one of the methods defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) or the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). Instrumentation MAY additionally support the closed set of custom HTTP methods defined in [HTTP method registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml) or a private registry. Instrumentation MUST set the `http.method` attribute to `OTHER` if the HTTP request method is not known to the instrumentation. +| `http.method` | string | **Stable**
HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| `http.status_code` | int | **Stable**
[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 | **Stable**
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`](../../trace/semantic_conventions/span-general.md) | int | **Stable**
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] | +| [`net.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | **Stable**
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 | **Stable**
Version of the application layer protocol used. See note below. [5] | `3.1.1` | Recommended | +| [`net.sock.peer.addr`](../../trace/semantic_conventions/span-general.md) | string | **Stable**
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 | + +**[1]:** HTTP request method SHOULD be one of the methods defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +or the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). +Instrumentation MAY additionally support the closed set of custom HTTP methods defined in +[HTTP method registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml) or a private registry. +Instrumentation MUST set the `http.method` attribute to `OTHER` if the HTTP request method is not known to the instrumentation. + +HTTP method names are case-sensitive and `http.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly. **[2]:** Determined by using the first of the following that applies @@ -375,15 +405,21 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.method` | string | HTTP request method. [1] | `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. | -| [`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. [2] | `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. [3] | `80`; `8080`; `443` | 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 | -| [`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 | - -**[1]:** HTTP request method SHOULD be one of the methods defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) or the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). Instrumentation MAY additionally support the closed set of custom HTTP methods defined in [HTTP method registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml) or a private registry. Instrumentation MUST set the `http.method` attribute to `OTHER` if the HTTP request method is not known to the instrumentation. +| `http.method` | string | **Stable**
HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| `http.status_code` | int | **Stable**
[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 | **Stable**
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`](../../trace/semantic_conventions/span-general.md) | int | **Stable**
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] | +| [`net.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | **Stable**
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 | **Stable**
Version of the application layer protocol used. See note below. [5] | `3.1.1` | Recommended | +| [`net.sock.peer.addr`](../../trace/semantic_conventions/span-general.md) | string | **Stable**
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 | + +**[1]:** HTTP request method SHOULD be one of the methods defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +or the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). +Instrumentation MAY additionally support the closed set of custom HTTP methods defined in +[HTTP method registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml) or a private registry. +Instrumentation MUST set the `http.method` attribute to `OTHER` if the HTTP request method is not known to the instrumentation. + +HTTP method names are case-sensitive and `http.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly. **[2]:** Determined by using the first of the following that applies @@ -428,15 +464,21 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.method` | string | HTTP request method. [1] | `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. | -| [`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. [2] | `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. [3] | `80`; `8080`; `443` | 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 | -| [`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 | - -**[1]:** HTTP request method SHOULD be one of the methods defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) or the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). Instrumentation MAY additionally support the closed set of custom HTTP methods defined in [HTTP method registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml) or a private registry. Instrumentation MUST set the `http.method` attribute to `OTHER` if the HTTP request method is not known to the instrumentation. +| `http.method` | string | **Stable**
HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| `http.status_code` | int | **Stable**
[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 | **Stable**
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`](../../trace/semantic_conventions/span-general.md) | int | **Stable**
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] | +| [`net.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | **Stable**
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 | **Stable**
Version of the application layer protocol used. See note below. [5] | `3.1.1` | Recommended | +| [`net.sock.peer.addr`](../../trace/semantic_conventions/span-general.md) | string | **Stable**
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 | + +**[1]:** HTTP request method SHOULD be one of the methods defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +or the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). +Instrumentation MAY additionally support the closed set of custom HTTP methods defined in +[HTTP method registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml) or a private registry. +Instrumentation MUST set the `http.method` attribute to `OTHER` if the HTTP request method is not known to the instrumentation. + +HTTP method names are case-sensitive and `http.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly. **[2]:** Determined by using the first of the following that applies diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index cb32bbc91bd..4ca53fe900b 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -89,19 +89,25 @@ 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. [1] | `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. [2] | `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: [3] | -| [`net.sock.peer.addr`](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 | -| [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [4] | -| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [5] | -| `user_agent.original` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended | - -**[1]:** HTTP request method SHOULD be one of the methods defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) or the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). Instrumentation MAY additionally support the closed set of custom HTTP methods defined in [HTTP method registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml) or a private registry. Instrumentation MUST set the `http.method` attribute to `OTHER` if the HTTP request method is not known to the instrumentation. +| `http.status_code` | int | **Stable**
[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 | **Stable**
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 | **Stable**
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 | **Stable**
HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| [`net.protocol.name`](span-general.md) | string | **Stable**
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 | **Stable**
Version of the application layer protocol used. See note below. [2] | `1.0`; `1.1`; `2.0` | Recommended | +| [`net.sock.family`](span-general.md) | string | **Stable**
Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet`; `inet6` | Conditionally Required: [3] | +| [`net.sock.peer.addr`](span-general.md) | string | **Stable**
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 | +| [`net.sock.peer.name`](span-general.md) | string | **Stable**
Remote socket peer name. | `proxy.example.com` | Recommended: [4] | +| [`net.sock.peer.port`](span-general.md) | int | **Stable**
Remote socket peer port. | `16456` | Recommended: [5] | +| `user_agent.original` | string | **Stable**
Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended | + +**[1]:** HTTP request method SHOULD be one of the methods defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +or the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). +Instrumentation MAY additionally support the closed set of custom HTTP methods defined in +[HTTP method registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml) or a private registry. +Instrumentation MUST set the `http.method` attribute to `OTHER` if the HTTP request method is not known to the instrumentation. + +HTTP method names are case-sensitive and `http.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly. **[2]:** `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`. @@ -175,10 +181,10 @@ 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. | -| [`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.url` | string | **Stable**
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 | **Stable**
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 | **Stable**
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 | **Stable**
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] | **[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/`. @@ -282,14 +288,14 @@ 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 | -| [`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] | +| `http.route` | string | **Stable**
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 | **Stable**
The full request target as passed in a HTTP request line or equivalent. | `/users/12314/?q=ddds` | Required | +| `http.client_ip` | string | **Stable**
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 | **Stable**
The URI scheme identifying the used protocol. | `http`; `https` | Required | +| [`net.host.name`](span-general.md) | string | **Stable**
Name of the local HTTP server that received the request. [3] | `localhost` | Required | +| [`net.host.port`](span-general.md) | int | **Stable**
Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] | +| [`net.sock.host.addr`](span-general.md) | string | **Stable**
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 | **Stable**
Local socket port number. | `35555` | Conditionally Required: [6] | **[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.