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.

Sign up for GitHub

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

Add requirements for how the Trace API should behave in the absence of an SDK #719

Merged
merged 6 commits into from
Aug 18, 2020
Merged

Add requirements for how the Trace API should behave in the absence of an SDK #719

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9176f83
Add requirements for how the Trace API should behave in the absence o…
Jul 20, 2020
08a59b5
update from feedback
Jul 20, 2020
6599bcc
Add clarifying language to what makes a span "invalid"
Jul 21, 2020
d4bfdb1
Update specification/trace/api.md
jkwatson Jul 30, 2020
1e82e91
slightly tweak the language around non-valid spans.
Aug 10, 2020
3287d34
add a CHANGELOG entry
Aug 10, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
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
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -476,8 +476,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 @@ -700,3 +700,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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This part will probably change, based on #721

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You should be able to install a W3C propagator into the propagation layer (which is supposed to be an artifact separate from API) even without initializing the SDK, right? So I don't think this part changes?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree. I don't think this changes. IF there is a propagator installed in the propagation APIs, THEN, this requires the API to propagate any valid spans that are specified as parent spans, even if no real child-span is created.


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.