From 03db37ed7c06c05ebabb28e4abec46745a96e92d Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 6 Sep 2023 16:27:57 -0700 Subject: [PATCH] error type on client metrics --- docs/http/http-metrics.md | 132 ++++++++++++++++++++++++++++---------- docs/http/http-spans.md | 2 +- model/http-common.yaml | 2 +- model/metrics/http.yaml | 19 ++++++ 4 files changed, 120 insertions(+), 35 deletions(-) diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index d17616d80b..b292c611b5 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -453,15 +453,31 @@ 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. [1] | `GET`; `POST`; `HEAD` | Required | +| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `name_resolution_error`; `Internal Server Error` | Conditionally Required: If request has ended with an error. | +| `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`](../general/attributes.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`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.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`](../general/attributes.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`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [6] | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | +| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [7] | `10.5.3.2` | Recommended: If different than `server.address`. | -**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[1]:** If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), +`error.type` SHOULD be set to the canonical [Reason Phrase](https://www.rfc-editor.org/rfc/rfc2616.html#section-6.1.1) +corresponding to the returned status code or to `_OTHER`. + +If request fails with an error before or after status code was sent or received, such error SHOULD be +recorded on `error.type` attribute. The description SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time, when no +additional filters are applied. + +If operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + +**[2]:** 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). @@ -476,9 +492,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M 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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[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`. -**[3]:** Determined by using the first of the following that applies +**[4]:** 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 @@ -486,13 +502,19 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[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. +**[5]:** 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. -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). +**[6]:** If not default (`80` for `http` scheme, `443` for `https`). -**[6]:** When observed from the client side, this SHOULD represent the immediate server peer address. +**[7]:** When observed from the client side, this SHOULD represent the immediate server peer address. When observed from the server side, this SHOULD represent the physical server address. +`error.type` 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 | +|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | + `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 | @@ -526,15 +548,31 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `name_resolution_error`; `Internal Server Error` | Conditionally Required: If request has ended with an error. | +| `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`](../general/attributes.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`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.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`](../general/attributes.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`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [6] | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | +| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [7] | `10.5.3.2` | Recommended: If different than `server.address`. | -**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[1]:** If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), +`error.type` SHOULD be set to the canonical [Reason Phrase](https://www.rfc-editor.org/rfc/rfc2616.html#section-6.1.1) +corresponding to the returned status code or to `_OTHER`. + +If request fails with an error before or after status code was sent or received, such error SHOULD be +recorded on `error.type` attribute. The description SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time, when no +additional filters are applied. + +If operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + +**[2]:** 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). @@ -549,9 +587,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M 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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[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`. -**[3]:** Determined by using the first of the following that applies +**[4]:** 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 @@ -559,13 +597,19 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[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. +**[5]:** 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. -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). +**[6]:** If not default (`80` for `http` scheme, `443` for `https`). -**[6]:** When observed from the client side, this SHOULD represent the immediate server peer address. +**[7]:** When observed from the client side, this SHOULD represent the immediate server peer address. When observed from the server side, this SHOULD represent the physical server address. +`error.type` 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 | +|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | + `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 | @@ -599,15 +643,31 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `name_resolution_error`; `Internal Server Error` | Conditionally Required: If request has ended with an error. | +| `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`](../general/attributes.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`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.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`](../general/attributes.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`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [6] | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `80`; `8080`; `443` | Conditionally Required: [6] | +| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [7] | `10.5.3.2` | Recommended: If different than `server.address`. | -**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[1]:** If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), +`error.type` SHOULD be set to the canonical [Reason Phrase](https://www.rfc-editor.org/rfc/rfc2616.html#section-6.1.1) +corresponding to the returned status code or to `_OTHER`. + +If request fails with an error before or after status code was sent or received, such error SHOULD be +recorded on `error.type` attribute. The description SHOULD be predictable and SHOULD have low cardinality. +Instrumentations SHOULD document the list of errors they report. + +The cardinality of `error.type` within one instrumentation library SHOULD be low, but +telemetry consumers that aggregate data from multiple instrumentation libraries and applications +should be prepared for `error.type` to have high cardinality at query time, when no +additional filters are applied. + +If operation has completed successfully, instrumentations SHOULD NOT set `error.type`. + +**[2]:** 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). @@ -622,9 +682,9 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M 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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[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`. -**[3]:** Determined by using the first of the following that applies +**[4]:** 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 @@ -632,13 +692,19 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[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. +**[5]:** 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. -**[5]:** If not default (`80` for `http` scheme, `443` for `https`). +**[6]:** If not default (`80` for `http` scheme, `443` for `https`). -**[6]:** When observed from the client side, this SHOULD represent the immediate server peer address. +**[7]:** When observed from the client side, this SHOULD represent the immediate server peer address. When observed from the server side, this SHOULD represent the physical server address. +`error.type` 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 | +|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | + `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/http/http-spans.md b/docs/http/http-spans.md index 89d8c1b2df..d4fa7f9f1f 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -120,7 +120,7 @@ sections below. **[1]:** If and only if it's different than `http.request.method`. -**[2]:** If the response status code was sent/received and the status indicates an error according to the [HTTP span status definition](/docs/http/http-spans.md), +**[2]:** If the response status code was sent/received and the status indicates an error according to the [HTTP span status definition](/docs/http/http-spans.md#status), `error.type` SHOULD be set to the canonical [Reason Phrase](https://www.rfc-editor.org/rfc/rfc2616.html#section-6.1.1) corresponding to the returned status code, otherwise it SHOULD be set `_OTHER`. diff --git a/model/http-common.yaml b/model/http-common.yaml index 8366287386..74d7fbaf8b 100644 --- a/model/http-common.yaml +++ b/model/http-common.yaml @@ -67,7 +67,7 @@ groups: conditionally_required: If the request has ended with an error. examples: ['timeout', 'name_resolution_error', 'server_certificate_invalid'] note: | - If the response status code was sent/received and the status indicates an error according to the [HTTP span status definition](/docs/http/http-spans.md), + If the response status code was sent/received and the status indicates an error according to the [HTTP span status definition](/docs/http/http-spans.md#status), `error.type` SHOULD be set to the canonical [Reason Phrase](https://www.rfc-editor.org/rfc/rfc2616.html#section-6.1.1) corresponding to the returned status code, otherwise it SHOULD be set `_OTHER`. diff --git a/model/metrics/http.yaml b/model/metrics/http.yaml index 6247a5780f..16d4aa7362 100644 --- a/model/metrics/http.yaml +++ b/model/metrics/http.yaml @@ -66,6 +66,25 @@ groups: - ref: network.protocol.name - ref: network.protocol.version - ref: server.socket.address + - ref: error.type + requirement_level: + conditionally_required: If request has ended with an error. + examples: ['timeout', 'name_resolution_error', 'Internal Server Error'] + note: | + If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), + `error.type` SHOULD be set to the canonical [Reason Phrase](https://www.rfc-editor.org/rfc/rfc2616.html#section-6.1.1) + corresponding to the returned status code or to `_OTHER`. + + If request fails with an error before or after status code was sent or received, such error SHOULD be + recorded on `error.type` attribute. The description SHOULD be predictable and SHOULD have low cardinality. + Instrumentations SHOULD document the list of errors they report. + + The cardinality of `error.type` within one instrumentation library SHOULD be low, but + telemetry consumers that aggregate data from multiple instrumentation libraries and applications + should be prepared for `error.type` to have high cardinality at query time, when no + additional filters are applied. + + If operation has completed successfully, instrumentations SHOULD NOT set `error.type`. - id: metric.http.server.request.duration type: metric