Skip to content

Commit

Permalink
Add requirements for how the Trace API should behave in the absence o…
Browse files Browse the repository at this point in the history
…f an SDK (open-telemetry#719)

* Add requirements for how the Trace API should behave in the absence of an SDK.

* update from feedback

* Add clarifying language to what makes a span "invalid"

* Update specification/trace/api.md

Co-authored-by: Christian Neumüller <[email protected]>

* slightly tweak the language around non-valid spans.

* add a CHANGELOG entry

Co-authored-by: Christian Neumüller <[email protected]>
  • Loading branch information
jkwatson and Oberon00 authored Aug 18, 2020
1 parent fa79464 commit 3ae9003
Show file tree
Hide file tree
Showing 2 changed files with 19 additions and 2 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ the release.
New:

- Add resource semantic conventions for operating systems ([#693](https://github.com/open-telemetry/opentelemetry-specification/pull/693))
- Clarification of the behavior of the Trace API, re: context propagation, in the absence of an installed SDK
- Add Span API and semantic conventions for recording exceptions
([#697](https://github.com/open-telemetry/opentelemetry-specification/pull/697))

Expand Down
20 changes: 18 additions & 2 deletions specification/trace/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -468,8 +468,8 @@ The Span interface MUST provide:
Updates the `Span` name. Upon this update, any sampling behavior based on `Span`
name will depend on the implementation.

Note that [Samplers](sdk.md#sampler) can only consider information already
present during span creation. Any changes done later, including updated span
Note that [Samplers](sdk.md#sampler) can only consider information already
present during span creation. Any changes done later, including updated span
name, cannot change their decisions.

Alternatives for the name update may be late `Span` creation, when Span is
Expand Down Expand Up @@ -692,3 +692,19 @@ implementer of these links.
The API layer MAY include the following `Propagator`s:

* A `HTTPTextPropagator` implementing the [W3C TraceContext Specification](https://www.w3.org/TR/trace-context/).

## Behavior of the API in the absence of an installed SDK

In general, in the absence of an installed SDK, the Trace API is a "no-op" API.
This means that operations on a Tracer, or on Spans, should have no side effects and do nothing. However, there
is one important exception to this general rule, and that is related to propagation of a SpanContext.

The following cases must be considered when a new Span is requested to be created, especially in relation to the
requested parent SpanContext:

* A valid `SpanContext` is specified as the parent of the new `Span`: The API MUST treat this parent context as the
context for the newly created `Span`. This means that a `SpanContext` that has been provided by a configured `Propagator`
will be propagated through to any child span, but that no new `SpanContext`s will be created.
* No valid `SpanContext` is specified as the parent of the new `Span`: The API MUST create an non-valid
(both SpanID and TradeID are equivalent to being all zeros) `Span` for use
by the API caller. This means that both the `TraceID` and the `SpanID` should be invalid.

0 comments on commit 3ae9003

Please sign in to comment.