From 0489469a07b192b0defd93efed9c2f8cc1682d5a Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Tue, 12 Aug 2025 12:47:33 +0200 Subject: [PATCH 01/14] Add Cardinality Limits section --- sdk/metric/doc.go | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/sdk/metric/doc.go b/sdk/metric/doc.go index 90a4ae16c1a..a90091f31eb 100644 --- a/sdk/metric/doc.go +++ b/sdk/metric/doc.go @@ -39,6 +39,30 @@ // Meter.RegisterCallback and Registration.Unregister to add and remove // callbacks without leaking memory. // +// # Cardinality Limits +// +// Cardinality refers to the number of unique attribute combinations for a single +// metric within one collection (export) interval. High cardinality can lead to +// excessive memory usage, increased storage costs, and backend performance issues. +// +// The Go OpenTelemetry SDK does not enforce a cardinality limit by default. +// A limit can be configured via the API using the `WithCardinalityLimit` +// option. +// +// When the configured limit is reached, any new attribute combination is not +// tracked separately. Instead, its measurements are aggregated together under +// a special attribute set containing `{"otel.metric.overflow": true}`. +// This ensures total metric values (e.g., Sum, Count) remain correct for the +// collection interval, but information about the specific dropped combinations +// is not preserved. +// +// Recommendations: +// +// - Set the limit based on the theoretical maximum combinations or expected +// active combinations per export interval. +// - Too high - wastes memory due to preallocation. +// - Too low - causes loss of attribute detail as more data falls into overflow. +// // See [go.opentelemetry.io/otel/metric] for more information about // the metric API. // From 7b53f1734bceec28d008d8b1833147df4fb0040b Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Tue, 12 Aug 2025 12:53:01 +0200 Subject: [PATCH 02/14] Changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c8630bbd0f7..1c112362bab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,7 +41,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm - `RPCGRPCResponseMetadata` - Add `ErrorType` attribute helper function to the `go.opentelmetry.io/otel/semconv/v1.34.0` package. (#6962) - Add `WithAllowKeyDuplication` in `go.opentelemetry.io/otel/sdk/log` which can be used to disable deduplication for log records. (#6968) -- Add `WithCardinalityLimit` option to configure the cardinality limit in `go.opentelemetry.io/otel/sdk/metric`. (#6996, #7065, #7081, #7164, #7165) +- Add `WithCardinalityLimit` option to configure the cardinality limit in `go.opentelemetry.io/otel/sdk/metric`. (#6996, #7065, #7081, #7164, #7165, #7179) - Add `Clone` method to `Record` in `go.opentelemetry.io/otel/log` that returns a copy of the record with no shared state. (#7001) - The `go.opentelemetry.io/otel/semconv/v1.36.0` package. The package contains semantic conventions from the `v1.36.0` version of the OpenTelemetry Semantic Conventions. From bf74c42179c0d5854c4d8e7c4d214d6e8a021e66 Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Tue, 12 Aug 2025 13:42:19 +0200 Subject: [PATCH 03/14] Update sdk/metric/doc.go MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- sdk/metric/doc.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/metric/doc.go b/sdk/metric/doc.go index a90091f31eb..cf9eae5e01c 100644 --- a/sdk/metric/doc.go +++ b/sdk/metric/doc.go @@ -45,7 +45,7 @@ // metric within one collection (export) interval. High cardinality can lead to // excessive memory usage, increased storage costs, and backend performance issues. // -// The Go OpenTelemetry SDK does not enforce a cardinality limit by default. +// The OpenTelemetry Go Metric SDK does not enforce a cardinality limit by default. // A limit can be configured via the API using the `WithCardinalityLimit` // option. // From 8e8f9a9ea7a337d6ad3fe58be96d55549f0d05d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Thu, 14 Aug 2025 10:26:18 +0200 Subject: [PATCH 04/14] Update sdk/metric/doc.go --- sdk/metric/doc.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/metric/doc.go b/sdk/metric/doc.go index cf9eae5e01c..5a99480d6eb 100644 --- a/sdk/metric/doc.go +++ b/sdk/metric/doc.go @@ -46,7 +46,7 @@ // excessive memory usage, increased storage costs, and backend performance issues. // // The OpenTelemetry Go Metric SDK does not enforce a cardinality limit by default. -// A limit can be configured via the API using the `WithCardinalityLimit` +// A limit can be configured using the [WithCardinalityLimit] // option. // // When the configured limit is reached, any new attribute combination is not From 9aa43a448a94c773a4d8064014ce3459f277c17d Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Mon, 18 Aug 2025 09:25:36 +0200 Subject: [PATCH 05/14] Update sdk/metric/doc.go Co-authored-by: Tyler Yahn --- sdk/metric/doc.go | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sdk/metric/doc.go b/sdk/metric/doc.go index 5a99480d6eb..826def636c9 100644 --- a/sdk/metric/doc.go +++ b/sdk/metric/doc.go @@ -45,9 +45,9 @@ // metric within one collection (export) interval. High cardinality can lead to // excessive memory usage, increased storage costs, and backend performance issues. // -// The OpenTelemetry Go Metric SDK does not enforce a cardinality limit by default. -// A limit can be configured using the [WithCardinalityLimit] -// option. +// Currently, the OpenTelemetry Go Metric SDK does not enforce a cardinality limit by default +// (note that this may change in a future release). Use [WithCardinalityLimit] to set the +// cardinality limit as desired. // // When the configured limit is reached, any new attribute combination is not // tracked separately. Instead, its measurements are aggregated together under From 7f3a212b8add22a5660244189d9f91f52a38c7a9 Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Mon, 18 Aug 2025 09:25:56 +0200 Subject: [PATCH 06/14] Update sdk/metric/doc.go Co-authored-by: Tyler Yahn --- sdk/metric/doc.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/metric/doc.go b/sdk/metric/doc.go index 826def636c9..eecf1f3fdad 100644 --- a/sdk/metric/doc.go +++ b/sdk/metric/doc.go @@ -49,8 +49,8 @@ // (note that this may change in a future release). Use [WithCardinalityLimit] to set the // cardinality limit as desired. // -// When the configured limit is reached, any new attribute combination is not -// tracked separately. Instead, its measurements are aggregated together under +// New attribute sets are dropped when the cardinality limit is reached. The measurement of +// these sets are aggregated into // a special attribute set containing `{"otel.metric.overflow": true}`. // This ensures total metric values (e.g., Sum, Count) remain correct for the // collection interval, but information about the specific dropped combinations From 497a6fffe77d32bd4178be75d3f9533c89317231 Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Mon, 18 Aug 2025 09:34:08 +0200 Subject: [PATCH 07/14] add otel recommendation/ update too-high case --- sdk/metric/doc.go | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/sdk/metric/doc.go b/sdk/metric/doc.go index eecf1f3fdad..41be733c518 100644 --- a/sdk/metric/doc.go +++ b/sdk/metric/doc.go @@ -59,8 +59,9 @@ // Recommendations: // // - Set the limit based on the theoretical maximum combinations or expected -// active combinations per export interval. -// - Too high - wastes memory due to preallocation. +// active combinations. The OpenTelemetry Specification recommends a default of 2000. +// - A too-high limit increases worst-case memory overhead in the SDK and may cause downstream +// issues for databases that cannot handle high cardinality. // - Too low - causes loss of attribute detail as more data falls into overflow. // // See [go.opentelemetry.io/otel/metric] for more information about From f518a72a2d485a4513c6cd9c9e717339859f61c4 Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Mon, 18 Aug 2025 09:47:46 +0200 Subject: [PATCH 08/14] Update sdk/metric/doc.go Co-authored-by: Tyler Yahn --- sdk/metric/doc.go | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sdk/metric/doc.go b/sdk/metric/doc.go index 41be733c518..dfbb1651db4 100644 --- a/sdk/metric/doc.go +++ b/sdk/metric/doc.go @@ -41,8 +41,7 @@ // // # Cardinality Limits // -// Cardinality refers to the number of unique attribute combinations for a single -// metric within one collection (export) interval. High cardinality can lead to +// Cardinality refers to the number of unique attributes collected. High cardinality can lead to // excessive memory usage, increased storage costs, and backend performance issues. // // Currently, the OpenTelemetry Go Metric SDK does not enforce a cardinality limit by default From 943f266655f0dd56e2536bd5bcf323540bb28a57 Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Mon, 18 Aug 2025 09:47:53 +0200 Subject: [PATCH 09/14] Update sdk/metric/doc.go Co-authored-by: Tyler Yahn --- sdk/metric/doc.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/metric/doc.go b/sdk/metric/doc.go index dfbb1651db4..aac9092010f 100644 --- a/sdk/metric/doc.go +++ b/sdk/metric/doc.go @@ -52,7 +52,7 @@ // these sets are aggregated into // a special attribute set containing `{"otel.metric.overflow": true}`. // This ensures total metric values (e.g., Sum, Count) remain correct for the -// collection interval, but information about the specific dropped combinations +// collection interval, but information about the specific dropped sets // is not preserved. // // Recommendations: From bc4b776349ea77912fa5b1d1ae9149b814860327 Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Mon, 18 Aug 2025 09:55:30 +0200 Subject: [PATCH 10/14] Update sdk/metric/doc.go MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- sdk/metric/doc.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/metric/doc.go b/sdk/metric/doc.go index aac9092010f..ae2c55ce0c0 100644 --- a/sdk/metric/doc.go +++ b/sdk/metric/doc.go @@ -50,7 +50,7 @@ // // New attribute sets are dropped when the cardinality limit is reached. The measurement of // these sets are aggregated into -// a special attribute set containing `{"otel.metric.overflow": true}`. +// a special attribute set containing "otel.metric.overflow" attribute with "true" value. // This ensures total metric values (e.g., Sum, Count) remain correct for the // collection interval, but information about the specific dropped sets // is not preserved. From 7dc091b3fbfcd1c158808db6f5521494f3e73b80 Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Mon, 18 Aug 2025 09:58:03 +0200 Subject: [PATCH 11/14] Update sdk/metric/doc.go MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- sdk/metric/doc.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/metric/doc.go b/sdk/metric/doc.go index ae2c55ce0c0..b3a49eb493a 100644 --- a/sdk/metric/doc.go +++ b/sdk/metric/doc.go @@ -59,7 +59,7 @@ // // - Set the limit based on the theoretical maximum combinations or expected // active combinations. The OpenTelemetry Specification recommends a default of 2000. -// - A too-high limit increases worst-case memory overhead in the SDK and may cause downstream +// - A too high limit increases worst-case memory overhead in the SDK and may cause downstream // issues for databases that cannot handle high cardinality. // - Too low - causes loss of attribute detail as more data falls into overflow. // From 980bc36cf54cc36fa7e578710c3d2f91dee35ece Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Mon, 18 Aug 2025 09:58:08 +0200 Subject: [PATCH 12/14] Update sdk/metric/doc.go MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- sdk/metric/doc.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/metric/doc.go b/sdk/metric/doc.go index b3a49eb493a..ce8de54cbc5 100644 --- a/sdk/metric/doc.go +++ b/sdk/metric/doc.go @@ -61,7 +61,7 @@ // active combinations. The OpenTelemetry Specification recommends a default of 2000. // - A too high limit increases worst-case memory overhead in the SDK and may cause downstream // issues for databases that cannot handle high cardinality. -// - Too low - causes loss of attribute detail as more data falls into overflow. +// - A too low limit causes loss of attribute detail as more data falls into overflow. // // See [go.opentelemetry.io/otel/metric] for more information about // the metric API. From 11b6130ef0d9dcc594a090a3ee4d9b19c4bda0c5 Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Mon, 18 Aug 2025 11:35:41 +0200 Subject: [PATCH 13/14] Update sdk/metric/doc.go MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- sdk/metric/doc.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/metric/doc.go b/sdk/metric/doc.go index ce8de54cbc5..864d19a761d 100644 --- a/sdk/metric/doc.go +++ b/sdk/metric/doc.go @@ -52,7 +52,7 @@ // these sets are aggregated into // a special attribute set containing "otel.metric.overflow" attribute with "true" value. // This ensures total metric values (e.g., Sum, Count) remain correct for the -// collection interval, but information about the specific dropped sets +// collection cycle, but information about the specific dropped sets // is not preserved. // // Recommendations: From e6b03a4eb4a511bb092b66bcbc65cfe94720adf2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 25 Aug 2025 15:53:12 +0200 Subject: [PATCH 14/14] Apply suggestions from code review Co-authored-by: Tyler Yahn --- sdk/metric/doc.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/metric/doc.go b/sdk/metric/doc.go index 864d19a761d..5f8cfd58d50 100644 --- a/sdk/metric/doc.go +++ b/sdk/metric/doc.go @@ -59,9 +59,9 @@ // // - Set the limit based on the theoretical maximum combinations or expected // active combinations. The OpenTelemetry Specification recommends a default of 2000. -// - A too high limit increases worst-case memory overhead in the SDK and may cause downstream +// - A too high of a limit increases worst-case memory overhead in the SDK and may cause downstream // issues for databases that cannot handle high cardinality. -// - A too low limit causes loss of attribute detail as more data falls into overflow. +// - A too low of a limit causes loss of attribute detail as more data falls into overflow. // // See [go.opentelemetry.io/otel/metric] for more information about // the metric API.