[language-agnostic-wg] first attempt at a language neutral explanation of the Tracer API #354

tsloughter · 2019-11-14T15:30:10Z

Getting the ball rolling. This is only a reworking of the initial Tracer definition and I think it still needs some work.

The "user definitions" shouldn't go in this document but I threw them in at the bottom just to get them somewhere for now.

I will be working on the "Tracer operations" section next and, assuming this PR isn't quickly finished up and merged (which I doubt), I'll be adding that commit to this PR.

specification/api-tracing.md

bogdandrutu · 2019-11-14T19:21:57Z

Please also resolve the conflicts :)

specification/api-tracing.md

specification/glossary.md

specification/api-tracing.md

specification/glossary.md

specification/api-tracing.md

specification/glossary.md

specification/api-tracing.md

MrAlias · 2020-02-05T21:02:03Z

specification/api-tracing.md

-way of the `Tracer`.
+A `Tracer` is the code responsible for starting `Spans`s and it exposes the API
+which [library developers][] use when instrumenting their code. The API MUST
+allow the [application developers][] to configure or specify the implementation


These last two sentences seem out of place. I interpret them as describing the overall project design rather than descriptions of the Tracer. Have I missed your intent?

Looking at another PR I noticed a similar idea in an introduction: https://github.com/open-telemetry/opentelemetry-specification/pull/430/files#diff-9c6d57b34defe784fc21653cedacae6dR56-R58

I'm guessing this was the intent here, right?

MrAlias · 2020-02-05T21:31:54Z

specification/api-tracing.md

-exposes methods for creating and activating new `Span`s. The `Tracer` is
-configured with `Propagator`s which support transferring span context across
-process boundaries.
+A `Tracer` is more than just the code though. Each `Tracer` has a name and 


This first sentence doesn't seem to add to the idea this paragraph is about. Instead it seems to add conflict with the first sentence of the previous paragraph.

Suggested change

A `Tracer` is more than just the code though. Each `Tracer` has a name and

Each `Tracer` has a name and

MrAlias · 2020-02-05T21:33:39Z

specification/api-tracing.md

-configured with `Propagator`s which support transferring span context across
-process boundaries.
+A `Tracer` is more than just the code though. Each `Tracer` has a name and 
+optionally a version. The API must provide [library developers][] a way to


should this be normative?

Suggested change

optionally a version. The API must provide [library developers][] a way to

optionally a version. The API MUST provide [library developers][] a way to

MrAlias · 2020-02-05T21:34:10Z

specification/api-tracing.md

-exposes methods for creating and activating new `Span`s. The `Tracer` is
-configured with `Propagator`s which support transferring span context across
-process boundaries.
+A `Tracer` is more than just the code though. Each `Tracer` has a name and 


It might be useful to say:

A Tracer is identified by a name and optionally a version.

This would help convey the significance of the name/version pair.

Also, is the version optional? I thought based on OTEP 16 this was a needed part of the tracer identity.

The otep says it is optional:

The version (following the convention proposed in open-telemetry/oteps#38) is basically optional but should be supplied

Gotcha, thanks for the ref 😄

specification/api-tracing.md

specification/glossary.md

MrAlias · 2020-02-05T22:43:27Z

specification/glossary.md

+  responsible for code that becomes a deployable artifact to run with some
+  configuration by an operator. The application developer's project may depend
+  on third party libraries that have been instrumented and may include its own
+  libraries, making the application developer potentially a library developer as


Should we replace "libraries" with "OpenTelemetry instrumentation"? I think we are trying to say that by performing their own instrumentation they become library developers as well, not that by including their own libraries makes them library developers.

Suggested change

libraries, making the application developer potentially a library developer as

OpenTelemetry instrumentation, making the application developer potentially a library developer as

No, I don't think that was the intent here. It is definitely a confusing sentence now and maybe should just be removed.

MrAlias · 2020-02-05T23:04:46Z

specification/glossary.md

+  on third party libraries that have been instrumented and may include its own
+  libraries, making the application developer potentially a library developer as
+  well. But only the end user, or operator, should include an OpenTelemetry SDK
+  implementation as a dependency and configure, either through code or


This sentence seems out of place for a user glossary definition for an application developer. It seems prescriptive of the operation of OpenTelemetry instrumented software rather than defining a user category.

Does it belong somewhere in the specification or maybe a Roles section?

I could see all of this instead moved to a roles section of the spec and removing the glossary. I dont't think these roles being in a glossary can say much if they don't describe these points, so if a Roles section is to be done instead I'd say it should all be moved.

specification/glossary.md

Co-Authored-By: Tyler Yahn <MrAlias@users.noreply.github.com>

tsloughter · 2020-02-08T16:46:33Z

Closing this and it is being replaced with #449, #451 and #452 for now.

As discussed in this PR and on gitter the current glossary makes more sense as a roles section somewhere in the specification. So that is still a PR that needs to be made.

tsloughter requested review from AloisReitbauer, bogdandrutu, c24t, carlosalberto, iredelmeier, reyang, SergeyKanzhelev, songy23, tedsuo, tigrannajaryan and yurishkuro as code owners November 14, 2019 15:30

tsloughter force-pushed the lang-agnostic-1 branch from 30f836e to bddea67 Compare November 14, 2019 16:12

bogdandrutu reviewed Nov 14, 2019

View reviewed changes

tsloughter force-pushed the lang-agnostic-1 branch from bddea67 to 6358cf3 Compare November 14, 2019 16:20

tsloughter force-pushed the lang-agnostic-1 branch 3 times, most recently from 868de24 to 05b0626 Compare November 14, 2019 22:18

tsloughter mentioned this pull request Nov 14, 2019

Tracer spec globals review #353

Merged

tsloughter force-pushed the lang-agnostic-1 branch from 05b0626 to d2544de Compare November 14, 2019 22:23

Oberon00 reviewed Nov 18, 2019

View reviewed changes

jmacd mentioned this pull request Nov 25, 2019

Consider a new name for Metrics Meter interface #365

Closed

Oberon00 mentioned this pull request Nov 26, 2019

Named tracers open-telemetry/opentelemetry-python#301

Merged

arminru requested changes Nov 27, 2019

View reviewed changes

Oberon00 requested changes Nov 27, 2019

View reviewed changes

specification/api-tracing.md Outdated Show resolved Hide resolved

arminru mentioned this pull request Nov 27, 2019

Rename Tracer/MeterFactory to Tracer/MeterRegistry open-telemetry/opentelemetry-java#664

Closed

dyladan mentioned this pull request Dec 3, 2019

Named Tracers / Tracer Registry open-telemetry/opentelemetry-js#582

Merged

tsloughter force-pushed the lang-agnostic-1 branch 3 times, most recently from 08efc33 to eb0ac73 Compare January 3, 2020 15:42

tsloughter added 20 commits February 5, 2020 09:29

first attempt at a language neutral explanation of the Tracer API

79f45e6

add separate glossary file

a763ef9

remove "span ending" from what the Tracer is responsible for

3f475fb

explain need for passing name/version at tracer retrieval time

9b208db

add user definitions for api and sdk developer

d891d8f

use markdown shortcut for common link target

b1c3e16

add note about operator role

be6bf16

replace 'end user' with 'application developer'

5a9977e

cleanup based on PR reviews

347f847

remove required/optional from name for named tracer

8b92bb5

add TracerProvider to Tracer section of api-tracing

8ff3174

change method to function

b7cd992

merge of updates from Yuri and Daniel

c3339a9

remove mention of tracer being used for context and propagation

5c6707f

reorder glossary

1bfbb2b

remove mention of Factory

313c3dd

remove confusing sentences about not how tracers are named

da41503

remove operator restriction from glossary

fa2873c

fix table of contents

82e6078

remove mention of Resource from named tracers

06a3e1a

tsloughter force-pushed the lang-agnostic-1 branch from 0ef4cbc to 06a3e1a Compare February 5, 2020 16:34

MrAlias reviewed Feb 5, 2020

View reviewed changes

tsloughter and others added 5 commits February 7, 2020 11:56

Update specification/api-tracing.md

6d32d43

Co-Authored-By: Tyler Yahn <MrAlias@users.noreply.github.com>

Update specification/glossary.md

7e8fa47

Co-Authored-By: Tyler Yahn <MrAlias@users.noreply.github.com>

Update specification/glossary.md

d4d1214

Co-Authored-By: Tyler Yahn <MrAlias@users.noreply.github.com>

Update specification/glossary.md

2a4b7ef

Co-Authored-By: Tyler Yahn <MrAlias@users.noreply.github.com>

Update specification/api-tracing.md

efd8003

Co-Authored-By: Tyler Yahn <MrAlias@users.noreply.github.com>

tsloughter closed this Feb 8, 2020

TuckTuckFloof pushed a commit to TuckTuckFloof/opentelemetry-specification that referenced this pull request Oct 15, 2020

cmake build with gcc4.8 (open-telemetry#354)

c33a195

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[language-agnostic-wg] first attempt at a language neutral explanation of the Tracer API #354

[language-agnostic-wg] first attempt at a language neutral explanation of the Tracer API #354

tsloughter commented Nov 14, 2019

bogdandrutu commented Nov 14, 2019

MrAlias Feb 5, 2020

MrAlias Feb 7, 2020

MrAlias Feb 5, 2020

MrAlias Feb 5, 2020

MrAlias Feb 5, 2020

tsloughter Feb 7, 2020

MrAlias Feb 7, 2020

MrAlias Feb 5, 2020

tsloughter Feb 7, 2020

MrAlias Feb 5, 2020

tsloughter Feb 7, 2020

tsloughter commented Feb 8, 2020

	A `Tracer` is more than just the code though. Each `Tracer` has a name and
	Each `Tracer` has a name and

	optionally a version. The API must provide [library developers][] a way to
	optionally a version. The API MUST provide [library developers][] a way to

	libraries, making the application developer potentially a library developer as
	OpenTelemetry instrumentation, making the application developer potentially a library developer as

[language-agnostic-wg] first attempt at a language neutral explanation of the Tracer API #354

[language-agnostic-wg] first attempt at a language neutral explanation of the Tracer API #354

Conversation

tsloughter commented Nov 14, 2019

bogdandrutu commented Nov 14, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tsloughter commented Feb 8, 2020