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

jkwatson · 2020-07-20T22:13:44Z

Clarifies the behavior of the Trace API, in the absence of an installed SDK, especially with respect to context propagation.

Fixes #689

Changes

Adds requirements for Trace API behavior in the absence of an SDK.

specification/trace/api.md

cijothomas · 2020-07-20T22:24:05Z

specification/trace/api.md

+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


Bit confused here.. This section is talking about the scenario when there is no Sdk installed. In that scenario, should we still take and propagate the context? Is this propagation limited to in-proc spans only or out-of-proc as well?

So, yes, that's the point of this PR. :) Since you can install a Propagator without an SDK installed, it became important to explain how that would work. If a propagator (let's say, the W3C Trace Context propagator) is installed, this specifies that that API should still propagate incoming spans, transparently.

It's the "minimum" requirement from the W3C spec for forwarding a trace: https://www.w3.org/TR/trace-context/#design-overview

It's the "minimum" requirement from the W3C spec for forwarding a trace

If you have no API and no SDK you are not a participant in the trace and thus not accountable to minimum behaviors.

But, if you have propagators attached to the API, shouldn't you be?

dyladan · 2020-07-20T23:41:33Z

This is not possible to implement in javascript without moving a ton of in-process context propagation logic into the API. Why is it that one use-case gets special treatment of being enabled by default?

jkwatson · 2020-07-20T23:42:59Z

@dyladan can you comment in the originating issue, please? #689

I thought this had been fairly well agreed to by all who had participated there.

dyladan · 2020-07-20T23:47:59Z

@dyladan can you comment in the originating issue, please? #689

I thought this had been fairly well agreed to by all who had participated there.

I don't see that agreement. Can you point to a specific comment? I also looked through the associated #428 and saw only no-op there in the absence of the SDK.

jkwatson · 2020-07-21T00:00:35Z

@dyladan can you comment in the originating issue, please? #689
I thought this had been fairly well agreed to by all who had participated there.

I don't see that agreement. Can you point to a specific comment? I also looked through the associated #428 and saw only no-op there in the absence of the SDK.

Well, that entire issue is about the behavior of the API with no SDK, so yes, it seems like general agreement was come to, and I agreed to own writing up the results of the discussion.

specification/trace/api.md

carlosalberto · 2020-07-21T13:52:53Z

specification/trace/api.md

+
+In general, in the absence of an installed SDK, the Trace API is intended to 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.


This part will probably change, based on #721

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?

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.

carlosalberto · 2020-07-21T13:54:26Z

Thanks for the effort - I'm wondering if this should also be added to Metrics/CorrelationContext parts as well.

bogdandrutu · 2020-08-10T16:49:11Z

@jkwatson please rebase and either remove draft or close this PR, we provided enough "initial" feedback :)

jkwatson · 2020-08-10T18:49:51Z

I'll update this and get it ready for official review/merging.

bogdandrutu · 2020-08-12T19:35:50Z

Rebase again :)

…f an SDK.

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

jkwatson · 2020-08-12T20:43:40Z

Rebase again :)

done :)

bogdandrutu · 2020-08-13T01:17:31Z

I think there is an issue with GitHub status checks

tedsuo · 2020-08-17T19:06:30Z

This looks ready to go. Can we merge?

bogdandrutu · 2020-08-17T23:57:22Z

@carlosalberto as assigned member please merge or comment :)

bogdandrutu · 2020-08-18T21:54:54Z

Merging this since it is non controversial. @jkwatson we should have similar content for all the APIs

…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]>

cijothomas reviewed Jul 20, 2020

View reviewed changes

specification/trace/api.md Outdated Show resolved Hide resolved

cijothomas reviewed Jul 20, 2020

View reviewed changes

specification/trace/api.md Outdated Show resolved Hide resolved

cijothomas reviewed Jul 20, 2020

View reviewed changes

bogdandrutu added area:api Cross language API specification issue spec:trace Related to the specification/trace directory labels Jul 21, 2020

bogdandrutu approved these changes Jul 21, 2020

View reviewed changes

anuraaga approved these changes Jul 21, 2020

View reviewed changes

Oberon00 reviewed Jul 21, 2020

View reviewed changes

specification/trace/api.md Outdated Show resolved Hide resolved

specification/trace/api.md Outdated Show resolved Hide resolved

carlosalberto reviewed Jul 21, 2020

View reviewed changes

specification/trace/api.md Outdated Show resolved Hide resolved

carlosalberto reviewed Jul 21, 2020

View reviewed changes

jkwatson mentioned this pull request Jul 21, 2020

Design document on the API / SDK split and guidelines for what to put where #723

Closed

Oberon00 mentioned this pull request Jul 31, 2020

Current "Invalid" SpanContext definition precludes TraceState-only SpanContext #753

Open

jkwatson force-pushed the trace-api-only-behavior branch from 7c9a178 to 11981c9 Compare August 10, 2020 20:52

jkwatson marked this pull request as ready for review August 10, 2020 20:53

jkwatson requested review from a team August 10, 2020 20:53

Oberon00 approved these changes Aug 11, 2020

View reviewed changes

bogdandrutu assigned carlosalberto Aug 12, 2020

jwatson and others added 4 commits August 12, 2020 13:40

Add requirements for how the Trace API should behave in the absence o…

9176f83

…f an SDK.

update from feedback

08a59b5

Add clarifying language to what makes a span "invalid"

6599bcc

Update specification/trace/api.md

d4bfdb1

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

jwatson added 2 commits August 12, 2020 13:40

slightly tweak the language around non-valid spans.

1e82e91

add a CHANGELOG entry

3287d34

jkwatson force-pushed the trace-api-only-behavior branch from 11981c9 to 3287d34 Compare August 12, 2020 20:41

jkwatson requested review from a team and yurishkuro August 12, 2020 20:41

bogdandrutu closed this Aug 13, 2020

bogdandrutu reopened this Aug 13, 2020

arminru approved these changes Aug 13, 2020

View reviewed changes

cijothomas approved these changes Aug 17, 2020

View reviewed changes

bogdandrutu merged commit 3ae9003 into open-telemetry:master Aug 18, 2020

jkwatson mentioned this pull request Aug 18, 2020

Add clarification on the no-op nature of the metric API. #829

Merged

jtescher mentioned this pull request Aug 19, 2020

Switch to noop propagators as default global propagator open-telemetry/opentelemetry-rust#181

Closed

dyladan mentioned this pull request Aug 21, 2020

It should be possible to propagate context with only the API open-telemetry/opentelemetry-js#1456

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

jkwatson commented Jul 20, 2020 •

edited

Loading

cijothomas Jul 20, 2020

jkwatson Jul 20, 2020

dyladan Jul 20, 2020

jkwatson Jul 20, 2020

dyladan commented Jul 20, 2020

jkwatson commented Jul 20, 2020

dyladan commented Jul 20, 2020

jkwatson commented Jul 21, 2020

carlosalberto Jul 21, 2020

Oberon00 Jul 22, 2020

jkwatson Aug 10, 2020

carlosalberto commented Jul 21, 2020

bogdandrutu commented Aug 10, 2020

jkwatson commented Aug 10, 2020

bogdandrutu commented Aug 12, 2020

jkwatson commented Aug 12, 2020

bogdandrutu commented Aug 13, 2020

tedsuo commented Aug 17, 2020

bogdandrutu commented Aug 17, 2020

bogdandrutu commented Aug 18, 2020

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

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

Conversation

jkwatson commented Jul 20, 2020 • edited Loading

Changes

cijothomas Jul 20, 2020

Choose a reason for hiding this comment

jkwatson Jul 20, 2020

Choose a reason for hiding this comment

dyladan Jul 20, 2020

Choose a reason for hiding this comment

jkwatson Jul 20, 2020

Choose a reason for hiding this comment

dyladan commented Jul 20, 2020

jkwatson commented Jul 20, 2020

dyladan commented Jul 20, 2020

jkwatson commented Jul 21, 2020

carlosalberto Jul 21, 2020

Choose a reason for hiding this comment

Oberon00 Jul 22, 2020

Choose a reason for hiding this comment

jkwatson Aug 10, 2020

Choose a reason for hiding this comment

carlosalberto commented Jul 21, 2020

bogdandrutu commented Aug 10, 2020

jkwatson commented Aug 10, 2020

bogdandrutu commented Aug 12, 2020

jkwatson commented Aug 12, 2020

bogdandrutu commented Aug 13, 2020

tedsuo commented Aug 17, 2020

bogdandrutu commented Aug 17, 2020

bogdandrutu commented Aug 18, 2020

jkwatson commented Jul 20, 2020 •

edited

Loading