5.2 KiB

Raw Permalink Blame History

Exporter Developer Guide

An exporter sends traces and metrics to any backend that is capable of consuming them. With OpenTelemetry, you can easily add and remove any exporter without requiring changes to your application code.

We provide support for several open source backends and vendors out-of-the-box like Zipkin, Jaeger, and Prometheus, but OpenTelemetry exporters follow a public interface which can be implemented by anyone. This document describes the process for developers to create their own exporter if the provided ones do not meet their needs.

A typical package layout:

opentelemetry-exporter-myexporter
   ├── src
   │   └── index.ts
   │   └── transform.ts
   │   └── types.ts
   │   └── my-trace-exporter.ts
   │   └── my-metric-exporter.ts
   └── test
       └── transform.test.ts
       └── my-trace-exporter.test.ts
       └── my-metric-exporter.test.ts

Traces

The SpanExporter interface defines which methods the protocol-specific trace/span exporters must implement so that they can be plugged into OpenTelemetry SDK. Span exporters must follow these rules:

Implement the SpanExporter interface.
Expect to only receive spans which have been sampled.
Expect to only receive spans which are ended.
Do not throw exceptions.
Do not modify received spans.
Do not implement queuing or batching logic because this is handled by Span Processors.

The current SpanExporter interface contains 2 methods:

export: Exports a batch of spans. In this method, you’ll process and translate ReadableSpan Data into the data that your trace backend accepts, and send them to your tracing backend.
shutdown: Shuts down the exporter. This is an opportunity for exporter to do any cleanup required. Shutdown should be called only once for each Exporter instance. After the call to Shutdown subsequent calls to Export are not allowed and should return FailedNotRetryable error.

Please refer to the Zipkin Exporter or Jaeger Exporter for more comprehensive examples.

Metrics

Metrics can be exported with two distinct patterns:

Push model exporting, like periodically push metrics to the backend.
Pull model exporting, like Prometheus pulling metrics from the application.

Push model exporting

The PushMetricExporter defines the interface that protocol-specific exporters must implement so that they can be plugged into OpenTelemetry SDK and support sending of metrics data with PeriodicMetricReader.

The current PushMetricExporter interface defines 3 required methods:

export: Exports a batch of telemetry data. In this method you’ll process and translate ResourceMetrics into the data that your metric backend accepts.
shutdown: Shuts down the exporter. This is an opportunity for exporter to do any cleanup required. Shutdown should be called only once for each Exporter instance.
forceFlush: Ensure that the export of any metrics the exporter has received is completed before the returned promise is settled.

The PushMetricExporter interface can also implement following methods to provide a preference on metric configuration:

selectAggregationTemporality: Select the preferred AggregationTemporality for the given InstrumentType for this exporter.
selectAggregation: Select the preferred Aggregation for the given InstrumentType for this exporter.

Please refer to the OTLP Exporter for more comprehensive examples.

Pull model exporting

The pulling model exporting requires the export pipeline proactively initiate metric collections. Such exporting pipeline must be modeled as a MetricReader.

The abstract class MetricReader defines the interface that protocol-specific readers must implement so that they can be plugged into OpenTelemetry SDK and support pulling of metrics data.

The current MetricReader interface defines 2 required methods:

onShutdown: Shuts down the reader. This is an opportunity for reader to do any cleanup required. Shutdown should be called only once for each reader instance.
onForceFlush: Ensure that the export of any metrics the reader has received is completed before the returned promise is settled.

A MetricReader can initiate a metric collection request with MetricReader.collect() method. The MetricReader.collect() returns a promise that settles with a CollectionResult, containing the ResourceMetrics record and a series of reasons for possibly failed asynchronous metric instrument collection. The ResourceMetrics record can be processed and translated into the data that your metric backend accepts.

Please refer to the Prometheus Exporter for more comprehensive examples.

5.2 KiB Raw Permalink Blame History Unescape Escape