Clarify otel.sdk.processor.span.processed and otel.sdk.processor.log.processed semantics for records a processor does not forward

Closed
CI
2mo ago
+31-10

The otel.sdk.processor.span.processed and otel.sdk.processor.log.processed metrics do not clearly define what "processed" means for a record a processor handles but does not forward to an exporter, for example RECORD_ONLY (recording, non-sampled) spans in the built-in Simple and Batching Span Processors.

This clarifies that a record is counted as successfully processed when the processor completes its intended handling of it (even if it is not forwarded to an exporter), and error.type is set only when the processor cannot complete that handling (for example queue_full or already_shutdown). processed is therefore an outcome metric and does not measure how many records reach an exporter, which is reported by otel.sdk.exporter.{span,log}.exported.

Measuring throughput or dataflow through a processor (how many records enter versus leave it) is intentionally out of scope, and could be a future dedicated pair of metrics, similar to the OpenTelemetry Collector's per-processor incoming/outgoing item counters. Alternatives such as adding that dataflow metric now, or adding an attribute to processed to separate forwarded from non-forwarded records, are considerably more disruptive: they expand the metric surface, require coordinated cross-language implementation, and take longer to settle. This clarification changes no metric shape and adds no attribute, so it is the least-disruptive way to remove the ambiguity and should let these long-standing metrics land as stable relatively soon.

If merged, most built-in span processor implementations will need small updates to conform. From a quick audit of Go, Python, and Java, the only one that already matches this clarification is Go's Simple Span Processor; the batch processors in all three, and Python's and Java's simple processors, currently drop non-forwarded RECORD_ONLY spans without counting them as processed.