rephrase error.type to clarify that instr can recode exceptions on to…

…p of status code, use numerical status code representation
open-telemetry · Sep 8, 2023 · e3eba94 · e3eba94
1 parent 655a9e4
commit e3eba94
Show file tree

Hide file tree

Showing 5 changed files with 28 additions and 28 deletions.
diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md
@@ -77,7 +77,7 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5,
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
-| `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `Internal Server Error` | Conditionally Required: If request has ended with an error. |
+| `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. |
 | `http.request.method` | string | HTTP request method. [3] | `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 |
@@ -102,7 +102,7 @@ telemetry consumers that aggregate data from multiple instrumentation libraries
 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`.
+If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
 
 **[3]:** 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)
@@ -246,7 +246,7 @@ This metric is optional.
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
-| `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `Internal Server Error` | Conditionally Required: If request has ended with an error. |
+| `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. |
 | `http.request.method` | string | HTTP request method. [3] | `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 |
@@ -271,7 +271,7 @@ telemetry consumers that aggregate data from multiple instrumentation libraries
 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`.
+If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
 
 **[3]:** 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)
@@ -347,7 +347,7 @@ This metric is optional.
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
-| `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `Internal Server Error` | Conditionally Required: If request has ended with an error. |
+| `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. |
 | `http.request.method` | string | HTTP request method. [3] | `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 |
@@ -372,7 +372,7 @@ telemetry consumers that aggregate data from multiple instrumentation libraries
 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`.
+If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
 
 **[3]:** 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)
@@ -453,7 +453,7 @@ 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,
 <!-- semconv metric.http.client.request.duration(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `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. |
+| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `name_resolution_error`; `500` | 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 |
@@ -475,7 +475,7 @@ telemetry consumers that aggregate data from multiple instrumentation libraries
 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`.
+If the request 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)
@@ -548,7 +548,7 @@ This metric is optional.
 <!-- semconv metric.http.client.request.size(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `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. |
+| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `name_resolution_error`; `500` | 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 |
@@ -570,7 +570,7 @@ telemetry consumers that aggregate data from multiple instrumentation libraries
 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`.
+If the request 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)
@@ -643,7 +643,7 @@ This metric is optional.
 <!-- semconv metric.http.client.response.size(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `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. |
+| `error.type` | string | Describes a class of error the operation ended with. [1] | `timeout`; `name_resolution_error`; `500` | 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 |
@@ -665,7 +665,7 @@ telemetry consumers that aggregate data from multiple instrumentation libraries
 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`.
+If the request 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)

diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md
@@ -110,7 +110,7 @@ sections below.
 | `http.request.method_original` | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | Conditionally Required: [1] |
 | `http.request.body.size` | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended |
 | `http.response.body.size` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended |
-| `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `server_certificate_invalid` | Conditionally Required: If the request has ended with an error. |
+| `error.type` | string | Describes a class of error the operation ended with. [2] | `timeout`; `name_resolution_error`; `500` | Conditionally Required: If request has ended with an error. |
 | `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required |
 | [`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. | `http`; `spdy` | Recommended: if not default (`http`). |
 | [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `1.0`; `1.1`; `2`; `3` | Recommended |
@@ -120,11 +120,11 @@ 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#status),
+**[2]:** 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, otherwise it SHOULD be set `_OTHER`.
+corresponding to the returned status code or to `_OTHER`.
 
-If the request fails with an error before or after the status code was sent or received, such error SHOULD be
+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.
 
@@ -133,7 +133,7 @@ telemetry consumers that aggregate data from multiple instrumentation libraries
 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`.
+If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
 
 **[3]:** 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)

diff --git a/model/error.yaml b/model/error.yaml
@@ -14,7 +14,7 @@ groups:
             - id: other
               value: "_OTHER"
               brief: 'A fallback error value to be used when the instrumentation does not define a custom value for it.'
-        examples: ['timeout', 'java.net.UnknownHostException', 'server_certificate_invalid', 'Internal Server Error']
+        examples: ['timeout', 'java.net.UnknownHostException', 'server_certificate_invalid', '500']
         note: |
           The `error.type` SHOULD be predictable and SHOULD have low cardinality.
           Instrumentations SHOULD document the list of errors they report.

diff --git a/model/http-common.yaml b/model/http-common.yaml
@@ -64,14 +64,14 @@ groups:
         examples: [200]
       - ref: error.type
         requirement_level:
-          conditionally_required: If the request has ended with an error.
-        examples: ['timeout', 'name_resolution_error', 'server_certificate_invalid']
+          conditionally_required: If request has ended with an error.
+        examples: ['timeout', 'name_resolution_error', '500']
         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#status),
+          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, otherwise it SHOULD be set `_OTHER`.
+          corresponding to the returned status code or to `_OTHER`.
 
-          If the request fails with an error before or after the status code was sent or received, such error SHOULD be
+          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.
 
@@ -80,7 +80,7 @@ groups:
           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`.
+          If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
       - ref: network.protocol.name
         examples: ['http', 'spdy']
         requirement_level:

diff --git a/model/metrics/http.yaml b/model/metrics/http.yaml
@@ -34,7 +34,7 @@ groups:
       - ref: error.type
         requirement_level:
           conditionally_required: If request has ended with an error.
-        examples: ['timeout', 'name_resolution_error', 'Internal Server Error']
+        examples: ['timeout', 'name_resolution_error', '500']
         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)
@@ -49,7 +49,7 @@ groups:
           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`.
+          If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
       - ref: http.request.method
       - ref: http.response.status_code
       - ref: network.protocol.name
@@ -69,7 +69,7 @@ groups:
       - ref: error.type
         requirement_level:
           conditionally_required: If request has ended with an error.
-        examples: ['timeout', 'name_resolution_error', 'Internal Server Error']
+        examples: ['timeout', 'name_resolution_error', '500']
         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)
@@ -84,7 +84,7 @@ groups:
           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`.
+          If the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
 
   - id: metric.http.server.request.duration
     type: metric