Http: server.address and server.port to opt-in on metrics

CHANGELOG.md

@@ -84,3 +84,8 @@ release.
   ([#55](https://github.com/open-telemetry/semantic-conventions/pull/55))
 - Split out sections for proposed stable JVM metrics and experimental JVM metrics.
   ([#56](https://github.com/open-telemetry/semantic-conventions/pull/56))
+- Change attributes requirement levels on HTTP server semantic conventions:
+ `server.address` and `server.port` requirement level has changed from
+  `required` to `opt_in` on HTTP server metrics and to `recommended` on HTTP spans.
+  `url.query` requirement level has changed from `recommended` to `required`.
+  ([#TODO](https://github.com/open-telemetry/semantic-conventions/pull/TODO))

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: |

semantic_conventions/metrics/http.yaml

@@ -1,17 +1,59 @@
 groups:
+  - id: metric_attributes.http.server
+    type: attribute_group
+    brief: 'HTTP server attributes'
+    extends: attributes.http.server
+    attributes:
+      - ref: http.request.method
+      - ref: http.response.status_code
+      - ref: network.protocol.name
+      - ref: network.protocol.version
+      - 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
+  - id: metric_attributes.http.client
+    type: attribute_group
+    brief: 'HTTP client attributes'
+    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
+
   - 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: attributes.http.server
-    attributes:
+    extends: metric_attributes.http.server
       # 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.http.server.active_requests
     type: metric
@@ -25,7 +67,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 +82,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 +99,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

semantic_conventions/trace/http.yaml

@@ -87,7 +87,7 @@ groups:
     brief: 'Semantic Convention for HTTP Server'
     attributes:
       - ref: server.address
-        requirement_level: required
+        requirement_level: recommended
         sampling_relevant: true
         brief: >
           Name of the local HTTP server that received the request.
@@ -104,7 +104,7 @@ groups:
       - ref: server.port
         sampling_relevant: true
         requirement_level:
-          conditionally_required: If not default (`80` for `http` scheme, `443` for `https`).
+          recommended: If not default (`80` for `http` scheme, `443` for `https`).
         brief: >
           Port of the local HTTP server that received the request.
         note: |
@@ -138,8 +138,9 @@ groups:
         requirement_level: required
         sampling_relevant: true
       - ref: url.query
+        requirement_level: required
         sampling_relevant: true
       - ref: url.scheme
-        sampling_relevant: true
         requirement_level: required
+        sampling_relevant: true
         examples: ["http", "https"]

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

specification/trace/semantic_conventions/http.md

@@ -293,12 +293,12 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i
 | [`client.port`](span-general.md) | int | The port of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) or a similar header). Otherwise, the immediate client peer port. [3] | `65123` | Recommended |
 | [`client.socket.address`](span-general.md) | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. |
 | [`client.socket.port`](span-general.md) | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. |
-| [`server.address`](span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Required |
-| [`server.port`](span-general.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Conditionally Required: [6] |
+| [`server.address`](span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Recommended |
+| [`server.port`](span-general.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Recommended: [6] |
 | [`server.socket.address`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.5.3.2` | Opt-In |
 | [`server.socket.port`](span-general.md) | int | Local socket port. Useful in case of a multi-port host. | `16456` | Opt-In |
 | `url.path` | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [7] | `/search` | Required |
-| `url.query` | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [8] | `q=OpenTelemetry` | Recommended |
+| `url.query` | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [8] | `q=OpenTelemetry` | Required |
 | `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.