Merge branch 'main' of github.com:open-telemetry/opentelemetry-specif…

…ication into jmacd/sampling_new

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))
 - Define randomness value requirements for W3C Trace Context Level 2.
   ([#4162](https://github.com/open-telemetry/opentelemetry-specification/pull/4162))
 
@@ -28,6 +30,9 @@ release.
 
 ### Logs
 
+- The SDK MAY provide an operation that makes a deep clone of a `ReadWriteLogRecord`.
+  ([#4090](https://github.com/open-telemetry/opentelemetry-specification/pull/4090))
+
 ### Events
 
 ### Resource

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/logs/event-sdk.md

@@ -87,7 +87,7 @@ to [emit a logRecord](./bridge-api.md#emit-a-logrecord) as follows:
   the `event.name` [Attribute](./data-model.md#field-attributes). If
   the `Attributes` provided by the user contain an `event.name` attribute the
   value provided in the `Name` takes precedence.
-* If provided by the user, the `Payload` MUST be used to set
+* If provided by the user, the `Body` MUST be used to set
   the [Body](./data-model.md#field-body). If not provided, `Body` MUST not be
   set.
 * If provided by the user, the `Timestamp` MUST be used to set

specification/logs/sdk.md

@@ -235,6 +235,12 @@ the following information added to the [LogRecord](data-model.md#log-and-event-r
 * [`SpanId`](./data-model.md#field-spanid)
 * [`TraceFlags`](./data-model.md#field-traceflags)
 
+The SDK MAY provide an operation that makes a deep clone of a `ReadWriteLogRecord`.
+The operation can be used to implement the [isolating processor](#isolating-processor)
+or by asynchronous processors (e.g. [Batching processor](#batching-processor))
+to avoid race conditions on the log record that is not required to be
+concurrent safe.
+
 ## LogRecord Limits
 
 `LogRecord` attributes MUST adhere to

specification/trace/sdk.md

@@ -46,6 +46,7 @@ linkTitle: SDK
 - [Span processor](#span-processor)
   * [Interface definition](#interface-definition)
     + [OnStart](#onstart)
+    + [OnEnding](#onending)
     + [OnEnd(Span)](#onendspan)
     + [Shutdown()](#shutdown)
     + [ForceFlush()](#forceflush)
@@ -625,11 +626,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:**
 
@@ -644,6 +657,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).