Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify SDK ReadableSpan's parent Context (fix accidentally requiring full parent chain) #3257

Merged
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
3 changes: 3 additions & 0 deletions specification/trace/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
17 changes: 13 additions & 4 deletions specification/trace/sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,21 +120,30 @@ 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).

Counts for attributes, events and links dropped due to collection limits MUST be
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,
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved
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
Expand Down