Make server.address and server.port to opt-in on HTTP server metrics (#109)

2023-06-19 14:35:45 -07:00 · 2023-06-19 14:35:45 -07:00 · 156f9424fe
parent d31b014b1f
commit 156f9424fe
4 changed files with 68 additions and 66 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -86,3 +86,6 @@ release.
  ([#56](https://github.com/open-telemetry/semantic-conventions/pull/56))
 - Make `url.query` conditionally required for HTTP spans.
  ([#118](https://github.com/open-telemetry/semantic-conventions/pull/118))
+- Change `server.address` and `server.port` requirement levels on HTTP server metrics
+  from `required` to `opt_in`.
+  ([#109](https://github.com/open-telemetry/semantic-conventions/pull/109))
--- a/semantic_conventions/http-common.yaml
+++ b/semantic_conventions/http-common.yaml
@ -65,7 +65,6 @@ groups:

          SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one.
      - ref: server.address
-        requirement_level: required
        brief: >
          Name of the local HTTP server that received the request.
        note: |
@ -80,8 +79,6 @@ groups:
          SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup.

      - ref: server.port
-        requirement_level:
-          conditionally_required: If not default (`80` for `http` scheme, `443` for `https`).
        brief: >
          Port of the local HTTP server that received the request.
        note: |
--- a/semantic_conventions/metrics/http.yaml
+++ b/semantic_conventions/metrics/http.yaml
@ -1,17 +1,60 @@
 groups:
-  - id: metric.http.server.duration
-    type: metric
-    metric_name: http.server.duration
-    brief: "Measures the duration of inbound HTTP requests."
-    instrument: histogram
-    unit: "s"
+  - id: metric_attributes.http.server
+    type: attribute_group
+    brief: 'HTTP server attributes'
    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](/specification/trace/semantic_conventions/http.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](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host.
+          - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
+            if it's sent in absolute-form.
+          - Port identifier of the `Host` header
+      # 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
+
+  - 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: server.socket.address
+
+  - id: metric.http.server.duration
+    type: metric
+    metric_name: http.server.duration
+    brief: "Measures the duration of inbound HTTP requests."
+    instrument: histogram
+    unit: "s"
+    extends: metric_attributes.http.server

  - id: metric.http.server.active_requests
    type: metric
@ -25,7 +68,7 @@ groups:
        requirement_level: required
        examples: ["http", "https"]
      - ref: server.address
-        requirement_level: required
+        requirement_level: opt_in
        brief: >
          Name of the local HTTP server that received the request.
        note: |
@ -40,8 +83,7 @@ groups:
          SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup.

      - ref: server.port
-        requirement_level:
-          conditionally_required: If not default (`80` for `http` scheme, `443` for `https`).
+        requirement_level: opt_in
        brief: >
          Port of the local HTTP server that received the request.
        note: |
@ -58,14 +100,7 @@ groups:
    brief: "Measures the size of HTTP request messages (compressed)."
    instrument: histogram
    unit: "By"
-    extends: attributes.http.server
-    # TODO (trask) below attributes are identical to above in metric.http.server.duration
-    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
+    extends: metric_attributes.http.server

  - id: metric.http.server.response.size
    type: metric
@ -73,13 +108,7 @@ groups:
    brief: "Measures the size of HTTP response messages (compressed)."
    instrument: histogram
    unit: "By"
-    extends: attributes.http.server
-    # TODO (trask) below attributes are identical to above in metric.http.server.duration
-    attributes:
-      - ref: http.request.method
-      - ref: http.response.status_code
-      - ref: network.protocol.name
-      - ref: network.protocol.version
+    extends: metric_attributes.http.server

  - id: metric.http.client.duration
    type: metric
@ -87,27 +116,15 @@ groups:
    brief: "Measures the duration of outbound HTTP requests."
    instrument: histogram
    unit: "s"
-    extends: attributes.http.client
-    attributes:
-      - ref: http.request.method
-      - ref: http.response.status_code
-      - ref: network.protocol.name
-      - ref: network.protocol.version
-      - ref: server.socket.address
+    extends: metric_attributes.http.client
+
  - id: metric.http.client.request.size
    type: metric
    metric_name: http.client.request.size
    brief: "Measures the size of HTTP request messages (compressed)."
    instrument: histogram
    unit: "By"
-    extends: attributes.http.client
-    # TODO (trask) below attributes are identical to above in metric.http.client.duration
-    attributes:
-      - ref: http.request.method
-      - ref: http.response.status_code
-      - ref: network.protocol.name
-      - ref: network.protocol.version
-      - ref: server.socket.address
+    extends: metric_attributes.http.client

  - id: metric.http.client.response.size
    type: metric
@ -115,11 +132,4 @@ groups:
    brief: "Measures the size of HTTP response messages (compressed)."
    instrument: histogram
    unit: "By"
-    extends: attributes.http.client
-    # TODO (trask) below attributes are identical to above in metric.http.client.duration
-    attributes:
-      - ref: http.request.method
-      - ref: http.response.status_code
-      - ref: network.protocol.name
-      - ref: network.protocol.version
-      - ref: server.socket.address
+    extends: metric_attributes.http.client
--- a/specification/metrics/semantic_conventions/http-metrics.md
+++ b/specification/metrics/semantic_conventions/http-metrics.md
@ -77,8 +77,8 @@ 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,
 | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
 | [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
 | [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended |
-| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required |
-| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
+| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Opt-In |
+| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Opt-In |
 | `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |

 **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
@ -102,8 +102,6 @@ SHOULD NOT be set if only IP address is available and capturing name would requi
 - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
  if it's sent in absolute-form.
 - Port identifier of the `Host` header
-
-**[5]:** If not default (`80` for `http` scheme, `443` for `https`).
 <!-- endsemconv -->

 ### Metric: `http.server.active_requests`
@ -120,8 +118,8 @@ This metric is optional.
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
-| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [1] | `example.com` | Required |
-| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [2] | `80`; `8080`; `443` | Conditionally Required: [3] |
+| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [1] | `example.com` | Opt-In |
+| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [2] | `80`; `8080`; `443` | Opt-In |
 | `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |

 **[1]:** Determined by using the first of the following that applies
@ -140,8 +138,6 @@ SHOULD NOT be set if only IP address is available and capturing name would requi
 - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
  if it's sent in absolute-form.
 - Port identifier of the `Host` header
-
-**[3]:** If not default (`80` for `http` scheme, `443` for `https`).
 <!-- endsemconv -->

 ### Metric: `http.server.request.size`
@ -162,8 +158,8 @@ This metric is optional.
 | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
 | [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
 | [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended |
-| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required |
-| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
+| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Opt-In |
+| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Opt-In |
 | `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |

 **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
@ -187,8 +183,6 @@ SHOULD NOT be set if only IP address is available and capturing name would requi
 - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
  if it's sent in absolute-form.
 - Port identifier of the `Host` header
-
-**[5]:** If not default (`80` for `http` scheme, `443` for `https`).
 <!-- endsemconv -->

 ### Metric: `http.server.response.size`
@ -209,8 +203,8 @@ This metric is optional.
 | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
 | [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
 | [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended |
-| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required |
-| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
+| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Opt-In |
+| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Opt-In |
 | `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |

 **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
@ -234,8 +228,6 @@ SHOULD NOT be set if only IP address is available and capturing name would requi
 - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
  if it's sent in absolute-form.
 - Port identifier of the `Host` header
-
-**[5]:** If not default (`80` for `http` scheme, `443` for `https`).
 <!-- endsemconv -->

 ## HTTP Client