From e21b489b5fb27f0520343ef918daa9e9b7a3773f Mon Sep 17 00:00:00 2001
From: "Anthony Turcios (anthoturc)" <anthony@buoyant.io>
Date: Wed, 12 Aug 2026 21:16:47 -0400
Subject: [PATCH] docs(proxy-metrics): add section about metrics expiry to
 2.10-latest

this addresses an ask in linkerd/linkerd2#6222
---
 .../content/2-edge/reference/proxy-metrics.md | 35 +++++++++++++++++++
 .../content/2.10/reference/proxy-metrics.md   | 35 +++++++++++++++++++
 .../content/2.11/reference/proxy-metrics.md   | 35 +++++++++++++++++++
 .../content/2.12/reference/proxy-metrics.md   | 35 +++++++++++++++++++
 .../content/2.13/reference/proxy-metrics.md   | 35 +++++++++++++++++++
 .../content/2.14/reference/proxy-metrics.md   | 35 +++++++++++++++++++
 .../content/2.15/reference/proxy-metrics.md   | 35 +++++++++++++++++++
 .../content/2.16/reference/proxy-metrics.md   | 35 +++++++++++++++++++
 .../content/2.17/reference/proxy-metrics.md   | 35 +++++++++++++++++++
 .../content/2.18/reference/proxy-metrics.md   | 35 +++++++++++++++++++
 .../content/2.19/reference/proxy-metrics.md   | 35 +++++++++++++++++++
 .../content/docs/reference/proxy-metrics.md   | 35 +++++++++++++++++++
 12 files changed, 420 insertions(+)

diff --git a/linkerd.io/content/2-edge/reference/proxy-metrics.md b/linkerd.io/content/2-edge/reference/proxy-metrics.md
index 63907d169d..cb02bc82e1 100644
--- a/linkerd.io/content/2-edge/reference/proxy-metrics.md
+++ b/linkerd.io/content/2-edge/reference/proxy-metrics.md
@@ -370,3 +370,38 @@ following labels:
   https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#pod-template-hash-label
 [ttfb]: https://en.wikipedia.org/wiki/Time_to_first_byte
 [HTTPRoute]: httproute/
+
+## Metric Expiry
+
+The Linkerd proxy emits some metrics that have high-cardinality labels. For example,
+clusters with a large number of meshed nodes may have many IP addresses for the
+same label. This can be an issue in a long running proxy because it will lead to
+higher memory usage.
+
+Linkerd proxy attempts to limit the number of high-cardinality metrics by discarding
+"unused" or "idle" metrics during each prometheus scrape. A metric is considered
+"unused" if no component within the proxy is referring to it. For example, a TCP
+connection terminates and a metric related to the TCP connection is no longer
+referred to. A metric is considered "idle" if it has not been updated within a
+predefined period of time. The default period of time is 10 minutes, but the default
+can be set by configuring `LINKERD2_PROXY_METRICS_RETAIN_IDLE`.
+
+Metric expiry applies to the following metrics within the proxy:
+
+- `request_total`
+- `response_total`
+- `response_latency_ms`
+- `route_request_total`
+- `route_response_total`
+- `route_response_latency_ms`
+- `route_actual_request_total`
+- `route_actual_response_total`
+- `route_retryable_total`
+- `control_request_total`
+- `control_response_total`
+- `control_response_latency_ms`
+- `tcp_open_total`
+- `tcp_open_connections`
+- `tcp_read_bytes_total`
+- `tcp_write_bytes_total`
+- `tcp_close_total`
diff --git a/linkerd.io/content/2.10/reference/proxy-metrics.md b/linkerd.io/content/2.10/reference/proxy-metrics.md
index c1de1e9830..84e2abd44a 100644
--- a/linkerd.io/content/2.10/reference/proxy-metrics.md
+++ b/linkerd.io/content/2.10/reference/proxy-metrics.md
@@ -195,3 +195,38 @@ connection closes (`tcp_close_total`):
   UNIX epoch).
 - `identity_cert_refresh_count`: A counter of the total number of times the
   proxy's mTLS identity certificate has been refreshed by the Identity service.
+
+## Metric Expiry
+
+The Linkerd proxy emits some metrics that have high-cardinality labels. For example,
+clusters with a large number of meshed nodes may have many IP addresses for the
+same label. This can be an issue in a long running proxy because it will lead to
+higher memory usage.
+
+Linkerd proxy attempts to limit the number of high-cardinality metrics by discarding
+"unused" or "idle" metrics during each prometheus scrape. A metric is considered
+"unused" if no component within the proxy is referring to it. For example, a TCP
+connection terminates and a metric related to the TCP connection is no longer
+referred to. A metric is considered "idle" if it has not been updated within a
+predefined period of time. The default period of time is 10 minutes, but the default
+can be set by configuring `LINKERD2_PROXY_METRICS_RETAIN_IDLE`.
+
+Metric expiry applies to the following metrics within the proxy:
+
+- `request_total`
+- `response_total`
+- `response_latency_ms`
+- `route_request_total`
+- `route_response_total`
+- `route_response_latency_ms`
+- `route_actual_request_total`
+- `route_actual_response_total`
+- `route_retryable_total`
+- `control_request_total`
+- `control_response_total`
+- `control_response_latency_ms`
+- `tcp_open_total`
+- `tcp_open_connections`
+- `tcp_read_bytes_total`
+- `tcp_write_bytes_total`
+- `tcp_close_total`
diff --git a/linkerd.io/content/2.11/reference/proxy-metrics.md b/linkerd.io/content/2.11/reference/proxy-metrics.md
index c1de1e9830..84e2abd44a 100644
--- a/linkerd.io/content/2.11/reference/proxy-metrics.md
+++ b/linkerd.io/content/2.11/reference/proxy-metrics.md
@@ -195,3 +195,38 @@ connection closes (`tcp_close_total`):
   UNIX epoch).
 - `identity_cert_refresh_count`: A counter of the total number of times the
   proxy's mTLS identity certificate has been refreshed by the Identity service.
+
+## Metric Expiry
+
+The Linkerd proxy emits some metrics that have high-cardinality labels. For example,
+clusters with a large number of meshed nodes may have many IP addresses for the
+same label. This can be an issue in a long running proxy because it will lead to
+higher memory usage.
+
+Linkerd proxy attempts to limit the number of high-cardinality metrics by discarding
+"unused" or "idle" metrics during each prometheus scrape. A metric is considered
+"unused" if no component within the proxy is referring to it. For example, a TCP
+connection terminates and a metric related to the TCP connection is no longer
+referred to. A metric is considered "idle" if it has not been updated within a
+predefined period of time. The default period of time is 10 minutes, but the default
+can be set by configuring `LINKERD2_PROXY_METRICS_RETAIN_IDLE`.
+
+Metric expiry applies to the following metrics within the proxy:
+
+- `request_total`
+- `response_total`
+- `response_latency_ms`
+- `route_request_total`
+- `route_response_total`
+- `route_response_latency_ms`
+- `route_actual_request_total`
+- `route_actual_response_total`
+- `route_retryable_total`
+- `control_request_total`
+- `control_response_total`
+- `control_response_latency_ms`
+- `tcp_open_total`
+- `tcp_open_connections`
+- `tcp_read_bytes_total`
+- `tcp_write_bytes_total`
+- `tcp_close_total`
diff --git a/linkerd.io/content/2.12/reference/proxy-metrics.md b/linkerd.io/content/2.12/reference/proxy-metrics.md
index 07596a0527..cef72bfc06 100644
--- a/linkerd.io/content/2.12/reference/proxy-metrics.md
+++ b/linkerd.io/content/2.12/reference/proxy-metrics.md
@@ -231,3 +231,38 @@ connection closes (`tcp_close_total`):
   UNIX epoch).
 - `identity_cert_refresh_count`: A counter of the total number of times the
   proxy's mTLS identity certificate has been refreshed by the Identity service.
+
+## Metric Expiry
+
+The Linkerd proxy emits some metrics that have high-cardinality labels. For example,
+clusters with a large number of meshed nodes may have many IP addresses for the
+same label. This can be an issue in a long running proxy because it will lead to
+higher memory usage.
+
+Linkerd proxy attempts to limit the number of high-cardinality metrics by discarding
+"unused" or "idle" metrics during each prometheus scrape. A metric is considered
+"unused" if no component within the proxy is referring to it. For example, a TCP
+connection terminates and a metric related to the TCP connection is no longer
+referred to. A metric is considered "idle" if it has not been updated within a
+predefined period of time. The default period of time is 10 minutes, but the default
+can be set by configuring `LINKERD2_PROXY_METRICS_RETAIN_IDLE`.
+
+Metric expiry applies to the following metrics within the proxy:
+
+- `request_total`
+- `response_total`
+- `response_latency_ms`
+- `route_request_total`
+- `route_response_total`
+- `route_response_latency_ms`
+- `route_actual_request_total`
+- `route_actual_response_total`
+- `route_retryable_total`
+- `control_request_total`
+- `control_response_total`
+- `control_response_latency_ms`
+- `tcp_open_total`
+- `tcp_open_connections`
+- `tcp_read_bytes_total`
+- `tcp_write_bytes_total`
+- `tcp_close_total`
diff --git a/linkerd.io/content/2.13/reference/proxy-metrics.md b/linkerd.io/content/2.13/reference/proxy-metrics.md
index b155c78099..47d8167e23 100644
--- a/linkerd.io/content/2.13/reference/proxy-metrics.md
+++ b/linkerd.io/content/2.13/reference/proxy-metrics.md
@@ -271,3 +271,38 @@ following labels:
 [pod-template-hash]:
   https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#pod-template-hash-label
 [ttfb]: https://en.wikipedia.org/wiki/Time_to_first_byte
+
+## Metric Expiry
+
+The Linkerd proxy emits some metrics that have high-cardinality labels. For example,
+clusters with a large number of meshed nodes may have many IP addresses for the
+same label. This can be an issue in a long running proxy because it will lead to
+higher memory usage.
+
+Linkerd proxy attempts to limit the number of high-cardinality metrics by discarding
+"unused" or "idle" metrics during each prometheus scrape. A metric is considered
+"unused" if no component within the proxy is referring to it. For example, a TCP
+connection terminates and a metric related to the TCP connection is no longer
+referred to. A metric is considered "idle" if it has not been updated within a
+predefined period of time. The default period of time is 10 minutes, but the default
+can be set by configuring `LINKERD2_PROXY_METRICS_RETAIN_IDLE`.
+
+Metric expiry applies to the following metrics within the proxy:
+
+- `request_total`
+- `response_total`
+- `response_latency_ms`
+- `route_request_total`
+- `route_response_total`
+- `route_response_latency_ms`
+- `route_actual_request_total`
+- `route_actual_response_total`
+- `route_retryable_total`
+- `control_request_total`
+- `control_response_total`
+- `control_response_latency_ms`
+- `tcp_open_total`
+- `tcp_open_connections`
+- `tcp_read_bytes_total`
+- `tcp_write_bytes_total`
+- `tcp_close_total`
diff --git a/linkerd.io/content/2.14/reference/proxy-metrics.md b/linkerd.io/content/2.14/reference/proxy-metrics.md
index bb00c5595c..c341cdeaca 100644
--- a/linkerd.io/content/2.14/reference/proxy-metrics.md
+++ b/linkerd.io/content/2.14/reference/proxy-metrics.md
@@ -272,3 +272,38 @@ following labels:
   https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#pod-template-hash-label
 [ttfb]: https://en.wikipedia.org/wiki/Time_to_first_byte
 [HTTPRoute]: ../features/httproute/
+
+## Metric Expiry
+
+The Linkerd proxy emits some metrics that have high-cardinality labels. For example,
+clusters with a large number of meshed nodes may have many IP addresses for the
+same label. This can be an issue in a long running proxy because it will lead to
+higher memory usage.
+
+Linkerd proxy attempts to limit the number of high-cardinality metrics by discarding
+"unused" or "idle" metrics during each prometheus scrape. A metric is considered
+"unused" if no component within the proxy is referring to it. For example, a TCP
+connection terminates and a metric related to the TCP connection is no longer
+referred to. A metric is considered "idle" if it has not been updated within a
+predefined period of time. The default period of time is 10 minutes, but the default
+can be set by configuring `LINKERD2_PROXY_METRICS_RETAIN_IDLE`.
+
+Metric expiry applies to the following metrics within the proxy:
+
+- `request_total`
+- `response_total`
+- `response_latency_ms`
+- `route_request_total`
+- `route_response_total`
+- `route_response_latency_ms`
+- `route_actual_request_total`
+- `route_actual_response_total`
+- `route_retryable_total`
+- `control_request_total`
+- `control_response_total`
+- `control_response_latency_ms`
+- `tcp_open_total`
+- `tcp_open_connections`
+- `tcp_read_bytes_total`
+- `tcp_write_bytes_total`
+- `tcp_close_total`
diff --git a/linkerd.io/content/2.15/reference/proxy-metrics.md b/linkerd.io/content/2.15/reference/proxy-metrics.md
index bb00c5595c..c341cdeaca 100644
--- a/linkerd.io/content/2.15/reference/proxy-metrics.md
+++ b/linkerd.io/content/2.15/reference/proxy-metrics.md
@@ -272,3 +272,38 @@ following labels:
   https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#pod-template-hash-label
 [ttfb]: https://en.wikipedia.org/wiki/Time_to_first_byte
 [HTTPRoute]: ../features/httproute/
+
+## Metric Expiry
+
+The Linkerd proxy emits some metrics that have high-cardinality labels. For example,
+clusters with a large number of meshed nodes may have many IP addresses for the
+same label. This can be an issue in a long running proxy because it will lead to
+higher memory usage.
+
+Linkerd proxy attempts to limit the number of high-cardinality metrics by discarding
+"unused" or "idle" metrics during each prometheus scrape. A metric is considered
+"unused" if no component within the proxy is referring to it. For example, a TCP
+connection terminates and a metric related to the TCP connection is no longer
+referred to. A metric is considered "idle" if it has not been updated within a
+predefined period of time. The default period of time is 10 minutes, but the default
+can be set by configuring `LINKERD2_PROXY_METRICS_RETAIN_IDLE`.
+
+Metric expiry applies to the following metrics within the proxy:
+
+- `request_total`
+- `response_total`
+- `response_latency_ms`
+- `route_request_total`
+- `route_response_total`
+- `route_response_latency_ms`
+- `route_actual_request_total`
+- `route_actual_response_total`
+- `route_retryable_total`
+- `control_request_total`
+- `control_response_total`
+- `control_response_latency_ms`
+- `tcp_open_total`
+- `tcp_open_connections`
+- `tcp_read_bytes_total`
+- `tcp_write_bytes_total`
+- `tcp_close_total`
diff --git a/linkerd.io/content/2.16/reference/proxy-metrics.md b/linkerd.io/content/2.16/reference/proxy-metrics.md
index 238a65f604..3fa18e3a4e 100644
--- a/linkerd.io/content/2.16/reference/proxy-metrics.md
+++ b/linkerd.io/content/2.16/reference/proxy-metrics.md
@@ -290,3 +290,38 @@ following labels:
   https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#pod-template-hash-label
 [ttfb]: https://en.wikipedia.org/wiki/Time_to_first_byte
 [HTTPRoute]: httproute/
+
+## Metric Expiry
+
+The Linkerd proxy emits some metrics that have high-cardinality labels. For example,
+clusters with a large number of meshed nodes may have many IP addresses for the
+same label. This can be an issue in a long running proxy because it will lead to
+higher memory usage.
+
+Linkerd proxy attempts to limit the number of high-cardinality metrics by discarding
+"unused" or "idle" metrics during each prometheus scrape. A metric is considered
+"unused" if no component within the proxy is referring to it. For example, a TCP
+connection terminates and a metric related to the TCP connection is no longer
+referred to. A metric is considered "idle" if it has not been updated within a
+predefined period of time. The default period of time is 10 minutes, but the default
+can be set by configuring `LINKERD2_PROXY_METRICS_RETAIN_IDLE`.
+
+Metric expiry applies to the following metrics within the proxy:
+
+- `request_total`
+- `response_total`
+- `response_latency_ms`
+- `route_request_total`
+- `route_response_total`
+- `route_response_latency_ms`
+- `route_actual_request_total`
+- `route_actual_response_total`
+- `route_retryable_total`
+- `control_request_total`
+- `control_response_total`
+- `control_response_latency_ms`
+- `tcp_open_total`
+- `tcp_open_connections`
+- `tcp_read_bytes_total`
+- `tcp_write_bytes_total`
+- `tcp_close_total`
diff --git a/linkerd.io/content/2.17/reference/proxy-metrics.md b/linkerd.io/content/2.17/reference/proxy-metrics.md
index 238a65f604..3fa18e3a4e 100644
--- a/linkerd.io/content/2.17/reference/proxy-metrics.md
+++ b/linkerd.io/content/2.17/reference/proxy-metrics.md
@@ -290,3 +290,38 @@ following labels:
   https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#pod-template-hash-label
 [ttfb]: https://en.wikipedia.org/wiki/Time_to_first_byte
 [HTTPRoute]: httproute/
+
+## Metric Expiry
+
+The Linkerd proxy emits some metrics that have high-cardinality labels. For example,
+clusters with a large number of meshed nodes may have many IP addresses for the
+same label. This can be an issue in a long running proxy because it will lead to
+higher memory usage.
+
+Linkerd proxy attempts to limit the number of high-cardinality metrics by discarding
+"unused" or "idle" metrics during each prometheus scrape. A metric is considered
+"unused" if no component within the proxy is referring to it. For example, a TCP
+connection terminates and a metric related to the TCP connection is no longer
+referred to. A metric is considered "idle" if it has not been updated within a
+predefined period of time. The default period of time is 10 minutes, but the default
+can be set by configuring `LINKERD2_PROXY_METRICS_RETAIN_IDLE`.
+
+Metric expiry applies to the following metrics within the proxy:
+
+- `request_total`
+- `response_total`
+- `response_latency_ms`
+- `route_request_total`
+- `route_response_total`
+- `route_response_latency_ms`
+- `route_actual_request_total`
+- `route_actual_response_total`
+- `route_retryable_total`
+- `control_request_total`
+- `control_response_total`
+- `control_response_latency_ms`
+- `tcp_open_total`
+- `tcp_open_connections`
+- `tcp_read_bytes_total`
+- `tcp_write_bytes_total`
+- `tcp_close_total`
diff --git a/linkerd.io/content/2.18/reference/proxy-metrics.md b/linkerd.io/content/2.18/reference/proxy-metrics.md
index 238a65f604..3fa18e3a4e 100644
--- a/linkerd.io/content/2.18/reference/proxy-metrics.md
+++ b/linkerd.io/content/2.18/reference/proxy-metrics.md
@@ -290,3 +290,38 @@ following labels:
   https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#pod-template-hash-label
 [ttfb]: https://en.wikipedia.org/wiki/Time_to_first_byte
 [HTTPRoute]: httproute/
+
+## Metric Expiry
+
+The Linkerd proxy emits some metrics that have high-cardinality labels. For example,
+clusters with a large number of meshed nodes may have many IP addresses for the
+same label. This can be an issue in a long running proxy because it will lead to
+higher memory usage.
+
+Linkerd proxy attempts to limit the number of high-cardinality metrics by discarding
+"unused" or "idle" metrics during each prometheus scrape. A metric is considered
+"unused" if no component within the proxy is referring to it. For example, a TCP
+connection terminates and a metric related to the TCP connection is no longer
+referred to. A metric is considered "idle" if it has not been updated within a
+predefined period of time. The default period of time is 10 minutes, but the default
+can be set by configuring `LINKERD2_PROXY_METRICS_RETAIN_IDLE`.
+
+Metric expiry applies to the following metrics within the proxy:
+
+- `request_total`
+- `response_total`
+- `response_latency_ms`
+- `route_request_total`
+- `route_response_total`
+- `route_response_latency_ms`
+- `route_actual_request_total`
+- `route_actual_response_total`
+- `route_retryable_total`
+- `control_request_total`
+- `control_response_total`
+- `control_response_latency_ms`
+- `tcp_open_total`
+- `tcp_open_connections`
+- `tcp_read_bytes_total`
+- `tcp_write_bytes_total`
+- `tcp_close_total`
diff --git a/linkerd.io/content/2.19/reference/proxy-metrics.md b/linkerd.io/content/2.19/reference/proxy-metrics.md
index 6d8881fce8..3bad778b24 100644
--- a/linkerd.io/content/2.19/reference/proxy-metrics.md
+++ b/linkerd.io/content/2.19/reference/proxy-metrics.md
@@ -339,3 +339,38 @@ following labels:
   https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#pod-template-hash-label
 [ttfb]: https://en.wikipedia.org/wiki/Time_to_first_byte
 [HTTPRoute]: httproute/
+
+## Metric Expiry
+
+The Linkerd proxy emits some metrics that have high-cardinality labels. For example,
+clusters with a large number of meshed nodes may have many IP addresses for the
+same label. This can be an issue in a long running proxy because it will lead to
+higher memory usage.
+
+Linkerd proxy attempts to limit the number of high-cardinality metrics by discarding
+"unused" or "idle" metrics during each prometheus scrape. A metric is considered
+"unused" if no component within the proxy is referring to it. For example, a TCP
+connection terminates and a metric related to the TCP connection is no longer
+referred to. A metric is considered "idle" if it has not been updated within a
+predefined period of time. The default period of time is 10 minutes, but the default
+can be set by configuring `LINKERD2_PROXY_METRICS_RETAIN_IDLE`.
+
+Metric expiry applies to the following metrics within the proxy:
+
+- `request_total`
+- `response_total`
+- `response_latency_ms`
+- `route_request_total`
+- `route_response_total`
+- `route_response_latency_ms`
+- `route_actual_request_total`
+- `route_actual_response_total`
+- `route_retryable_total`
+- `control_request_total`
+- `control_response_total`
+- `control_response_latency_ms`
+- `tcp_open_total`
+- `tcp_open_connections`
+- `tcp_read_bytes_total`
+- `tcp_write_bytes_total`
+- `tcp_close_total`
diff --git a/linkerd.io/content/docs/reference/proxy-metrics.md b/linkerd.io/content/docs/reference/proxy-metrics.md
index 63907d169d..cb02bc82e1 100644
--- a/linkerd.io/content/docs/reference/proxy-metrics.md
+++ b/linkerd.io/content/docs/reference/proxy-metrics.md
@@ -370,3 +370,38 @@ following labels:
   https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#pod-template-hash-label
 [ttfb]: https://en.wikipedia.org/wiki/Time_to_first_byte
 [HTTPRoute]: httproute/
+
+## Metric Expiry
+
+The Linkerd proxy emits some metrics that have high-cardinality labels. For example,
+clusters with a large number of meshed nodes may have many IP addresses for the
+same label. This can be an issue in a long running proxy because it will lead to
+higher memory usage.
+
+Linkerd proxy attempts to limit the number of high-cardinality metrics by discarding
+"unused" or "idle" metrics during each prometheus scrape. A metric is considered
+"unused" if no component within the proxy is referring to it. For example, a TCP
+connection terminates and a metric related to the TCP connection is no longer
+referred to. A metric is considered "idle" if it has not been updated within a
+predefined period of time. The default period of time is 10 minutes, but the default
+can be set by configuring `LINKERD2_PROXY_METRICS_RETAIN_IDLE`.
+
+Metric expiry applies to the following metrics within the proxy:
+
+- `request_total`
+- `response_total`
+- `response_latency_ms`
+- `route_request_total`
+- `route_response_total`
+- `route_response_latency_ms`
+- `route_actual_request_total`
+- `route_actual_response_total`
+- `route_retryable_total`
+- `control_request_total`
+- `control_response_total`
+- `control_response_latency_ms`
+- `tcp_open_total`
+- `tcp_open_connections`
+- `tcp_read_bytes_total`
+- `tcp_write_bytes_total`
+- `tcp_close_total`