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

…109)
open-telemetry · Jun 19, 2023 · 156f942 · 156f942
1 parent d31b014
commit 156f942
Show file tree

Hide file tree

Showing 4 changed files with 68 additions and 66 deletions.
diff --git 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))
diff --git 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: |

diff --git 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,68 +100,36 @@ 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
     metric_name: http.server.response.size
     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
     metric_name: http.client.duration
     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
     metric_name: http.client.response.size
     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
diff --git 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