diff --git a/CHANGELOG.md b/CHANGELOG.md index 54c1a3aa1..36135059f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,8 @@ release. ([#401](https://github.com/open-telemetry/semantic-conventions/pull/401)) - Change `server.port` from recommended to conditionally required on HTTP server semconv. ([#399](https://github.com/open-telemetry/semantic-conventions/pull/399)) +- Add cardinality warning about two opt-in HTTP metric attributes to all HTTP metrics. + ([#412](https://github.com/open-telemetry/semantic-conventions/pull/412)) ## v1.22.0 (2023-10-12) diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index d2a73412f..1aa35b7e0 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -135,6 +135,9 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin 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 +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. @@ -142,6 +145,9 @@ SHOULD NOT be set if only IP address is available and capturing name would requi if it's sent in absolute-form. - 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 +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. `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. @@ -316,6 +322,9 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin 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 +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. @@ -323,6 +332,9 @@ SHOULD NOT be set if only IP address is available and capturing name would requi if it's sent in absolute-form. - 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 +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. `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. @@ -423,6 +435,9 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin 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 +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. @@ -430,6 +445,9 @@ SHOULD NOT be set if only IP address is available and capturing name would requi if it's sent in absolute-form. - 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 +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. `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/model/metrics/http.yaml b/model/metrics/http.yaml index 2596a06f0..474c99fa7 100644 --- a/model/metrics/http.yaml +++ b/model/metrics/http.yaml @@ -6,8 +6,32 @@ groups: attributes: - ref: server.address requirement_level: opt_in + 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. + - 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. + + Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker + to trigger cardinality limits, degrading the usefulness of the metric. + - ref: server.port requirement_level: opt_in + note: | + 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 the `Host` header + + Warning: since this attribute may be based on the `Host` header, opting in to it may allow an attacker + to trigger cardinality limits, degrading the usefulness of the metric. - id: metric_attributes.http.client type: attribute_group