Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[metrics] Document view level cardinality limit #5321

Merged
merged 9 commits into from
Feb 7, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 2 additions & 7 deletions docs/metrics/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`SetMaxMetricPointsPerMetricStream` method, or at individual
`SetCardinalityLimit` 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)
Copy link
Contributor

@Yun-Ting Yun-Ting Feb 7, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section can be updated to be: "../../docs/metrics/customizing-the-sdk/README.md#changing-the-cardinalityLimit", given the name standardization effort: https://github.com/open-telemetry/opentelemetry-dotnet/pull/5328/files.

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
Expand Down
14 changes: 10 additions & 4 deletions docs/metrics/customizing-the-sdk/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
3 changes: 3 additions & 0 deletions docs/metrics/getting-started-console/Program.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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"));
Expand Down
22 changes: 18 additions & 4 deletions docs/metrics/getting-started-console/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand Down
Loading