diff --git a/semantic_conventions/http-common.yaml b/semantic_conventions/http-common.yaml index 3295762007..4e51e8765d 100644 --- a/semantic_conventions/http-common.yaml +++ b/semantic_conventions/http-common.yaml @@ -5,10 +5,57 @@ groups: prefix: http attributes: - id: request.method - type: string + type: + allow_custom_values: true + members: + - id: connect + value: "CONNECT" + brief: 'CONNECT method.' + - id: delete + value: "DELETE" + brief: 'DELETE method.' + - id: get + value: "GET" + brief: 'GET method.' + - id: head + value: "HEAD" + brief: 'HEAD method.' + - id: options + value: "OPTIONS" + brief: 'OPTIONS method.' + - id: patch + value: "PATCH" + brief: 'PATCH method.' + - id: post + value: "POST" + brief: 'POST method.' + - id: put + value: "PUT" + brief: 'PUT method.' + - id: trace + value: "TRACE" + brief: 'TRACE method.' + - id: other + value: "other" + brief: 'Any custom HTTP method that the instrumentation has no prior knowledge of.' requirement_level: required brief: 'HTTP request method.' examples: ["GET", "POST", "HEAD"] + 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. + If the HTTP request method is not known to the instrumentation, it MUST set the `http.request.method` attribute to `other` and SHOULD + populate the exact method passed by client on `http.request.original_method` attribute. + + HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly. + - id: request.original_method + type: string + requirement_level: + recommended: If and only if it's different than `http.request.method`. + brief: Original HTTP method sent by the client in the request line. + examples: ["GeT", "ACL", "foo"] - id: response.status_code type: int requirement_level: @@ -25,7 +72,7 @@ groups: - id: attributes.http.client prefix: http type: attribute_group - brief: 'HTTP Client spans attributes' + brief: 'HTTP Client attributes' attributes: - ref: server.address requirement_level: required @@ -51,7 +98,7 @@ groups: - id: attributes.http.server prefix: http type: attribute_group - brief: 'HTTP Server spans attributes' + brief: 'HTTP Server attributes' attributes: - id: route type: string diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index ca43d975f4..9ddcd6d9cc 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -70,20 +70,29 @@ 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.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.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | +| `http.request.method` | string | HTTP request method. [2] | `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] | +| [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | +| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Required | +| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | | `url.scheme` | 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. -**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[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. +If the HTTP request method is not known to the instrumentation, it MUST set the `http.request.method` attribute to `other` and SHOULD +populate the exact method passed by client on `http.request.original_method` attribute. -**[3]:** Determined by using the first of the following that applies +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly. + +**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[4]:** Determined by using the first of the following that applies - The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. @@ -93,14 +102,29 @@ SHOULD include the [application root](/specification/trace/semantic_conventions/ SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. -**[4]:** Determined by using the first of the following that applies +**[5]:** Determined by using the first of the following that applies - Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. - 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 -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). +**[6]:** If not default (`80` for `http` scheme, `443` for `https`). + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `CONNECT` | CONNECT method. | +| `DELETE` | DELETE method. | +| `GET` | GET method. | +| `HEAD` | HEAD method. | +| `OPTIONS` | OPTIONS method. | +| `PATCH` | PATCH method. | +| `POST` | POST method. | +| `PUT` | PUT method. | +| `TRACE` | TRACE method. | +| `other` | Any custom HTTP method that the instrumentation has no prior knowledge of. | ### Metric: `http.server.active_requests` @@ -116,12 +140,21 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `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] | +| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [2] | `example.com` | Required | +| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | `url.scheme` | 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 +**[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. +If the HTTP request method is not known to the instrumentation, it MUST set the `http.request.method` attribute to `other` and SHOULD +populate the exact method passed by client on `http.request.original_method` attribute. + +HTTP method names are case-sensitive and `http.request.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 - The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. @@ -131,14 +164,29 @@ This metric is optional. SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. -**[2]:** Determined by using the first of the following that applies +**[3]:** Determined by using the first of the following that applies - Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. - 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 -**[3]:** If not default (`80` for `http` scheme, `443` for `https`). +**[4]:** If not default (`80` for `http` scheme, `443` for `https`). + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `CONNECT` | CONNECT method. | +| `DELETE` | DELETE method. | +| `GET` | GET method. | +| `HEAD` | HEAD method. | +| `OPTIONS` | OPTIONS method. | +| `PATCH` | PATCH method. | +| `POST` | POST method. | +| `PUT` | PUT method. | +| `TRACE` | TRACE method. | +| `other` | Any custom HTTP method that the instrumentation has no prior knowledge of. | ### Metric: `http.server.request.size` @@ -155,20 +203,29 @@ This metric is optional. | 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.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | +| `http.request.method` | string | HTTP request method. [2] | `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] | +| [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | +| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Required | +| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | | `url.scheme` | 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. -**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[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. +If the HTTP request method is not known to the instrumentation, it MUST set the `http.request.method` attribute to `other` and SHOULD +populate the exact method passed by client on `http.request.original_method` attribute. -**[3]:** Determined by using the first of the following that applies +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly. + +**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[4]:** Determined by using the first of the following that applies - The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. @@ -178,14 +235,29 @@ SHOULD include the [application root](/specification/trace/semantic_conventions/ SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. -**[4]:** Determined by using the first of the following that applies +**[5]:** Determined by using the first of the following that applies - Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. - 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 -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). +**[6]:** If not default (`80` for `http` scheme, `443` for `https`). + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `CONNECT` | CONNECT method. | +| `DELETE` | DELETE method. | +| `GET` | GET method. | +| `HEAD` | HEAD method. | +| `OPTIONS` | OPTIONS method. | +| `PATCH` | PATCH method. | +| `POST` | POST method. | +| `PUT` | PUT method. | +| `TRACE` | TRACE method. | +| `other` | Any custom HTTP method that the instrumentation has no prior knowledge of. | ### Metric: `http.server.response.size` @@ -202,20 +274,29 @@ This metric is optional. | 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.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | +| `http.request.method` | string | HTTP request method. [2] | `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] | +| [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | +| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Required | +| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | | `url.scheme` | 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. -**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[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. +If the HTTP request method is not known to the instrumentation, it MUST set the `http.request.method` attribute to `other` and SHOULD +populate the exact method passed by client on `http.request.original_method` attribute. -**[3]:** Determined by using the first of the following that applies +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly. + +**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[4]:** Determined by using the first of the following that applies - The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. @@ -225,14 +306,29 @@ SHOULD include the [application root](/specification/trace/semantic_conventions/ SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. -**[4]:** Determined by using the first of the following that applies +**[5]:** Determined by using the first of the following that applies - Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. - 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 -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). +**[6]:** If not default (`80` for `http` scheme, `443` for `https`). + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `CONNECT` | CONNECT method. | +| `DELETE` | DELETE method. | +| `GET` | GET method. | +| `HEAD` | HEAD method. | +| `OPTIONS` | OPTIONS method. | +| `PATCH` | PATCH method. | +| `POST` | POST method. | +| `PUT` | PUT method. | +| `TRACE` | TRACE method. | +| `other` | Any custom HTTP method that the instrumentation has no prior knowledge of. | ## HTTP Client @@ -254,17 +350,26 @@ 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.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | +| `http.request.method` | string | HTTP request method. [1] | `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 | -| [`server.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] | +| [`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 | 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`](../../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. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | | [`server.socket.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. | -**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[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. +If the HTTP request method is not known to the instrumentation, it MUST set the `http.request.method` attribute to `other` and SHOULD +populate the exact method passed by client on `http.request.original_method` attribute. -**[2]:** Determined by using the first of the following that applies +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly. + +**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[3]:** 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 @@ -272,9 +377,24 @@ 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, SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[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]:** 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`). + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `CONNECT` | CONNECT method. | +| `DELETE` | DELETE method. | +| `GET` | GET method. | +| `HEAD` | HEAD method. | +| `OPTIONS` | OPTIONS method. | +| `PATCH` | PATCH method. | +| `POST` | POST method. | +| `PUT` | PUT method. | +| `TRACE` | TRACE method. | +| `other` | Any custom HTTP method that the instrumentation has no prior knowledge of. | ### Metric: `http.client.request.size` @@ -290,17 +410,26 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | +| `http.request.method` | string | HTTP request method. [1] | `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 | -| [`server.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] | +| [`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 | 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`](../../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. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | | [`server.socket.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. | -**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[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. +If the HTTP request method is not known to the instrumentation, it MUST set the `http.request.method` attribute to `other` and SHOULD +populate the exact method passed by client on `http.request.original_method` attribute. -**[2]:** Determined by using the first of the following that applies +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly. + +**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[3]:** 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 @@ -308,9 +437,24 @@ This metric is optional. SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[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]:** 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`). + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `CONNECT` | CONNECT method. | +| `DELETE` | DELETE method. | +| `GET` | GET method. | +| `HEAD` | HEAD method. | +| `OPTIONS` | OPTIONS method. | +| `PATCH` | PATCH method. | +| `POST` | POST method. | +| `PUT` | PUT method. | +| `TRACE` | TRACE method. | +| `other` | Any custom HTTP method that the instrumentation has no prior knowledge of. | ### Metric: `http.client.response.size` @@ -326,17 +470,26 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | +| `http.request.method` | string | HTTP request method. [1] | `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 | -| [`server.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] | +| [`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 | 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`](../../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. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | | [`server.socket.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. | -**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[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. +If the HTTP request method is not known to the instrumentation, it MUST set the `http.request.method` attribute to `other` and SHOULD +populate the exact method passed by client on `http.request.original_method` attribute. -**[2]:** Determined by using the first of the following that applies +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly. + +**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[3]:** 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 @@ -344,7 +497,22 @@ This metric is optional. SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[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]:** 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`). + +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `CONNECT` | CONNECT method. | +| `DELETE` | DELETE method. | +| `GET` | GET method. | +| `HEAD` | HEAD method. | +| `OPTIONS` | OPTIONS method. | +| `PATCH` | PATCH method. | +| `POST` | POST method. | +| `PUT` | PUT method. | +| `TRACE` | TRACE method. | +| `other` | Any custom HTTP method that the instrumentation has no prior knowledge of. | diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index c1b9c543b7..fedee88b30 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -89,24 +89,51 @@ sections below. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| `http.request.original_method` | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | Recommended: [1] | | `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 | +| `http.request.method` | string | HTTP request method. [2] | `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] | +| [`network.protocol.version`](span-general.md) | string | Version of the application layer protocol used. See note below. [3] | `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: [4] | | [`network.type`](span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | | `user_agent.original` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended | -**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[1]:** If and only if it's different than `http.request.method`. -**[2]:** If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`). +**[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. +If the HTTP request method is not known to the instrumentation, it MUST set the `http.request.method` attribute to `other` and SHOULD +populate the exact method passed by client on `http.request.original_method` attribute. + +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly. + +**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[4]:** If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`). Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: * `http.request.method` +`http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `CONNECT` | CONNECT method. | +| `DELETE` | DELETE method. | +| `GET` | GET method. | +| `HEAD` | HEAD method. | +| `OPTIONS` | OPTIONS method. | +| `PATCH` | PATCH method. | +| `POST` | POST method. | +| `PUT` | PUT method. | +| `TRACE` | TRACE method. | +| `other` | Any custom HTTP method that the instrumentation has no prior knowledge of. | + `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. | Value | Description |