README.md

Extending the OpenTelemetry .NET SDK

• Building your own exporter
• Building your own reader
• Building your own exemplar filter
• Building your own exemplar reservoir
• References

Exporter

OpenTelemetry .NET SDK has provided the following built-in metric exporters:

• InMemory
• Console
• OpenTelemetryProtocol
• Prometheus HttpListener
• Prometheus AspNetCore

Custom exporters can be implemented to send telemetry data to places which are not covered by the built-in exporters:

• Exporters should derive from OpenTelemetry.BaseExporter<Metric> (which belongs to the OpenTelemetry package) and implement the Export method.
• Exporters can optionally implement the OnShutdown method.
• Exporters should not throw exceptions from Export and OnShutdown.
• Exporters are responsible for any retry logic needed by the scenario. The SDK does not implement any retry logic.
• Exporters should avoid generating telemetry and causing live-loop, this can be done via OpenTelemetry.SuppressInstrumentationScope.
• Exporters receives a batch of Metric, and each Metric can contain 1 or more MetricPoints. The exporter should perform all actions (e.g. serializing etc.) with the Metrics and MetricsPoints in the batch before returning control from Export, once the control is returned, the exporter can no longer make any assumptions about the state of the batch or anything inside it.
• Exporters should use ParentProvider.GetResource() to get the Resource associated with the provider.

class MyExporter : BaseExporter<Metric>
{
    public override ExportResult Export(in Batch<Metric> batch)
    {
        using var scope = SuppressInstrumentationScope.Begin();

        foreach (var metric in batch)
        {
            Console.WriteLine($"Export: {metric.metric}");

            foreach (ref readonly var metricPoint in metric.GetMetricPoints())
            {
                Console.WriteLine($"Export: {metricPoint.StartTime}");
            }
        }

        return ExportResult.Success;
    }
}

A demo exporter which simply writes metric name, metric point start time and tags to the console is shown here.

Apart from the exporter itself, you should also provide extension methods as shown here. This allows users to add the Exporter to the MeterProvider as shown in the example here.

Reader

Not supported.

ExemplarFilter

OpenTelemetry .NET SDK has provided the following built-in ExemplarFilters:

• AlwaysOnExemplarFilter
• AlwaysOffExemplarFilter
• TraceBasedExemplarFilter

Custom exemplar filters can be implemented to achieve filtering based on other criterion:

• ExemplarFilter should derive from OpenTelemetry.ExemplarFilter (which belongs to the OpenTelemetry 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.

public sealed class HighValueFilter : ExemplarFilter
{
    private readonly double maxValue;

    public HighValueFilter(double maxValue)
    {
        this.maxValue = maxValue;
    }
    public override bool ShouldSample(long value, ReadOnlySpan<KeyValuePair<string, object>> tags)
    {
        return Activity.Current?.Recorded && value > this.maxValue;
    }

    public override bool ShouldSample(double value, ReadOnlySpan<KeyValuePair<string, object>> tags)
    {
        return Activity.Current?.Recorded && value > this.maxValue;
    }
}

ExemplarReservoir

Not supported.

References