Consider X-Forwarded-Host / Forwarded when capturing server.address a…

…nd server.port
open-telemetry · Oct 16, 2023 · c26fbcf · c26fbcf
1 parent cee22ec
commit c26fbcf
Show file tree

Hide file tree

Showing 5 changed files with 39 additions and 6 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,8 @@ release.
 
 - BREAKING: Rename http.resend_count to http.request.resend_count.
   ([#374](https://github.com/open-telemetry/semantic-conventions/pull/374))
+- BREAKING: Consider `X-Forwarded-Host` / `Forwarded` when capturing `server.address` and `server.port`.
+  ([#411](https://github.com/open-telemetry/semantic-conventions/pull/411))
 
 ### Features
 

diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md
@@ -131,6 +131,8 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
   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 [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
 
 SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup.
@@ -140,6 +142,8 @@ SHOULD NOT be set if only IP address is available and capturing name would requi
 - 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.
+- 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.
 - Port identifier of the `Host` header
 
 `error.type` 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.
@@ -205,21 +209,25 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original
   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 [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
 
 SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup.
 
-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.
 
 **[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.
+- 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.
 - 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,6 +318,8 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
   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 [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
 
 SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup.
@@ -319,6 +329,8 @@ SHOULD NOT be set if only IP address is available and capturing name would requi
 - 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.
+- 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.
 - Port identifier of the `Host` header
 
 `error.type` 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.
@@ -415,6 +427,8 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
   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 [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
 
 SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup.
@@ -424,6 +438,8 @@ SHOULD NOT be set if only IP address is available and capturing name would requi
 - 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.
+- 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.
 - Port identifier of the `Host` header
 
 `error.type` 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.

diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md
@@ -393,6 +393,8 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
   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 [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
 
 SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup.
@@ -402,6 +404,8 @@ SHOULD NOT be set if only IP address is available and capturing name would requi
 - 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.
+- 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.
 - Port identifier of the `Host` header
 
 **[6]:** If not default (`80` for `http` scheme, `443` for `https`).

diff --git a/model/http-common.yaml b/model/http-common.yaml
@@ -81,8 +81,12 @@ groups:
             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 [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.
+
           SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup.
 
       - ref: server.port
@@ -94,6 +98,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`).

diff --git a/model/metrics/http.yaml b/model/metrics/http.yaml
@@ -44,15 +44,18 @@ 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.
+
           SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup.
 
-          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.
 
       - ref: server.port
@@ -65,9 +68,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