Remove repetitive notes, briefs, etc on ref attributes

open-telemetry · Oct 3, 2023 · dee44a8 · dee44a8
1 parent 2c065be
commit dee44a8
Show file tree

Hide file tree

Showing 5 changed files with 27 additions and 135 deletions.
diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md
@@ -80,8 +80,8 @@ 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
 | `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. |
 | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
-| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `amqp`; `http`; `mqtt` | Recommended |
-| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `3.1.1` | Recommended |
+| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `http`; `spdy` | Recommended: if not default (`http`). |
+| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `1.0`; `1.1`; `2`; `3` | Recommended |
 | [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com` | Opt-In |
 | [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [7] | `80`; `8080`; `443` | Opt-In |
 | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
@@ -252,8 +252,8 @@ This metric is optional.
 | `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. |
 | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
-| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `amqp`; `http`; `mqtt` | Recommended |
-| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `3.1.1` | Recommended |
+| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `http`; `spdy` | Recommended: if not default (`http`). |
+| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `1.0`; `1.1`; `2`; `3` | Recommended |
 | [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com` | Opt-In |
 | [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [7] | `80`; `8080`; `443` | Opt-In |
 | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
@@ -356,8 +356,8 @@ This metric is optional.
 | `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. |
 | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
-| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `amqp`; `http`; `mqtt` | Recommended |
-| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `3.1.1` | Recommended |
+| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `http`; `spdy` | Recommended: if not default (`http`). |
+| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `1.0`; `1.1`; `2`; `3` | Recommended |
 | [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com` | Opt-In |
 | [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [7] | `80`; `8080`; `443` | Opt-In |
 | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
@@ -465,8 +465,8 @@ 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
 | `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. [3] | `amqp`; `http`; `mqtt` | Recommended |
-| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [4] | `3.1.1` | Recommended |
+| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `http`; `spdy` | Recommended: if not default (`http`). |
+| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [4] | `1.0`; `1.1`; `2`; `3` | 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. [5] | `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. [6] | `80`; `8080`; `443` | Conditionally Required: [7] |
 | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Required |
@@ -512,7 +512,8 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original
   if it's sent in absolute-form
 - Host identifier of the `Host` header
 
-SHOULD NOT be set if capturing it would require an extra DNS lookup.
+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.
 
 **[6]:** 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.
 
@@ -560,8 +561,8 @@ This metric is optional.
 | `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. [3] | `amqp`; `http`; `mqtt` | Recommended |
-| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [4] | `3.1.1` | Recommended |
+| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `http`; `spdy` | Recommended: if not default (`http`). |
+| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [4] | `1.0`; `1.1`; `2`; `3` | 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. [5] | `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. [6] | `80`; `8080`; `443` | Conditionally Required: [7] |
 | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Required |
@@ -607,7 +608,8 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original
   if it's sent in absolute-form
 - Host identifier of the `Host` header
 
-SHOULD NOT be set if capturing it would require an extra DNS lookup.
+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.
 
 **[6]:** 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.
 
@@ -655,8 +657,8 @@ This metric is optional.
 | `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. [3] | `amqp`; `http`; `mqtt` | Recommended |
-| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [4] | `3.1.1` | Recommended |
+| [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `http`; `spdy` | Recommended: if not default (`http`). |
+| [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [4] | `1.0`; `1.1`; `2`; `3` | 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. [5] | `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. [6] | `80`; `8080`; `443` | Conditionally Required: [7] |
 | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Required |
@@ -702,7 +704,8 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original
   if it's sent in absolute-form
 - Host identifier of the `Host` header
 
-SHOULD NOT be set if capturing it would require an extra DNS lookup.
+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.
 
 **[6]:** 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.
 

diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md
@@ -240,7 +240,7 @@ This span type represents an outbound HTTP request. There are two ways this can
 
 For an HTTP client span, `SpanKind` MUST be `Client`.
 
-<!-- semconv trace.http.client(full) -->
+<!-- semconv trace.http.client -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | `http.resend_count` | int | The ordinal number of request resending attempt (for any reason, including redirects). [1] | `3` | Recommended: if and only if request was retried. |
@@ -372,7 +372,7 @@ This span type represents an inbound HTTP request.
 
 For an HTTP server span, `SpanKind` MUST be `Server`.
 
-<!-- semconv trace.http.server(full) -->
+<!-- semconv trace.http.server -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | [`client.address`](../general/attributes.md) | string | Client address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `83.164.160.102` | Recommended |

diff --git a/model/http-common.yaml b/model/http-common.yaml
@@ -93,6 +93,7 @@ groups:
     prefix: http
     type: attribute_group
     brief: 'HTTP Client attributes'
+    extends: attributes.http.common
     attributes:
       - ref: server.address
         requirement_level: required
@@ -105,7 +106,8 @@ groups:
             if it's sent in absolute-form
           - Host identifier of the `Host` header
 
-          SHOULD NOT be set if capturing it would require an extra DNS lookup.
+          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 default (`80` for `http` scheme, `443` for `https`).
@@ -119,6 +121,7 @@ groups:
     prefix: http
     type: attribute_group
     brief: 'HTTP Server attributes'
+    extends: attributes.http.common
     attributes:
       - id: route
         type: string
@@ -155,6 +158,8 @@ groups:
           - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
             if it's sent in absolute-form.
           - Port identifier of the `Host` header
+        requirement_level:
+          recommended: If not default (`80` for `http` scheme, `443` for `https`).
       - ref: url.scheme
         requirement_level: required
         examples: ["http", "https"]
diff --git a/model/metrics/http.yaml b/model/metrics/http.yaml
@@ -5,87 +5,15 @@ groups:
     extends: attributes.http.server
     attributes:
       - ref: server.address
-        brief: >
-          Name of the local HTTP server that received the request.
         requirement_level: opt_in
-        note: |
-          Determined by using the first of the following that applies
-
-          - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only
-            include host identifier.
-          - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
-            if it's sent in absolute-form.
-          - Host identifier of the `Host` header
-
-          SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup.
-
       - ref: server.port
-        brief: >
-          Port of the local HTTP server that received the request.
         requirement_level: opt_in
-        note: |
-          Determined by using the first of the following that applies
-
-          - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host.
-          - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
-            if it's sent in absolute-form.
-          - Port identifier of the `Host` header
-      # todo (lmolkova) build tools don't populate grandparent attributes
-      - ref: error.type
-        requirement_level:
-          conditionally_required: If request has ended with an error.
-        examples: ['timeout', 'name_resolution_error', '500']
-        note: |
-          If the request fails with an error before response status code was sent or received,
-          `error.type` SHOULD be set to exception type or a component-specific low cardinality error code.
-
-          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 status code number (represented as a string), an exception type (if thrown) or a component-specific error code.
-
-          The `error.type` value 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 the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
-      - ref: http.request.method
-      - ref: http.response.status_code
-      - ref: network.protocol.name
-      - ref: network.protocol.version
 
   - id: metric_attributes.http.client
     type: attribute_group
     brief: 'HTTP client attributes'
     extends: attributes.http.client
     attributes:
-      # todo (lmolkova) build tools don't populate grandparent attributes
-      - ref: http.request.method
-      - ref: http.response.status_code
-      - ref: network.protocol.name
-      - ref: network.protocol.version
-      - ref: error.type
-        requirement_level:
-          conditionally_required: If request has ended with an error.
-        examples: ['timeout', 'name_resolution_error', '500']
-        note: |
-          If the request fails with an error before response status code was sent or received,
-          `error.type` SHOULD be set to exception type or a component-specific low cardinality error code.
-
-          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 status code number (represented as a string), an exception type (if thrown) or a component-specific error code.
-
-          The `error.type` value 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 the request has completed successfully, instrumentations SHOULD NOT set `error.type`.
       - ref: url.scheme
         requirement_level: required