diff --git a/docs/metrics/README.md b/docs/metrics/README.md index ea3cb4459e4..412a824ea11 100644 --- a/docs/metrics/README.md +++ b/docs/metrics/README.md @@ -356,18 +356,13 @@ predictable and reliable behavior when excessive cardinality happens, whether it was due to a malicious attack or developer making mistakes while writing code. OpenTelemetry has a default cardinality limit of `2000` per metric. This limit -can be configured at `MeterProvider` level using +can be configured at `MeterProvider` level using the `SetMaxMetricPointsPerMetricStream` method, or at individual [view](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#view) -level. Refer to this +level using `MetricStreamConfiguration.CardinalityLimit`. Refer to this [doc](../../docs/metrics/customizing-the-sdk/README.md#changing-maximum-metricpoints-per-metricstream) for more information. -> [!NOTE] -> Setting cardinality limit per view is not yet implemented in OpenTelemetry - .NET. You can track the progress by following this - [issue](https://github.com/open-telemetry/opentelemetry-dotnet/issues/5296). - Given a metric, once the cardinality limit is reached, any new measurement which cannot be independently aggregated because of the limit will be aggregated using the [overflow diff --git a/docs/metrics/customizing-the-sdk/README.md b/docs/metrics/customizing-the-sdk/README.md index 20a9350e508..d7cf59961a9 100644 --- a/docs/metrics/customizing-the-sdk/README.md +++ b/docs/metrics/customizing-the-sdk/README.md @@ -444,10 +444,16 @@ AnotherFruitCounter.Add(5, new("name", "banana"), new("color", "yellow")); // Ex AnotherFruitCounter.Add(4, new("name", "mango"), new("color", "yellow")); // Not exported ``` -> [!NOTE] -> The above limit is *per* metric stream, and applies to all the metric -streams. There is no ability to apply different limits for each instrument at -this moment. +To set the [cardinality limit](../README.md#cardinality-limits) at individual +metric level, use `MetricStreamConfiguration.CardinalityLimit`: + +```csharp +var meterProvider = Sdk.CreateMeterProviderBuilder() + .AddMeter("MyCompany.MyProduct.MyLibrary") + .AddView(instrumentName: "MyFruitCounter", new MetricStreamConfiguration { CardinalityLimit = 10 }) + .AddConsoleExporter() + .Build(); +``` ### Exemplars diff --git a/docs/metrics/getting-started-console/Program.cs b/docs/metrics/getting-started-console/Program.cs index 524ee88ad1a..89425c6d41c 100644 --- a/docs/metrics/getting-started-console/Program.cs +++ b/docs/metrics/getting-started-console/Program.cs @@ -17,6 +17,9 @@ public static void Main() .AddConsoleExporter() .Build(); + // In this example, we have low cardinality which is below the 2000 + // default limit. If you have high cardinality, you need to set the + // cardinality limit properly. MyFruitCounter.Add(1, new("name", "apple"), new("color", "red")); MyFruitCounter.Add(2, new("name", "lemon"), new("color", "yellow")); MyFruitCounter.Add(1, new("name", "lemon"), new("color", "yellow")); diff --git a/docs/metrics/getting-started-console/README.md b/docs/metrics/getting-started-console/README.md index 661c396d615..3f30652b313 100644 --- a/docs/metrics/getting-started-console/README.md +++ b/docs/metrics/getting-started-console/README.md @@ -69,10 +69,10 @@ MyFruitCounter.Add(2, new("name", "lemon"), new("color", "yellow")); MyFruitCounter.Add(1, new("name", "lemon"), new("color", "yellow")); ``` -An OpenTelemetry -[MeterProvider](#meterprovider) -is configured to subscribe to instruments from the Meter -`MyCompany.MyProduct.MyLibrary`, and aggregate the measurements in-memory. The +An OpenTelemetry [MeterProvider](#meterprovider) is configured to subscribe to +an instrument named "MyFruitCounter" from the Meter +`MyCompany.MyProduct.MyLibrary`, and aggregate the measurements in-memory with a +default [cardinality limit](../README.md#cardinality-limits) of `2000`. The pre-aggregated metrics are exported to a `ConsoleExporter`. ```csharp @@ -82,6 +82,20 @@ var meterProvider = Sdk.CreateMeterProviderBuilder() .Build(); ``` +> [!NOTE] +> If you need to collect metrics with cardinality higher than the default limit + `2000`, please follow the [cardinality + limits](../README.md#cardinality-limits) guidance. Here is a quick example of + how to change the cardinality limit to `10` for this particular metric: + + ```csharp + var meterProvider = Sdk.CreateMeterProviderBuilder() + .AddMeter("MyCompany.MyProduct.MyLibrary") + .AddView(instrumentName: "MyFruitCounter", new MetricStreamConfiguration { CardinalityLimit = 10 }) + .AddConsoleExporter() + .Build(); + ``` + ```mermaid graph LR