Factor in X-Forwarded-Host / Forwarded when capturing server.address and server.port

CHANGELOG.md

@@ -19,6 +19,8 @@ release.
   ([#402](https://github.com/open-telemetry/semantic-conventions/pull/402))
 - BREAKING: Change `network.type` from recommended to opt-in in HTTP semconv.
   ([#410](https://github.com/open-telemetry/semantic-conventions/pull/410))
+- BREAKING: Factor in `X-Forwarded-Host` / `Forwarded` when capturing `server.address` and `server.port`.
+  ([#411](https://github.com/open-telemetry/semantic-conventions/pull/411))
 
 ### Features
 

docs/http/http-metrics.md

@@ -127,23 +127,28 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
 
 **[6]:** 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.
+- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host.
 - 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 [Forwarded#host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded#host),
+  [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host), or a similar header.
 - Host identifier of the `Host` header
 
-Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker
+MUST NOT include the port identifier.
+
+Warning: since this attribute may be based on HTTP headers, opting in to it may allow an attacker
 to trigger cardinality limits, degrading the usefulness of the metric.
 
 **[7]:** 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 [Forwarded#host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded#host),
+  [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host), or a similar header.
 - Port identifier of the `Host` header
 
-Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker
+Warning: since this attribute may be based on HTTP headers, opting in to it may allow an attacker
 to trigger cardinality limits, degrading the usefulness of the metric.
 
 **[8]:** The scheme of the original client request, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded), [X-Forwarded-Proto](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request.
@@ -207,23 +212,28 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original
 
 **[2]:** 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.
+- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host.
 - 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 [Forwarded#host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded#host),
+  [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host), or a similar header.
 - Host identifier of the `Host` header
 
-Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker
+MUST NOT include the port identifier.
+
+Warning: since this attribute may be based on HTTP headers, opting in to it may allow an attacker
 to trigger cardinality limits, degrading the usefulness of the metric.
 
 **[3]:** 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 [Forwarded#host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded#host),
+  [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host), or a similar header.
 - Port identifier of the `Host` header
 
-Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker
+Warning: since this attribute may be based on HTTP headers, opting in to it may allow an attacker
 to trigger cardinality limits, degrading the usefulness of the metric.
 
 `http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
@@ -310,23 +320,28 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
 
 **[6]:** 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.
+- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host.
 - 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 [Forwarded#host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded#host),
+  [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host), or a similar header.
 - Host identifier of the `Host` header
 
-Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker
+MUST NOT include the port identifier.
+
+Warning: since this attribute may be based on HTTP headers, opting in to it may allow an attacker
 to trigger cardinality limits, degrading the usefulness of the metric.
 
 **[7]:** 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 [Forwarded#host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded#host),
+  [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host), or a similar header.
 - Port identifier of the `Host` header
 
-Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker
+Warning: since this attribute may be based on HTTP headers, opting in to it may allow an attacker
 to trigger cardinality limits, degrading the usefulness of the metric.
 
 **[8]:** The scheme of the original client request, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded), [X-Forwarded-Proto](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request.
@@ -421,23 +436,28 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
 
 **[6]:** 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.
+- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host.
 - 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 [Forwarded#host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded#host),
+  [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host), or a similar header.
 - Host identifier of the `Host` header
 
-Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker
+MUST NOT include the port identifier.
+
+Warning: since this attribute may be based on HTTP headers, opting in to it may allow an attacker
 to trigger cardinality limits, degrading the usefulness of the metric.
 
 **[7]:** 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 [Forwarded#host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded#host),
+  [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host), or a similar header.
 - Port identifier of the `Host` header
 
-Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker
+Warning: since this attribute may be based on HTTP headers, opting in to it may allow an attacker
 to trigger cardinality limits, degrading the usefulness of the metric.
 
 **[8]:** The scheme of the original client request, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded), [X-Forwarded-Proto](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request.

docs/http/http-spans.md

@@ -373,17 +373,22 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
 
 **[4]:** 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.
+- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host.
 - 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 [Forwarded#host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded#host),
+  [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host), or a similar header.
 - Host identifier of the `Host` header
 
+MUST NOT include the port identifier.
+
 **[5]:** 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 [Forwarded#host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded#host),
+  [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host), or a similar header.
 - Port identifier of the `Host` header
 
 **[6]:** If not default (`80` for `http` scheme, `443` for `https`).

model/http-common.yaml

@@ -76,12 +76,15 @@ groups:
         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.
+          - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host.
           - 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 [Forwarded#host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded#host),
+            [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host), or a similar header.
           - Host identifier of the `Host` header
 
+          MUST NOT include the port identifier.
+
       - ref: server.port
         brief: >
           Port of the local HTTP server that received the request.
@@ -91,6 +94,8 @@ groups:
           - 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 [Forwarded#host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded#host),
+            [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host), or a similar header.
           - Port identifier of the `Host` header
         requirement_level:
           conditionally_required: If not default (`80` for `http` scheme, `443` for `https`).

model/metrics/http.yaml

@@ -9,13 +9,16 @@ groups:
         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.
+          - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host.
           - 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 [Forwarded#host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded#host),
+            [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host), or a similar header.
           - Host identifier of the `Host` header
 
-          Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker
+          MUST NOT include the port identifier.
+
+          Warning: since this attribute may be based on HTTP headers, opting in to it may allow an attacker
           to trigger cardinality limits, degrading the usefulness of the metric.
 
       - ref: server.port
@@ -26,9 +29,11 @@ groups:
           - 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 [Forwarded#host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded#host),
+            [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host), or a similar header.
           - Port identifier of the `Host` header
 
-          Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker
+          Warning: since this attribute may be based on HTTP headers, opting in to it may allow an attacker
           to trigger cardinality limits, degrading the usefulness of the metric.
 
   - id: metric_attributes.http.client
@@ -66,13 +71,16 @@ groups:
         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.
+          - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host.
           - 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 [Forwarded#host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded#host),
+            [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host), or a similar header.
           - Host identifier of the `Host` header
 
-          Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker
+          MUST NOT include the port identifier.
+
+          Warning: since this attribute may be based on HTTP headers, opting in to it may allow an attacker
           to trigger cardinality limits, degrading the usefulness of the metric.
 
       - ref: server.port
@@ -85,9 +93,11 @@ groups:
           - 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 [Forwarded#host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded#host),
+            [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host), or a similar header.
           - Port identifier of the `Host` header
 
-          Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker
+          Warning: since this attribute may be based on HTTP headers, opting in to it may allow an attacker
           to trigger cardinality limits, degrading the usefulness of the metric.
 
   - id: metric.http.server.request.body.size