diff --git a/doc/web-api.md b/doc/contributing/web-api.md similarity index 100% rename from doc/web-api.md rename to doc/contributing/web-api.md diff --git a/doc/exporter-guide.md b/doc/exporter-guide.md index 46dfe0d221..adeb090b43 100644 --- a/doc/exporter-guide.md +++ b/doc/exporter-guide.md @@ -12,13 +12,15 @@ opentelemetry-exporter-myexporter │ └── index.ts │ └── transform.ts │ └── types.ts - │ └── myexporter.ts + │ └── my-trace-exporter.ts + │ └── my-metric-exporter.ts └── test └── transform.test.ts - └── myexporter.test.ts + └── my-trace-exporter.test.ts + └── my-metric-exporter.test.ts ``` -## Tracing +## 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: @@ -29,7 +31,7 @@ The `SpanExporter` interface defines which methods the protocol-specific trace/s 5. Do not modify received spans. 6. Do not implement queuing or batching logic because this is handled by Span Processors. -The current `SpanExporter` interface (`0.2.0`) contains 2 methods: +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. @@ -39,16 +41,48 @@ Please refer to the [Zipkin Exporter][zipkin-exporter] or [Jaeger Exporter][jaeg ## Metrics -The `MetricExporter` defines the interface that protocol-specific exporters must implement so that they can be plugged into OpenTelemetry SDK and support sending of metrics data. +Metrics can be exported with two distinct patterns: -The current `MetricExporter` interface (`0.2.0`) defines 2 methods: +- Push model exporting, like periodically push metrics to the backend. +- Pull model exporting, like Prometheus pulling metrics from the application. -- `export`: Exports a batch of telemetry data. In this method you’ll process and translate `MetricRecord` Data into the data that your metric backend accepts. +### Push model exporting -- `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. +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][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][prometheus-exporter] for more comprehensive examples. [zipkin-exporter]: https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-exporter-zipkin [jaeger-exporter]: https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-exporter-jaeger +[otlp-exporter]: https://github.com/open-telemetry/opentelemetry-js/blob/main/experimental/packages/opentelemetry-exporter-metrics-otlp-grpc [prometheus-exporter]: https://github.com/open-telemetry/opentelemetry-js/blob/main/experimental/packages/opentelemetry-exporter-prometheus