From 4d245a4b7c237e566a9353cd8780fd2db9e80975 Mon Sep 17 00:00:00 2001 From: cijothomas Date: Fri, 29 May 2026 13:07:51 -0700 Subject: [PATCH 1/3] Change network.peer.address to opt-in on http.client.open_connections (related to #3279) --- .chloggen/http-peer-address-opt-in.yaml | 28 +++++++++++++++++++++++++ docs/http/http-metrics.md | 4 +++- model/http/metrics.yaml | 7 ++++++- 3 files changed, 37 insertions(+), 2 deletions(-) create mode 100644 .chloggen/http-peer-address-opt-in.yaml diff --git a/.chloggen/http-peer-address-opt-in.yaml b/.chloggen/http-peer-address-opt-in.yaml new file mode 100644 index 0000000000..6a7c441c55 --- /dev/null +++ b/.chloggen/http-peer-address-opt-in.yaml @@ -0,0 +1,28 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: breaking + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: http + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Change `network.peer.address` attribute requirement level from Recommended to Opt-In on the `http.client.open_connections` metric. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [3279] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: | + `network.peer.address` is typically high-cardinality (one time series per remote IP). + On `http.client.open_connections` (an UpDownCounter, always exported with cumulative + temporality) this caused unbounded growth of metric streams over the lifetime of the + process, exhausting SDK cardinality limits and collapsing useful low-cardinality + attributes (e.g. `url.scheme`) into the overflow bucket. Operators that need this + attribute can still opt-in. diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 4340499507..ba84006ca0 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -951,8 +951,8 @@ This metric is optional. | [`http.connection.state`](/docs/registry/attributes/http.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | State of the HTTP connection in the HTTP connection pool. | `active`; `idle` | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | int | Server port number. [2] | `80`; `8080`; `443` | -| [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | | [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [3] | `1.1`; `2` | +| [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | string | Peer address of the network connection - IP address or Unix domain socket name. [4] | `10.1.2.80`; `/tmp/my.sock` | | [`url.scheme`](/docs/registry/attributes/url.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | **[1] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. @@ -961,6 +961,8 @@ This metric is optional. **[3] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. +**[4] `network.peer.address`:** `network.peer.address` is opt-in because it is typically high-cardinality (one time series per remote IP) and, combined with the cumulative temporality of UpDownCounter, can cause unbounded memory growth and metric stream accumulation in the SDK over the lifetime of the process. + --- `http.connection.state` 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/http/metrics.yaml b/model/http/metrics.yaml index fcf4846e01..ed00d995a9 100644 --- a/model/http/metrics.yaml +++ b/model/http/metrics.yaml @@ -177,7 +177,12 @@ groups: - ref: http.connection.state requirement_level: required - ref: network.peer.address - requirement_level: recommended + requirement_level: opt_in + note: > + `network.peer.address` is opt-in because it is typically high-cardinality + (one time series per remote IP) and, combined with the cumulative temporality + of UpDownCounter, can cause unbounded memory growth and metric stream + accumulation in the SDK over the lifetime of the process. - ref: network.protocol.version requirement_level: recommended - ref: server.address From d7742c6c9a74d447dcad94a81a1bfada29c641fe Mon Sep 17 00:00:00 2001 From: cijothomas Date: Fri, 29 May 2026 14:43:47 -0700 Subject: [PATCH 2/3] Address review feedback: drop spec note on network.peer.address --- docs/http/http-metrics.md | 4 +--- model/http/metrics.yaml | 5 ----- 2 files changed, 1 insertion(+), 8 deletions(-) diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index ba84006ca0..6f94ea2a0f 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -952,7 +952,7 @@ This metric is optional. | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | int | Server port number. [2] | `80`; `8080`; `443` | | [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [3] | `1.1`; `2` | -| [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | string | Peer address of the network connection - IP address or Unix domain socket name. [4] | `10.1.2.80`; `/tmp/my.sock` | +| [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | | [`url.scheme`](/docs/registry/attributes/url.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | **[1] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. @@ -961,8 +961,6 @@ This metric is optional. **[3] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[4] `network.peer.address`:** `network.peer.address` is opt-in because it is typically high-cardinality (one time series per remote IP) and, combined with the cumulative temporality of UpDownCounter, can cause unbounded memory growth and metric stream accumulation in the SDK over the lifetime of the process. - --- `http.connection.state` 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/http/metrics.yaml b/model/http/metrics.yaml index ed00d995a9..8fef8b2b57 100644 --- a/model/http/metrics.yaml +++ b/model/http/metrics.yaml @@ -178,11 +178,6 @@ groups: requirement_level: required - ref: network.peer.address requirement_level: opt_in - note: > - `network.peer.address` is opt-in because it is typically high-cardinality - (one time series per remote IP) and, combined with the cumulative temporality - of UpDownCounter, can cause unbounded memory growth and metric stream - accumulation in the SDK over the lifetime of the process. - ref: network.protocol.version requirement_level: recommended - ref: server.address From 670385f28e5a09540feaaab2163d052091e6981f Mon Sep 17 00:00:00 2001 From: cijothomas Date: Mon, 1 Jun 2026 07:21:12 -0700 Subject: [PATCH 3/3] Also flip network.peer.address to opt-in on http.client.connection.duration for consistency --- .chloggen/http-peer-address-opt-in.yaml | 14 +++++++------- docs/http/http-metrics.md | 2 +- model/http/metrics.yaml | 2 +- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/.chloggen/http-peer-address-opt-in.yaml b/.chloggen/http-peer-address-opt-in.yaml index 6a7c441c55..cdbe77e8b6 100644 --- a/.chloggen/http-peer-address-opt-in.yaml +++ b/.chloggen/http-peer-address-opt-in.yaml @@ -10,7 +10,7 @@ change_type: breaking component: http # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). -note: Change `network.peer.address` attribute requirement level from Recommended to Opt-In on the `http.client.open_connections` metric. +note: Change `network.peer.address` attribute requirement level from Recommended to Opt-In on the `http.client.open_connections` and `http.client.connection.duration` metrics. # Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. # The values here must be integers. @@ -20,9 +20,9 @@ issues: [3279] # These lines will be padded with 2 spaces and then inserted directly into the document. # Use pipe (|) for multiline entries. subtext: | - `network.peer.address` is typically high-cardinality (one time series per remote IP). - On `http.client.open_connections` (an UpDownCounter, always exported with cumulative - temporality) this caused unbounded growth of metric streams over the lifetime of the - process, exhausting SDK cardinality limits and collapsing useful low-cardinality - attributes (e.g. `url.scheme`) into the overflow bucket. Operators that need this - attribute can still opt-in. + `network.peer.address` is typically high-cardinality (one time series per remote IP) + and causes unbounded growth of metric streams over the lifetime of the process when + exported with cumulative temporality (always the case for `http.client.open_connections` + since it is an UpDownCounter, and possible for `http.client.connection.duration` when + the histogram is configured for cumulative). Operators that need this attribute can + still opt-in. diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 6f94ea2a0f..17dbc901a8 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -995,8 +995,8 @@ This metric is optional. | --- | --- | --- | --- | --- | --- | | [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Required` | int | Server port number. [2] | `80`; `8080`; `443` | -| [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | | [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [3] | `1.1`; `2` | +| [`network.peer.address`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | | [`url.scheme`](/docs/registry/attributes/url.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | **[1] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. diff --git a/model/http/metrics.yaml b/model/http/metrics.yaml index 8fef8b2b57..3659cef3cb 100644 --- a/model/http/metrics.yaml +++ b/model/http/metrics.yaml @@ -200,7 +200,7 @@ groups: unit: "s" attributes: - ref: network.peer.address - requirement_level: recommended + requirement_level: opt_in - ref: network.protocol.version requirement_level: recommended - ref: server.address