diff --git a/.chloggen/clarify-sdk-processor-processed-boundary.yaml b/.chloggen/clarify-sdk-processor-processed-boundary.yaml new file mode 100644 index 0000000000..a215d050a7 --- /dev/null +++ b/.chloggen/clarify-sdk-processor-processed-boundary.yaml @@ -0,0 +1,11 @@ +change_type: enhancement + +component: otel + +note: > + Clarify when SDK processors record successful processing and distinguish it + from queue acceptance and exporter completion. + +issues: [1921] + +subtext: diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index 68779b0802..53614a7d13 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -265,7 +265,11 @@ This metric is [recommended][MetricRecommended]. **[1]:** For successful processing, `error.type` MUST NOT be set. For failed processing, `error.type` MUST contain the failure cause. SDK Batching Span Processors MUST use `queue_full` as the value of `error.type` for spans dropped due to a full queue. SDK Span Processors MUST use `already_shutdown` as the value of `error.type` for spans dropped because the processor has already been shut down. -For the SDK Simple and Batching Span Processor a span is considered to be processed already when it has been submitted to the exporter, not when the corresponding export call has finished. +For the SDK Simple and Batching Span Processors, successful processing finishes when the processor invokes the export operation. +For batching processors, all spans in the invoked batch are considered processed at this point; spans that were accepted and remain +queued have not yet been processed. Implementations MUST record successful processing when the export operation is invoked, regardless +of whether the invocation returns normally or throws, and MUST NOT delay recording until the export operation completes. The outcome +of the export operation MUST NOT affect this metric. **Attributes:** @@ -705,8 +709,11 @@ This metric is [recommended][MetricRecommended]. **[1]:** For successful processing, `error.type` MUST NOT be set. For failed processing, `error.type` MUST contain the failure cause. SDK Batching Log Record Processors MUST use `queue_full` as the value of `error.type` for log records dropped due to a full queue. SDK Log Record Processors MUST use `already_shutdown` as the value of `error.type` for log records dropped because the processor has already been shut down. -For the SDK Simple and Batching Log Record Processor a log record is considered to be processed already when it has been submitted to the exporter, -not when the corresponding export call has finished. +For the SDK Simple and Batching Log Record Processors, successful processing finishes when the processor invokes the export operation. +For batching processors, all log records in the invoked batch are considered processed at this point; log records that were accepted +and remain queued have not yet been processed. Implementations MUST record successful processing when the export operation is invoked, +regardless of whether the invocation returns normally or throws, and MUST NOT delay recording until the export operation completes. +The outcome of the export operation MUST NOT affect this metric. **Attributes:** diff --git a/model/otel/metrics.yaml b/model/otel/metrics.yaml index 07ab94fb43..2ec762dfac 100644 --- a/model/otel/metrics.yaml +++ b/model/otel/metrics.yaml @@ -74,7 +74,11 @@ groups: For successful processing, `error.type` MUST NOT be set. For failed processing, `error.type` MUST contain the failure cause. SDK Batching Span Processors MUST use `queue_full` as the value of `error.type` for spans dropped due to a full queue. SDK Span Processors MUST use `already_shutdown` as the value of `error.type` for spans dropped because the processor has already been shut down. - For the SDK Simple and Batching Span Processor a span is considered to be processed already when it has been submitted to the exporter, not when the corresponding export call has finished. + For the SDK Simple and Batching Span Processors, successful processing finishes when the processor invokes the export operation. + For batching processors, all spans in the invoked batch are considered processed at this point; spans that were accepted and remain + queued have not yet been processed. Implementations MUST record successful processing when the export operation is invoked, regardless + of whether the invocation returns normally or throws, and MUST NOT delay recording until the export operation completes. The outcome + of the export operation MUST NOT affect this metric. instrument: counter unit: "{span}" attributes: @@ -191,8 +195,11 @@ groups: For successful processing, `error.type` MUST NOT be set. For failed processing, `error.type` MUST contain the failure cause. SDK Batching Log Record Processors MUST use `queue_full` as the value of `error.type` for log records dropped due to a full queue. SDK Log Record Processors MUST use `already_shutdown` as the value of `error.type` for log records dropped because the processor has already been shut down. - For the SDK Simple and Batching Log Record Processor a log record is considered to be processed already when it has been submitted to the exporter, - not when the corresponding export call has finished. + For the SDK Simple and Batching Log Record Processors, successful processing finishes when the processor invokes the export operation. + For batching processors, all log records in the invoked batch are considered processed at this point; log records that were accepted + and remain queued have not yet been processed. Implementations MUST record successful processing when the export operation is invoked, + regardless of whether the invocation returns normally or throws, and MUST NOT delay recording until the export operation completes. + The outcome of the export operation MUST NOT affect this metric. instrument: counter unit: "{log_record}" attributes: