diff --git a/specification/sdk-span-processors.md b/specification/sdk-span-processors.md new file mode 100644 index 00000000000..dfa25c7f244 --- /dev/null +++ b/specification/sdk-span-processors.md @@ -0,0 +1,80 @@ +# Span processor + +Span processor is an interface which allows hooks for span start and end method invocations. +The span processors are invoked only when [`IsRecordingEvents`](api-tracing.md#isrecordingevents) is true. This interface can be used to implement [span exporter](sdk-exporter.md) to batch and convert spans. + +Span processors can be registered directly on SDK Tracer and they are invoked in the same order as they were registered. + +The following diagram shows `SpanProcessor`'s relationship to other components in the SDK: + +``` + +-----+---------------+ +---------------------+ +-------------------+ + | | | | | | | + | | | | BatchProcessor | | SpanExporter | + | | +---> SimpleProcessor +---> (JaegerExporter) | + | SDK | SpanProcessor | | | | | + | | | +---------------------+ +-------------------+ + | | | + | | | +---------------------+ + | | | | | + | | +---> ZPagesProcessor | + | | | | | + +-----+---------------+ +---------------------+ +``` + +## Interface definition + +### OnStart(Span) + +`OnStart` is called when a span is started. +This method is called synchronously on the thread that started the span, therefore it should not block or throw exceptions. + +**Parameters:** + +* `Span` - a readable span object. + +**Returns:** `Void` + +### OnEnd(Span) + +`OnEnd` is called when a span is ended. +This method is called synchronously on the execution thread, therefore it should not block or throw an exception. + +**Parameters:** + +* `Span` - a readable span object. + +**Returns:** `Void` + +### Shutdown() + +Shuts down the processor. Called when SDK is shut down. This is an opportunity for processor to do any cleanup required. + +Shutdown should be called only once for each `Processor` instance. After the call to shutdown subsequent calls to `onStart` or `onEnd` are not allowed. + +Shutdown should not block indefinitely. Language library authors can decide if they want to make the shutdown timeout to be configurable. + +## Built-in span processors + +### Simple processor + +The implementation of `SpanProcessor` that passes ended span directly to the configured `SpanExporter`. + +**Configurable parameters:** + +* `exporter` - the exporter where the spans are pushed. + +### Batching processor + +The implementation of the `SpanProcessor` that batches ended spans and pushes them to the configured `SpanExporter`. + +First the spans are added to a synchronized queue, then exported to the exporter pipeline in batches. +The implementation is responsible for managing the span queue and sending batches of spans to the exporters. +This processor can cause high contention in a very high traffic service. + +**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`. +* `scheduledDelayMillis` - the delay interval in milliseconds between two consecutive exports. The default value is `5000`. +* `maxExportBatchSize` - the maximum batch size of every export. It must be smaller or equal to `maxQueueSize`. The default value is `512`.