diff --git a/CHANGELOG.md b/CHANGELOG.md index 2729c9f5120..2e71b526382 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ release. - Remove restriction that sampler description is immutable. ([#4137](https://github.com/open-telemetry/opentelemetry-specification/pull/4137)) +- Add in-development `OnEnding` callback to SDK `SpanProcessor` interface. + ([#4024](https://github.com/open-telemetry/opentelemetry-specification/pull/4024)) ### Metrics diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index b0d9f5c07ef..374e1e2b340 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -55,6 +55,7 @@ formats is required. Implementing more than one format is optional. | events collection size limit | | + | + | + | + | + | + | + | + | - | - | + | | attribute collection size limit | | + | + | + | + | + | + | + | + | - | - | + | | links collection size limit | | + | + | + | + | + | + | + | + | - | - | + | +| [SpanProcessor.OnEnding](specification/trace/sdk.md#onending) | X | - | - | - | - | - | - | - | - | - | - | - | | [Span attributes](specification/trace/api.md#set-attributes) | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | | SetAttribute | | + | + | + | + | + | + | + | + | + | + | + | | Set order preserved | X | + | - | + | + | + | + | + | + | + | + | + | diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 622a1e1452b..82bec706359 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -38,6 +38,7 @@ linkTitle: SDK - [Span processor](#span-processor) * [Interface definition](#interface-definition) + [OnStart](#onstart) + + [OnEnding](#onending) + [OnEnd(Span)](#onendspan) + [Shutdown()](#shutdown) + [ForceFlush()](#forceflush) @@ -571,11 +572,23 @@ in the SDK: ### Interface definition +The `SpanProcessor` interface MUST declare the following methods: + +* [OnStart](#onstart) +* [OnEnd](#onendspan) +* [Shutdown](#shutdown-1) +* [ForceFlush](#forceflush-1) + +The `SpanProcessor` interface SHOULD declare the following methods: + +* [OnEnding](#onending) method. + #### OnStart `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. +exceptions. If multiple `SpanProcessors` are registered, their `OnStart` callbacks +are invoked in the order they have been registered. **Parameters:** @@ -590,6 +603,25 @@ exceptions. **Returns:** `Void` +#### OnEnding + +**Status**: [Development](../document-status.md) + +`OnEnding` is called during the span `End()` operation, after the end timestamp has been set. The Span object is still mutable (i.e., `SetAttribute`, `AddLink`, `AddEvent` can be called) while `OnEnding` is called. +This method MUST be called synchronously within the [`Span.End()` API](api.md#end), +therefore it should not block or throw an exception. +If multiple `SpanProcessors` are registered, their `OnEnding` callbacks +are invoked in the order they have been registered. +The SDK MUST guarantee that the span can no longer be modified by any other thread +before invoking `OnEnding` of the first `SpanProcessor`. From that point on, modifications +are only allowed synchronously from within the invoked `OnEnding` callbacks. All registered SpanProcessor `OnEnding` callbacks are executed before any SpanProcessor's `OnEnd` callback is invoked. + +**Parameters:** + +* `span` - a [read/write span object](#additional-span-interfaces) for the span which is about to be ended. + +**Returns:** `Void` + #### OnEnd(Span) `OnEnd` is called after a span is ended (i.e., the end timestamp is already set).