diff --git a/CHANGELOG.md b/CHANGELOG.md index 8240bfb827e..1635dbc2514 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)) - 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 diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 42e39dafffe..fc67f7de207 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/logs/event-sdk.md b/specification/logs/event-sdk.md index 5a4769fd33c..1a9bc0ee829 100644 --- a/specification/logs/event-sdk.md +++ b/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 diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index be06ddc56b6..eadd5a597d2 100644 --- a/specification/logs/sdk.md +++ b/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 diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 991b09b28e1..071a9317972 100644 --- a/specification/trace/sdk.md +++ b/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).