diff --git a/docs/metrics/customizing-the-sdk/README.md b/docs/metrics/customizing-the-sdk/README.md index b671d7c70..5608ee516 100644 --- a/docs/metrics/customizing-the-sdk/README.md +++ b/docs/metrics/customizing-the-sdk/README.md @@ -447,6 +447,15 @@ using var meterProvider = Sdk.CreateMeterProviderBuilder() > As of today, there is no separate toggle for enable/disable Exemplar feature. It can be turned off by using `AlwaysOffExemplarFilter`. +If the built-in `ExemplarFilter`s are not meeting the needs, one may author +custom `ExemplarFilter` as shown +[here](../extending-the-sdk/README.md#exemplarfilter). A custom filter, which +eliminates all un-interesting measurements from becoming Exemplar is a +recommended way to control performance overhead associated with collecting +Exemplars. See +[benchmark](../../../test/Benchmarks/Metrics/ExemplarBenchmarks.cs) to see how +much impact can `ExemplarFilter` have on performance. + #### ExemplarReservoir `ExemplarReservoir` receives the measurements sampled in by the `ExemplarFilter` diff --git a/docs/metrics/extending-the-sdk/README.md b/docs/metrics/extending-the-sdk/README.md index 0777c8f8f..4c409961d 100644 --- a/docs/metrics/extending-the-sdk/README.md +++ b/docs/metrics/extending-the-sdk/README.md @@ -2,7 +2,8 @@ * [Building your own exporter](#exporter) * [Building your own reader](#reader) -* [Building your own exemplar](#exemplar) +* [Building your own exemplar filter](#exemplarfilter) +* [Building your own exemplar reservoir](#exemplarreservoir) * [References](#references) ## Exporter @@ -70,7 +71,48 @@ to the `MeterProvider` as shown in the example [here](./Program.cs). Not supported. -## Exemplar +## ExemplarFilter + +OpenTelemetry .NET SDK has provided the following built-in `ExemplarFilter`s: + +* [AlwaysOnExemplarFilter](../../../src/OpenTelemetry/Metrics/Exemplar/AlwaysOnExemplarFilter.cs) +* [AlwaysOffExemplarFilter](../../../src/OpenTelemetry/Metrics/Exemplar/AlwaysOffExemplarFilter.cs) +* [TraceBasedExemplarFilter](../../../src/OpenTelemetry/Metrics/Exemplar/TraceBasedExemplarFilter.cs) + +Custom exemplar filters can be implemented to achieve filtering based on other criterion: + +* `ExemplarFilter` should derive from `OpenTelemetry.ExemplarFilter` (which + belongs to the [OpenTelemetry](../../../src/OpenTelemetry/README.md) package) + and implement the `ShouldSample` method. + +One example is a filter, which filters all measurements of value lower +than given threshold is given below. Such a filter prevents any measurements +below the given threshold from ever becoming a `Exemplar`. Such filters could +also incorporate the `TraceBasedExemplarFilter` condition as well, as storing +exemplars for non-sampled traces may be undesired. + +```csharp +public sealed class HighValueFilter : ExemplarFilter +{ + private readonly double maxValue; + + public HighValueFilter(double maxValue) + { + this.maxValue = maxValue; + } + public override bool ShouldSample(long value, ReadOnlySpan> tags) + { + return Activity.Current?.Recorded && value > this.maxValue; + } + + public override bool ShouldSample(double value, ReadOnlySpan> tags) + { + return Activity.Current?.Recorded && value > this.maxValue; + } +} +``` + +## ExemplarReservoir Not supported.