Add ability for SpanProcessor to mutate spans on end (#4024)

Fixes #1089.

In addition to the comments on the issue, this was discussed in the spec
SIG Meeting on 2024/23/04:
* The filtering use-case explained in [this
comment](#1089 (comment))
should rather be solved by the upcoming samplerV2 instead of
`SpanProcessor`s due to better conceptual fit
* The buffering use-case also explained in [this
comment](#1089 (comment))
seems to be not relevant enough to influence the design decision
* Apparently there was a discussion around building the `SpanProcessor`s
in a chaining fashion during the initial SDK spec design and it was
actively decided against it. However, no one could recall the reason
why.

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
 

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        | +   | -    | +   | +      | +    | +      | +   | +    | +   | +    | +     |

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).