Skip to content

Commit

Permalink
Trace API: Update mentions of SpanContext as parent. (open-telemetry#…
Browse files Browse the repository at this point in the history
…1023)

* Trace API: Update mentions of SpanContext as parent.

* Incorporate changes regarding Propagated Span

Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com>

* Rewrite "Behavior of the API in absence of SDK"

* Update specification/trace/api.md

Co-authored-by: John Watson <jkwatson@gmail.com>

* Apply suggestions from code review

Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com>

* Improve grammar.

Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com>
Co-authored-by: John Watson <jkwatson@gmail.com>
  • Loading branch information
3 people authored Oct 2, 2020
1 parent f8c9cbd commit f901ad2
Showing 1 changed file with 10 additions and 11 deletions.
21 changes: 10 additions & 11 deletions specification/trace/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -732,14 +732,13 @@ The API layer MAY include the following `Propagator`s:

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.
is one important exception to this general rule, and that is related to propagation of a `SpanContext`:
The API MUST create a [Propagated Span](#propagated-span-creation) with the `SpanContext`
that is in the `Span` in the parent `Context` (whether explicitly given or implicit current) or,
if the parent is a Propagated Span (which it usually always is if no SDK is present),
it MAY return the same parent Propagated Span instance back from the creation method.
If the parent `Context` contains no `Span`, an empty Propagated Span MUST be returned instead
(i.e., having a SpanContext with all-zero Span and Trace IDs, empty Tracestate, and unsampled TraceFlags).
This means that a `SpanContext` that has been provided by a configured `Propagator`
will be propagated through to any child span and ultimately also `Inject`,
but that no new `SpanContext`s will be created.

0 comments on commit f901ad2

Please sign in to comment.