diff --git a/CHANGELOG.md b/CHANGELOG.md index ae4d3d93dd6..d245b19650c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,10 @@ release. ### Traces +* Clarify required parent information in ReadableSpan. Technically a relaxation, + but previously it was easy to overlook certain properties were required. + [#3257](https://github.com/open-telemetry/opentelemetry-specification/pull/3257) + ### Metrics - Clarify that units should use UCUM case sensitive variant. diff --git a/specification/trace/api.md b/specification/trace/api.md index d27cbacc9f7..59a4b390a97 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -224,6 +224,9 @@ specification](https://www.w3.org/TR/trace-context/#tracestate-header). For specific OTel values in `TraceState`, see the [TraceState Handling](tracestate-handling.md) document. +`IsRemote`, a boolean indicating whether the SpanContext was received from somewhere +else or locally generated, see [IsRemote](#isremote). + The API MUST implement methods to create a `SpanContext`. These methods SHOULD be the only way to create a `SpanContext`. This functionality MUST be fully implemented in the API, and SHOULD NOT be overridable. diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 2e5b0dd46dc..ec69c39b8fd 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -120,14 +120,19 @@ Thus, the SDK specification defines sets of possible requirements for * **Readable span**: A function receiving this as argument MUST be able to access all information that was added to the span, as listed - [in the API spec](api.md#span). In particular, it MUST also be - able to access the `InstrumentationScope` [since 1.10.0] and `Resource` - information (implicitly) associated with the span. For backwards compatibility + in the API spec for [Span](api.md#span). Note: Below, a few particular properties + are called out for clarity, but for the complete list of required properties, + the [Span API spec](api.md#span) is authoritative. + + A function receiving this as argument MUST be able to access + the `InstrumentationScope` [since 1.10.0] and `Resource` information + (implicitly) associated with the span. For backwards compatibility it MUST also be able to access the `InstrumentationLibrary` [deprecated since 1.10.0] having the same name and version values as the `InstrumentationScope`. - It must also be able to reliably determine whether the Span has ended + A function receiving this as argument MUST must be able to reliably determine + whether the Span has ended (some languages might implement this by having an end timestamp of `null`, others might have an explicit `hasEnded` boolean). @@ -135,6 +140,10 @@ Thus, the SDK specification defines sets of possible requirements for available for exporters to report as described in the [exporters](../common/mapping-to-non-otlp.md#dropped-attributes-count) specification. + As an exception to the authoritative set of span properties defined in the API spec, + implementations MAY choose not to expose (and store) the full parent [Context](../context/README.md) + of the Span but they MUST expose at least the full parent [SpanContext](api.md#spancontext). + A function receiving this as argument might not be able to modify the Span. Note: Typically this will be implemented with a new interface or