|
2 | 2 |
|
3 | 3 | * [Building your own exporter](#exporter) |
4 | 4 | * [Building your own reader](#reader) |
5 | | -* [Building your own exemplar filter](#exemplarfilter) |
6 | 5 | * [Building your own exemplar reservoir](#exemplarreservoir) |
7 | 6 | * [Building your own resource detector](../../resources/README.md#resource-detector) |
8 | 7 | * [References](#references) |
@@ -72,12 +71,103 @@ to the `MeterProvider` as shown in the example [here](./Program.cs). |
72 | 71 |
|
73 | 72 | Not supported. |
74 | 73 |
|
75 | | -## ExemplarFilter |
| 74 | +## ExemplarReservoir |
76 | 75 |
|
77 | | -Not supported. |
| 76 | +> [!NOTE] |
| 77 | +> `ExemplarReservoir` is an experimental API only available in pre-release |
| 78 | + builds. For details see: |
| 79 | + [OTEL1004](../../diagnostics/experimental-apis/OTEL1004.md). Please [provide |
| 80 | + feedback](https://github.com/open-telemetry/opentelemetry-dotnet/issues/5629) |
| 81 | + to help inform decisions about what should be exposed stable and when. |
78 | 82 |
|
79 | | -## ExemplarReservoir |
| 83 | +Custom [ExemplarReservoir](../customizing-the-sdk/README.md#exemplarreservoir)s |
| 84 | +can be implemented to control how `Exemplar`s are recorded for a metric: |
80 | 85 |
|
81 | | -Not supported. |
| 86 | +* `ExemplarReservoir`s should derive from `FixedSizeExemplarReservoir` (which |
| 87 | + belongs to the [OpenTelemetry](../../../src/OpenTelemetry/README.md) package) |
| 88 | + and implement the `Offer` methods. |
| 89 | +* The `FixedSizeExemplarReservoir` constructor accepts a `capacity` parameter to |
| 90 | + control the number of `Exemplar`s which may be recorded by the |
| 91 | + `ExemplarReservoir`. |
| 92 | +* The `virtual` `OnCollected` method is called after the `ExemplarReservoir` |
| 93 | + collection operation has completed and may be used to implement cleanup or |
| 94 | + reset logic. |
| 95 | +* The `bool` `ResetOnCollect` property on `ExemplarReservoir` is set to `true` |
| 96 | + when delta aggregation temporality is used for the metric using the |
| 97 | + `ExemplarReservoir`. |
| 98 | +* The `Offer` and `Collect` `ExemplarReservoir` methods are called concurrently |
| 99 | + by the OpenTelemetry SDK. As such any state required by custom |
| 100 | + `ExemplarReservoir` implementations needs to be managed using appropriate |
| 101 | + thread-safety/concurrency mechanisms (`lock`, `Interlocked`, etc.). |
| 102 | +* Custom `ExemplarReservoir` implementations MUST NOT throw exceptions. |
| 103 | + Exceptions thrown in custom implementations MAY lead to unreleased locks and |
| 104 | + undefined behaviors. |
| 105 | + |
| 106 | +The following example demonstrates a custom `ExemplarReservoir` implementation |
| 107 | +which records `Exemplar`s for measurements which have the highest value. When |
| 108 | +delta aggregation temporality is used the recorded `Exemplar` will be the |
| 109 | +highest value for a given collection cycle. When cumulative aggregation |
| 110 | +temporality is used the recorded `Exemplar` will be the highest value for the |
| 111 | +lifetime of the process. |
| 112 | + |
| 113 | +```csharp |
| 114 | +class HighestValueExemplarReservoir : FixedSizeExemplarReservoir |
| 115 | +{ |
| 116 | + private readonly object lockObject = new(); |
| 117 | + private long? previousValueLong; |
| 118 | + private double? previousValueDouble; |
| 119 | + |
| 120 | + public HighestValueExemplarReservoir() |
| 121 | + : base(capacity: 1) |
| 122 | + { |
| 123 | + } |
| 124 | + |
| 125 | + public override void Offer(in ExemplarMeasurement<long> measurement) |
| 126 | + { |
| 127 | + if (!this.previousValueLong.HasValue || measurement.Value > this.previousValueLong.Value) |
| 128 | + { |
| 129 | + lock (this.lockObject) |
| 130 | + { |
| 131 | + if (!this.previousValueLong.HasValue || measurement.Value > this.previousValueLong.Value) |
| 132 | + { |
| 133 | + this.UpdateExemplar(0, in measurement); |
| 134 | + this.previousValueLong = measurement.Value; |
| 135 | + } |
| 136 | + } |
| 137 | + } |
| 138 | + } |
| 139 | + |
| 140 | + public override void Offer(in ExemplarMeasurement<double> measurement) |
| 141 | + { |
| 142 | + if (!this.previousValueDouble.HasValue || measurement.Value > this.previousValueDouble.Value) |
| 143 | + { |
| 144 | + lock (this.lockObject) |
| 145 | + { |
| 146 | + if (!this.previousValueDouble.HasValue || measurement.Value > this.previousValueDouble.Value) |
| 147 | + { |
| 148 | + this.UpdateExemplar(0, in measurement); |
| 149 | + this.previousValueDouble = measurement.Value; |
| 150 | + } |
| 151 | + } |
| 152 | + } |
| 153 | + } |
| 154 | + |
| 155 | + protected override void OnCollected() |
| 156 | + { |
| 157 | + if (this.ResetOnCollect) |
| 158 | + { |
| 159 | + lock (this.lockObject) |
| 160 | + { |
| 161 | + this.previousValueLong = null; |
| 162 | + this.previousValueDouble = null; |
| 163 | + } |
| 164 | + } |
| 165 | + } |
| 166 | +} |
| 167 | +``` |
| 168 | + |
| 169 | +Custom [ExemplarReservoir](../customizing-the-sdk/README.md#exemplarreservoir)s |
| 170 | +can be configured using the View API. For details see: [Change the |
| 171 | +ExemplarReservoir](../customizing-the-sdk/README.md#change-the-exemplarreservoir). |
82 | 172 |
|
83 | 173 | ## References |
0 commit comments