From bf38c75f7dc0e33b63b8429027a375c0d26989da Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Thu, 7 Mar 2024 11:37:55 +0100 Subject: [PATCH 1/5] Move HTTP client metrics out of .NET conventions --- .../move-dotnet-metrics-experimental.yaml | 5 + docs/attributes-registry/http.md | 8 + docs/dotnet/dotnet-http-metrics.md | 20 +- docs/http/http-metrics.md | 173 ++++++++++++++++++ model/metrics/dotnet/dotnet-http.yaml | 111 ----------- model/metrics/http.yaml | 144 +++++++++++++++ model/registry/http.yaml | 12 ++ 7 files changed, 346 insertions(+), 127 deletions(-) create mode 100755 .chloggen/move-dotnet-metrics-experimental.yaml diff --git a/.chloggen/move-dotnet-metrics-experimental.yaml b/.chloggen/move-dotnet-metrics-experimental.yaml new file mode 100755 index 0000000000..2671cef5e6 --- /dev/null +++ b/.chloggen/move-dotnet-metrics-experimental.yaml @@ -0,0 +1,5 @@ +change_type: enhancement + +component: http +note: Extracts common HTTP client metrics from .NET conventions. +issues: [800] diff --git a/docs/attributes-registry/http.md b/docs/attributes-registry/http.md index 8b7665bb9c..9d1b311165 100644 --- a/docs/attributes-registry/http.md +++ b/docs/attributes-registry/http.md @@ -8,6 +8,7 @@ | Attribute | Type | Description | Examples | |---|---|---|---| +| `http.connection.state` | string | State of the HTTP connection in the HTTP connection pool. | `active`; `idle` | | `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` | | `http.request.header.` | string[] | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [1] | `http.request.header.content-type=["application/json"]`; `http.request.header.x-forwarded-for=["1.2.3.4", "1.2.3.5"]` | | `http.request.method` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
HTTP request method. [2] | `GET`; `POST`; `HEAD` | @@ -46,6 +47,13 @@ The attribute value MUST consist of either multiple header values as an array of **[5]:** 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](/docs/http/http-spans.md#http-server-definitions) if there is one. +`http.connection.state` MUST be one of the following: + +| Value | Description | +|---|---| +| `active` | active state. | +| `idle` | idle state. | + `http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. | Value | Description | diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index 47bf1a71b7..e4e4f7c28c 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -43,15 +43,13 @@ Notes: ### Metric: `http.client.open_connections` - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | | `http.client.open_connections` | UpDownCounter | `{connection}` | Number of outbound HTTP connections that are currently active or idle on the client. [1] | **[1]:** Meter name: `System.Net.Http`; Added in: .NET 8.0 - - | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.connection.state` | string | State of the HTTP connection in the HTTP connection pool. | `active`; `idle` | Required | @@ -75,7 +73,6 @@ Notes: |---|---| | `active` | active state. | | `idle` | idle state. | - ### Metric: `http.client.connection.duration` @@ -83,15 +80,13 @@ this metric SHOULD be specified with [`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | | `http.client.connection.duration` | Histogram | `s` | The duration of the successfully established outbound HTTP connections. [1] | **[1]:** Meter name: `System.Net.Http`; Added in: .NET 8.0 - - | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | @@ -107,7 +102,6 @@ of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. **[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[4]:** If not the default (`80` for `http` scheme, `443` for `https`). - ### Metric: `http.client.request.time_in_queue` @@ -115,15 +109,13 @@ this metric SHOULD be specified with [`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | | `http.client.request.time_in_queue` | Histogram | `s` | The amount of time requests spent on a queue waiting for an available connection. [1] | **[1]:** Meter name: `System.Net.Http`; Added in: .NET 8.0 - - | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | @@ -157,19 +149,16 @@ If the HTTP request method isn't known, it sets the `http.request.method` attrib | `PUT` | PUT method. | | `TRACE` | TRACE method. | | `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | - ### Metric: `http.client.active_requests` - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | | `http.client.active_requests` | UpDownCounter | `{request}` | Number of active HTTP requests. [1] | **[1]:** Meter name: `System.Net.Http`; Added in: .NET 8.0 - - | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | @@ -200,7 +189,6 @@ If the HTTP request method isn't known, it sets the `http.request.method` attrib | `PUT` | PUT method. | | `TRACE` | TRACE method. | | `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | - ## HTTP server diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index aed8fc81dc..73b4b073c2 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -23,6 +23,10 @@ operations. By adding HTTP attributes to metric events it allows for finely tune - [Metric: `http.client.request.duration`](#metric-httpclientrequestduration) - [Metric: `http.client.request.body.size`](#metric-httpclientrequestbodysize) - [Metric: `http.client.response.body.size`](#metric-httpclientresponsebodysize) + - [Metric: `http.client.open_connections`](#metric-httpclientopen_connections) + - [Metric: `http.client.connection.duration`](#metric-httpclientconnectionduration) + - [Metric: `http.client.request.time_in_queue`](#metric-httpclientrequesttime_in_queue) + - [Metric: `http.client.active_requests`](#metric-httpclientactive_requests) @@ -701,4 +705,173 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original | `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | +### Metric: `http.client.open_connections` + +**Status**: [Experimental][DocumentStatus] + +This metric is optional. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.open_connections` | UpDownCounter | `{connection}` | Number of outbound HTTP connections that are currently active or idle on the client. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`http.connection.state`](../attributes-registry/http.md) | string | State of the HTTP connection in the HTTP connection pool. | `active`; `idle` | Required | +| [`network.peer.address`](../attributes-registry/network.md) | string | Remote IP address of the socket connection. | `10.1.2.80` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | HTTP protocol version of the connection in the connection pool. [1] | `1.1`; `2`; `3` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.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.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | + +**[1]:** HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. So, the `network.protocol.version` value reported on connection metrics is different than the one reported on request-level metrics or spans for HTTP 1.0 requests. + +**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. + +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[4]:** If not the default (`80` for `http` scheme, `443` for `https`). + +`http.connection.state` MUST be one of the following: + +| Value | Description | +|---|---| +| `active` | active state. | +| `idle` | idle state. | + + +### Metric: `http.client.connection.duration` + +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advisory-parameters) +of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`. + +**Status**: [Experimental][DocumentStatus] + +This metric is optional. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.connection.duration` | Histogram | `s` | The duration of the successfully established outbound HTTP connections. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | HTTP protocol version of the connection in the connection pool. [1] | `1.1`; `2`; `3` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.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.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | + +**[1]:** HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. So, the `network.protocol.version` value reported on connection metrics is different than the one reported on request-level metrics or spans for HTTP 1.0 requests. + +**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. + +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[4]:** If not the default (`80` for `http` scheme, `443` for `https`). + + +### Metric: `http.client.request.time_in_queue` + +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advisory-parameters) +of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. + +**Status**: [Experimental][DocumentStatus] + +This metric is optional. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.request.time_in_queue` | Histogram | `s` | The amount of time requests spent on a queue waiting for an available connection. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | HTTP protocol version of the connection in the connection pool. [2] | `1.1`; `2`; `3` | Recommended | +| [`server.address`](../attributes-registry/server.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`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.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] | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | + +**[1]:** HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). +If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. It's not possible at the moment to override the list of known HTTP methods. + +**[2]:** HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. So, the `network.protocol.version` value reported on connection metrics is different than the one reported on request-level metrics or spans for HTTP 1.0 requests. + +**[3]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. + +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[5]:** If not the 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 HTTP method that the instrumentation has no prior knowledge of. | + + +### Metric: `http.client.active_requests` + +**Status**: [Experimental][DocumentStatus] + +This metric is optional. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.active_requests` | UpDownCounter | `{request}` | Number of active HTTP requests. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../attributes-registry/server.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.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | + +**[1]:** HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). +If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. It's not possible at the moment to override the list of known HTTP methods. + +**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. + +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. + +**[4]:** If not the 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 HTTP method that the instrumentation has no prior knowledge of. | + + [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/model/metrics/dotnet/dotnet-http.yaml b/model/metrics/dotnet/dotnet-http.yaml index 9a326bb5d7..e390bd9031 100644 --- a/model/metrics/dotnet/dotnet-http.yaml +++ b/model/metrics/dotnet/dotnet-http.yaml @@ -36,114 +36,3 @@ groups: See [SocketError](https://learn.microsoft.com/dotnet/api/system.net.sockets.socketerror) for more details. examples: ["host_not_found", "no_recovery", "System.Net.Sockets.SocketException"] - - - id: dotnet.http.client.common.attributes - type: attribute_group - brief: "Common HTTP client attributes" - attributes: - - ref: url.scheme - examples: ['http', 'https', 'ftp'] - - ref: server.address - requirement_level: required - brief: > - Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: > - If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then - `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. - - ref: server.port - requirement_level: - conditionally_required: If not the default (`80` for `http` scheme, `443` for `https`). - brief: > - Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - - - id: dotnet.http.client.connection.attributes - type: attribute_group - brief: "Common HTTP client attributes" - extends: dotnet.http.client.common.attributes - attributes: - - ref: network.protocol.version - brief: HTTP protocol version of the connection in the connection pool. - note: > - HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. - So, the `network.protocol.version` value reported on connection metrics is different than the one reported - on request-level metrics or spans for HTTP 1.0 requests. - examples: ["1.1", "2", "3"] - - - id: dotnet.http.client.request.attributes - type: attribute_group - brief: "Common HTTP client attributes" - extends: dotnet.http.client.common.attributes - attributes: - - ref: http.request.method - note: > - HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) - and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). - - If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. - It's not possible at the moment to override the list of known HTTP methods. - - - id: metric.dotnet.http.client.open_connections - type: metric - metric_name: http.client.open_connections - brief: "Number of outbound HTTP connections that are currently active or idle on the client." - instrument: updowncounter - unit: "{connection}" - note: > - Meter name: `System.Net.Http`; Added in: .NET 8.0 - extends: dotnet.http.client.connection.attributes - attributes: - - id: http.connection.state - type: - members: - - id: active - value: "active" - brief: 'active state.' - - id: idle - value: "idle" - brief: 'idle state.' - brief: State of the HTTP connection in the HTTP connection pool. - requirement_level: required - examples: ["active", "idle"] - - ref: network.peer.address - brief: Remote IP address of the socket connection. - examples: ["10.1.2.80"] - - - id: metric.dotnet.http.client.connection.duration - type: metric - metric_name: http.client.connection.duration - brief: "The duration of the successfully established outbound HTTP connections." - instrument: histogram - unit: "s" - note: > - Meter name: `System.Net.Http`; Added in: .NET 8.0 - extends: dotnet.http.client.connection.attributes - attributes: - - ref: network.peer.address - - - id: metric.dotnet.http.client.active_requests - type: metric - metric_name: http.client.active_requests - brief: "Number of active HTTP requests." - instrument: updowncounter - unit: "{request}" - note: > - Meter name: `System.Net.Http`; Added in: .NET 8.0 - extends: dotnet.http.client.request.attributes - - - id: metric.dotnet.http.client.request.time_in_queue - type: metric - metric_name: http.client.request.time_in_queue - brief: "The amount of time requests spent on a queue waiting for an available connection." - instrument: histogram - unit: "s" - note: > - Meter name: `System.Net.Http`; Added in: .NET 8.0 - extends: dotnet.http.client.connection.attributes - attributes: - - ref: http.request.method - note: > - HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) - and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). - - If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. - It's not possible at the moment to override the list of known HTTP methods. diff --git a/model/metrics/http.yaml b/model/metrics/http.yaml index d22e7836b8..c8324dc984 100644 --- a/model/metrics/http.yaml +++ b/model/metrics/http.yaml @@ -124,3 +124,147 @@ groups: 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. extends: metric_attributes.http.client + + - id: metric.http.client.open_connections + type: metric + metric_name: http.client.open_connections + stability: experimental + brief: "Number of outbound HTTP connections that are currently active or idle on the client." + instrument: updowncounter + unit: "{connection}" + attributes: + - ref: http.connection.state + requirement_level: required + - ref: network.peer.address + requirement_level: recommended + brief: Remote IP address of the socket connection. + examples: ["10.1.2.80"] + - ref: network.protocol.version + requirement_level: recommended + brief: HTTP protocol version of the connection in the connection pool. + note: > + HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. + So, the `network.protocol.version` value reported on connection metrics is different than the one reported + on request-level metrics or spans for HTTP 1.0 requests. + examples: ["1.1", "2", "3"] + - ref: server.address + requirement_level: required + brief: > + Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + note: > + If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then + `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. + - ref: server.port + requirement_level: + conditionally_required: If not the default (`80` for `http` scheme, `443` for `https`). + brief: > + Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + - ref: url.scheme + requirement_level: recommended + examples: ['http', 'https', 'ftp'] + + - id: metric.http.client.connection.duration + type: metric + metric_name: http.client.connection.duration + stability: experimental + brief: "The duration of the successfully established outbound HTTP connections." + instrument: histogram + unit: "s" + attributes: + - ref: network.peer.address + requirement_level: recommended + - ref: network.protocol.version + requirement_level: recommended + brief: HTTP protocol version of the connection in the connection pool. + note: > + HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. + So, the `network.protocol.version` value reported on connection metrics is different than the one reported + on request-level metrics or spans for HTTP 1.0 requests. + examples: ["1.1", "2", "3"] + - ref: server.address + requirement_level: required + brief: > + Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + note: > + If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then + `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. + - ref: server.port + requirement_level: + conditionally_required: If not the default (`80` for `http` scheme, `443` for `https`). + brief: > + Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + - ref: url.scheme + requirement_level: recommended + examples: ['http', 'https', 'ftp'] + + - id: metric.http.client.request.time_in_queue + type: metric + metric_name: http.client.request.time_in_queue + stability: experimental + brief: "The amount of time requests spent on a queue waiting for an available connection." + instrument: histogram + unit: "s" + attributes: + - ref: http.request.method + requirement_level: recommended + note: > + HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) + and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). + + If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. + It's not possible at the moment to override the list of known HTTP methods. + - ref: network.protocol.version + requirement_level: recommended + brief: HTTP protocol version of the connection in the connection pool. + note: > + HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. + So, the `network.protocol.version` value reported on connection metrics is different than the one reported + on request-level metrics or spans for HTTP 1.0 requests. + examples: ["1.1", "2", "3"] + - ref: server.address + requirement_level: required + brief: > + Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + note: > + If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then + `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. + - ref: server.port + requirement_level: + conditionally_required: If not the default (`80` for `http` scheme, `443` for `https`). + brief: > + Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + - ref: url.scheme + requirement_level: recommended + examples: ['http', 'https', 'ftp'] + + - id: metric.http.client.active_requests + type: metric + metric_name: http.client.active_requests + stability: experimental + brief: "Number of active HTTP requests." + instrument: updowncounter + unit: "{request}" + attributes: + - ref: http.request.method + requirement_level: recommended + note: > + HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) + and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). + + If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. + It's not possible at the moment to override the list of known HTTP methods. + - ref: server.address + requirement_level: required + brief: > + Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + note: > + If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then + `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. + - ref: server.port + requirement_level: + conditionally_required: If not the default (`80` for `http` scheme, `443` for `https`). + brief: > + Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + - ref: url.scheme + requirement_level: recommended + examples: ['http', 'https', 'ftp'] diff --git a/model/registry/http.yaml b/model/registry/http.yaml index 2cb8e8b894..c8bd9a0839 100644 --- a/model/registry/http.yaml +++ b/model/registry/http.yaml @@ -133,3 +133,15 @@ groups: 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](/docs/http/http-spans.md#http-server-definitions) if there is one. + - id: connection.state + type: + members: + - id: active + value: "active" + brief: 'active state.' + - id: idle + value: "idle" + brief: 'idle state.' + brief: State of the HTTP connection in the HTTP connection pool. + stability: experimental + examples: ["active", "idle"] From 8022f6af3dd40cb2d6aec39979b67f22ec24cb5d Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Thu, 7 Mar 2024 15:58:55 +0100 Subject: [PATCH 2/5] Remove space --- .chloggen/move-dotnet-metrics-experimental.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/.chloggen/move-dotnet-metrics-experimental.yaml b/.chloggen/move-dotnet-metrics-experimental.yaml index 2671cef5e6..f2812b3aa1 100755 --- a/.chloggen/move-dotnet-metrics-experimental.yaml +++ b/.chloggen/move-dotnet-metrics-experimental.yaml @@ -1,5 +1,4 @@ change_type: enhancement - component: http note: Extracts common HTTP client metrics from .NET conventions. issues: [800] From 12ff234f3880b17f071be2a8a12d38aa041d7456 Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Fri, 8 Mar 2024 11:42:54 +0100 Subject: [PATCH 3/5] PR suggestions --- docs/attributes-registry/http.md | 2 +- docs/http/http-metrics.md | 88 +++++++++++++++++++------------- model/metrics/http.yaml | 84 +++++------------------------- model/registry/http.yaml | 1 + 4 files changed, 66 insertions(+), 109 deletions(-) diff --git a/docs/attributes-registry/http.md b/docs/attributes-registry/http.md index 9d1b311165..9363bed226 100644 --- a/docs/attributes-registry/http.md +++ b/docs/attributes-registry/http.md @@ -47,7 +47,7 @@ The attribute value MUST consist of either multiple header values as an array of **[5]:** 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](/docs/http/http-spans.md#http-server-definitions) if there is one. -`http.connection.state` MUST be one of the following: +`http.connection.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. | Value | Description | |---|---| diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 73b4b073c2..50434e5757 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -721,21 +721,19 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`http.connection.state`](../attributes-registry/http.md) | string | State of the HTTP connection in the HTTP connection pool. | `active`; `idle` | Required | -| [`network.peer.address`](../attributes-registry/network.md) | string | Remote IP address of the socket connection. | `10.1.2.80` | Recommended | -| [`network.protocol.version`](../attributes-registry/network.md) | string | HTTP protocol version of the connection in the connection pool. [1] | `1.1`; `2`; `3` | Recommended | -| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../attributes-registry/server.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.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | +| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `3.1.1` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.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` | Required | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Opt-In | -**[1]:** HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. So, the `network.protocol.version` value reported on connection metrics is different than the one reported on request-level metrics or spans for HTTP 1.0 requests. +**[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 has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. +**[2]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. **[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -**[4]:** If not the default (`80` for `http` scheme, `443` for `https`). - -`http.connection.state` MUST be one of the following: +`http.connection.state` 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 | |---|---| @@ -763,18 +761,16 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`network.protocol.version`](../attributes-registry/network.md) | string | HTTP protocol version of the connection in the connection pool. [1] | `1.1`; `2`; `3` | Recommended | -| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../attributes-registry/server.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.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `3.1.1` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.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` | Required | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Opt-In | -**[1]:** HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. So, the `network.protocol.version` value reported on connection metrics is different than the one reported on request-level metrics or spans for HTTP 1.0 requests. +**[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 has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. +**[2]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. **[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. - -**[4]:** If not the default (`80` for `http` scheme, `443` for `https`). ### Metric: `http.client.request.time_in_queue` @@ -797,21 +793,31 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | -| [`network.protocol.version`](../attributes-registry/network.md) | string | HTTP protocol version of the connection in the connection pool. [2] | `1.1`; `2`; `3` | Recommended | -| [`server.address`](../attributes-registry/server.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`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../attributes-registry/server.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] | -| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | +| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `3.1.1` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.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` | Required | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Opt-In | -**[1]:** HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). -If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. It's not possible at the moment to override the list of known HTTP methods. +**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. +By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). -**[2]:** HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. So, the `network.protocol.version` value reported on connection metrics is different than the one reported on request-level metrics or spans for HTTP 1.0 requests. +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. -**[3]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. +If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override +the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named +OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods +(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). -**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. +Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. +Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. + +**[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 has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[5]:** If not the default (`80` for `http` scheme, `443` for `https`). +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + +**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `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. @@ -845,18 +851,28 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | -| [`server.address`](../attributes-registry/server.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | -| [`server.port`](../attributes-registry/server.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.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../attributes-registry/server.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` | Required | +| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Opt-In | -**[1]:** HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). -If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. It's not possible at the moment to override the list of known HTTP methods. +**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. +By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). -**[2]:** If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. -**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. +If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override +the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named +OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods +(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). -**[4]:** If not the default (`80` for `http` scheme, `443` for `https`). +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. +Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. +Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. + +**[2]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. + +**[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. `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. diff --git a/model/metrics/http.yaml b/model/metrics/http.yaml index c8324dc984..176d87a616 100644 --- a/model/metrics/http.yaml +++ b/model/metrics/http.yaml @@ -137,31 +137,16 @@ groups: requirement_level: required - ref: network.peer.address requirement_level: recommended - brief: Remote IP address of the socket connection. - examples: ["10.1.2.80"] - ref: network.protocol.version requirement_level: recommended - brief: HTTP protocol version of the connection in the connection pool. - note: > - HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. - So, the `network.protocol.version` value reported on connection metrics is different than the one reported - on request-level metrics or spans for HTTP 1.0 requests. - examples: ["1.1", "2", "3"] - ref: server.address - requirement_level: required - brief: > - Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: > - If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then - `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. - ref: server.port - requirement_level: - conditionally_required: If not the default (`80` for `http` scheme, `443` for `https`). + requirement_level: required brief: > Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - ref: url.scheme - requirement_level: recommended - examples: ['http', 'https', 'ftp'] + requirement_level: opt_in + examples: ["http", "https"] - id: metric.http.client.connection.duration type: metric @@ -175,27 +160,14 @@ groups: requirement_level: recommended - ref: network.protocol.version requirement_level: recommended - brief: HTTP protocol version of the connection in the connection pool. - note: > - HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. - So, the `network.protocol.version` value reported on connection metrics is different than the one reported - on request-level metrics or spans for HTTP 1.0 requests. - examples: ["1.1", "2", "3"] - ref: server.address - requirement_level: required - brief: > - Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: > - If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then - `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. - ref: server.port - requirement_level: - conditionally_required: If not the default (`80` for `http` scheme, `443` for `https`). + requirement_level: required brief: > Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - ref: url.scheme - requirement_level: recommended - examples: ['http', 'https', 'ftp'] + requirement_level: opt_in + examples: ["http", "https"] - id: metric.http.client.request.time_in_queue type: metric @@ -207,35 +179,16 @@ groups: attributes: - ref: http.request.method requirement_level: recommended - note: > - HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) - and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). - - If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. - It's not possible at the moment to override the list of known HTTP methods. - ref: network.protocol.version requirement_level: recommended - brief: HTTP protocol version of the connection in the connection pool. - note: > - HTTP 1.0 and 1.1 requests share connections in the connection pool and are both reported as version `1.1`. - So, the `network.protocol.version` value reported on connection metrics is different than the one reported - on request-level metrics or spans for HTTP 1.0 requests. - examples: ["1.1", "2", "3"] - ref: server.address - requirement_level: required - brief: > - Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: > - If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then - `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. - ref: server.port - requirement_level: - conditionally_required: If not the default (`80` for `http` scheme, `443` for `https`). + requirement_level: required brief: > Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - ref: url.scheme - requirement_level: recommended - examples: ['http', 'https', 'ftp'] + requirement_level: opt_in + examples: ["http", "https"] - id: metric.http.client.active_requests type: metric @@ -247,24 +200,11 @@ groups: attributes: - ref: http.request.method requirement_level: recommended - note: > - HTTP request method value is one of the "known" methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) - and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). - - If the HTTP request method isn't known, it sets the `http.request.method` attribute to `_OTHER`. - It's not possible at the moment to override the list of known HTTP methods. - ref: server.address - requirement_level: required - brief: > - Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: > - If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then - `server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used. - ref: server.port - requirement_level: - conditionally_required: If not the default (`80` for `http` scheme, `443` for `https`). + requirement_level: required brief: > Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - ref: url.scheme - requirement_level: recommended - examples: ['http', 'https', 'ftp'] + requirement_level: opt_in + examples: ["http", "https"] diff --git a/model/registry/http.yaml b/model/registry/http.yaml index c8bd9a0839..a4d4839eba 100644 --- a/model/registry/http.yaml +++ b/model/registry/http.yaml @@ -135,6 +135,7 @@ groups: SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. - id: connection.state type: + allow_custom_values: true members: - id: active value: "active" From 36436f981bb7ba72440495adf7cdceac50ed0644 Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Tue, 12 Mar 2024 16:20:48 +0100 Subject: [PATCH 4/5] Remove http.client.request.time_in_queue --- docs/http/http-metrics.md | 63 --------------------------------------- model/metrics/http.yaml | 21 ------------- 2 files changed, 84 deletions(-) diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 50434e5757..5a09ad5cbf 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -25,7 +25,6 @@ operations. By adding HTTP attributes to metric events it allows for finely tune - [Metric: `http.client.response.body.size`](#metric-httpclientresponsebodysize) - [Metric: `http.client.open_connections`](#metric-httpclientopen_connections) - [Metric: `http.client.connection.duration`](#metric-httpclientconnectionduration) - - [Metric: `http.client.request.time_in_queue`](#metric-httpclientrequesttime_in_queue) - [Metric: `http.client.active_requests`](#metric-httpclientactive_requests) @@ -773,68 +772,6 @@ This metric is optional. **[3]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. -### Metric: `http.client.request.time_in_queue` - -This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/api.md#instrument-advisory-parameters) -of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. - -**Status**: [Experimental][DocumentStatus] - -This metric is optional. - - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `http.client.request.time_in_queue` | Histogram | `s` | The amount of time requests spent on a queue waiting for an available connection. | - - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | -| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [2] | `3.1.1` | Recommended | -| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | -| [`server.port`](../attributes-registry/server.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` | Required | -| [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Opt-In | - -**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. -By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) -and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). - -If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`. - -If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override -the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named -OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods -(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). - -HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. -Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. -Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. - -**[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 has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. - -**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. - -**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. - -`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 HTTP method that the instrumentation has no prior knowledge of. | - - ### Metric: `http.client.active_requests` **Status**: [Experimental][DocumentStatus] diff --git a/model/metrics/http.yaml b/model/metrics/http.yaml index 176d87a616..49a0d6819c 100644 --- a/model/metrics/http.yaml +++ b/model/metrics/http.yaml @@ -169,27 +169,6 @@ groups: requirement_level: opt_in examples: ["http", "https"] - - id: metric.http.client.request.time_in_queue - type: metric - metric_name: http.client.request.time_in_queue - stability: experimental - brief: "The amount of time requests spent on a queue waiting for an available connection." - instrument: histogram - unit: "s" - attributes: - - ref: http.request.method - requirement_level: recommended - - ref: network.protocol.version - requirement_level: recommended - - ref: server.address - - ref: server.port - requirement_level: required - brief: > - Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - - ref: url.scheme - requirement_level: opt_in - examples: ["http", "https"] - - id: metric.http.client.active_requests type: metric metric_name: http.client.active_requests From c3f9dd324040af073096e655c8e5a495bb00cf1d Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Wed, 13 Mar 2024 09:44:36 +0100 Subject: [PATCH 5/5] Fix server.address requirement level --- docs/http/http-metrics.md | 6 +++--- model/metrics/http.yaml | 3 +++ 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 5a09ad5cbf..dd429a32fb 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -722,7 +722,7 @@ This metric is optional. | [`http.connection.state`](../attributes-registry/http.md) | string | State of the HTTP connection in the HTTP connection pool. | `active`; `idle` | Required | | [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `3.1.1` | Recommended | -| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../attributes-registry/server.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` | Required | | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Opt-In | @@ -761,7 +761,7 @@ This metric is optional. |---|---|---|---|---| | [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [1] | `3.1.1` | Recommended | -| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../attributes-registry/server.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` | Required | | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Opt-In | @@ -788,7 +788,7 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Recommended | -| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../attributes-registry/server.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` | Required | | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Opt-In | diff --git a/model/metrics/http.yaml b/model/metrics/http.yaml index 49a0d6819c..ba1ca5a522 100644 --- a/model/metrics/http.yaml +++ b/model/metrics/http.yaml @@ -140,6 +140,7 @@ groups: - ref: network.protocol.version requirement_level: recommended - ref: server.address + requirement_level: required - ref: server.port requirement_level: required brief: > @@ -161,6 +162,7 @@ groups: - ref: network.protocol.version requirement_level: recommended - ref: server.address + requirement_level: required - ref: server.port requirement_level: required brief: > @@ -180,6 +182,7 @@ groups: - ref: http.request.method requirement_level: recommended - ref: server.address + requirement_level: required - ref: server.port requirement_level: required brief: >