docs: update exporter guide (#3256)

Co-authored-by: Valentin Marchaud <[email protected]>

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