diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 6a315d11b6f..1b46ae1b958 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -287,17 +287,17 @@ invocations. The span processors are invoked only when [`IsRecording`](api.md#isrecording) is true. Built-in span processors are responsible for batching and conversion of spans to -exportable representation and passing batches to exporters. +exportable representation and passing batches to exporters or alternatives to +exporters such as [z-pages](../../experimental/trace/zpages.md). Span processors can be registered directly on SDK `TracerProvider` and they are invoked in the same order as they were registered. -Each processor registered on `TracerProvider` is a start of pipeline that consist -of span processor and optional exporter. SDK MUST allow to end each pipeline with -individual exporter. +Each processor registered on `TracerProvider` is a start of a pipeline that consists +of one or more span processors and, optionally, one or more exporters. The SDK MUST +allow ending each pipeline with an individual exporter. -SDK MUST allow users to implement and configure custom processors and decorate -built-in processors for advanced scenarios such as tagging or filtering. +The SDK MUST allow users to implement and configure custom processors. The following diagram shows `SpanProcessor`'s relationship to other components in the SDK: @@ -391,13 +391,19 @@ make the flush timeout configurable. The standard OpenTelemetry SDK MUST implement both simple and batch processors, as described below. Other common processing scenarios should be first considered -for implementation out-of-process in [OpenTelemetry Collector](../overview.md#collector) +for implementation out-of-process in an [OpenTelemetry Collector](../overview.md#collector). #### Simple processor This is an implementation of `SpanProcessor` which passes finished spans -and passes the export-friendly span data representation to the configured -`SpanExporter`, as soon as they are finished. +and the export-friendly span data representation to the configured +`SpanExporter` as soon as they are finished. + +The simple processor must not be used lightly in production. It runs on application thread and may +degrade performance. It may be appropriate for production use in scenarios where creating +multiple threads is not desirable (since batching span processors will typically be threaded +in order to pass spans on to exporters in the background) as well as scenarios where different +custom attributes should be added to individual spans based on code scopes. **Configurable parameters:** @@ -405,21 +411,23 @@ and passes the export-friendly span data representation to the configured #### Batching processor -This is an implementation of the `SpanProcessor` which create batches of finished -spans and passes the export-friendly span data representations to the -configured `SpanExporter`. +This is an implementation of `SpanProcessor` which collects finished spans into batches +and passes the export-friendly span data representations to the associated `SpanExporter`. + +Typically, the batching processor will be more suitable for production environments +than the simple processor. **Configurable parameters:** * `exporter` - the exporter where the spans are pushed. -* `maxQueueSize` - the maximum queue size. After the size is reached spans are - dropped. The default value is `2048`. +* `maxQueueSize` - the maximum queue size. After this limit is reached, spans are + skipped by this BatchSpanProcessor. The default value is `2048`. * `scheduledDelayMillis` - the delay interval in milliseconds between two consecutive exports. The default value is `5000`. * `exportTimeoutMillis` - how long the export can run before it is cancelled. The default value is `30000`. * `maxExportBatchSize` - the maximum batch size of every export. It must be - smaller or equal to `maxQueueSize`. The default value is `512`. + smaller than or equal to `maxQueueSize`. The default value is `512`. ## Span Exporter