sdk/metric: Add Documentation for Cardinality Limits (#7179)

Fixes #6979
Towards #6887

## What

- Documentation includes a section on cardinality limits.
- Adding guidance around what cardinality is, why it is important to
consider, how to control it, and what defaults the SDK provides

---------

Co-authored-by: Robert Pająk <[email protected]>
Co-authored-by: Tyler Yahn <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -44,7 +44,7 @@ The next release will require at least [Go 1.24].
   - `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.

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 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
+// (note that this may change in a future release). Use [WithCardinalityLimit] to set the
+// cardinality limit as desired.
+//
+// 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" attribute with "true" value.
+// This ensures total metric values (e.g., Sum, Count) remain correct for the
+// collection cycle, but information about the specific dropped sets
+// is not preserved.
+//
+// Recommendations:
+//
+//   - Set the limit based on the theoretical maximum combinations or expected
+//     active combinations. The OpenTelemetry Specification recommends a default of 2000.
+//   - 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 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.
 //