Skip to content

Commit e8946b4

Browse files
c24tbogdandrutu
c24t
authored and
bogdandrutu
committed
Generalize span operations (open-telemetry#209)
* s/content/contents/ * Fix typo * Remove impl-specific details, shuffle text * Shuffle section on multi-deployment runtime * Less flowery language * Backtick fixes * Apply @songy23's suggestions from PR Co-Authored-By: Yang Song <songy23@users.noreply.github.com> * Reword tracer config description * Note that SpanProcessor does more than export * s/set/make/ * Lose refs to exporters, processors * Separate span lifetime and activation
1 parent f889ede commit e8946b4

File tree

3 files changed

+61
-96
lines changed

3 files changed

+61
-96
lines changed

‎specification/api-metrics.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
<details>
44
<summary>
5-
Table of Content
5+
Table of Contents
66
</summary>
77

88
- [Meter](#meter)

‎specification/api-propagators.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
<details>
44
<summary>
5-
Table of Content
5+
Table of Contents
66
</summary>
77

88
- [Binary Format](#binary-format)

‎specification/api-tracing.md

+59-94
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
<details>
44
<summary>
5-
Table of Content
5+
Table of Contents
66
</summary>
77

88
* [Data types](#data-types)
@@ -82,110 +82,84 @@ A duration is the elapsed time between two events.
8282

8383
## Tracer
8484

85-
### Obtaining a tracer
86-
87-
A tracer SHOULD be obtained from a global registry, for example
88-
`OpenTelemetry.getTracer()`.
89-
90-
The registration to the registry depends on the language. In some languages the
91-
tracer is explicitly created and registered from user code and other languages
92-
the tracer implementation is resolved from linked dependencies using provider
93-
pattern.
94-
95-
The tracer object construction depends on the implementation. Various
96-
implementations might require to specify different configuration properties at
97-
creation time. In languages where provider pattern is used the configuration is
98-
provided externally.
99-
100-
#### Tracer provider
101-
102-
Tracer provider is an internal class used by the global registry
103-
(`OpenTelemetry`) to get a tracer instance. The global registry delegates calls
104-
to the provider every time a tracer instance is requested. This is necessary
105-
for use-cases when a single instrumentation code runs for multiple deployments.
106-
107-
The tracer provider is registered to API usually via language-specific
108-
mechanism, for instance `ServiceLoader` in Java.
109-
110-
##### Runtime with multiple deployments/applications
111-
112-
Application runtimes which support multiple deployments/applications might need
113-
to provide a different tracer instance to each deployment. In this case the
114-
runtime provides its own implementation of provider which returns a different
115-
tracer for each deployment.
116-
117-
### Tracer operations
118-
119-
#### GetCurrentSpan
120-
121-
Returns the current Span from the current context.
122-
123-
There should be no parameter.
124-
125-
Returns the default `Span` that does nothing and has an invalid `SpanContext` if
126-
no `Span` is associated with the current context, otherwise the current `Span`
127-
from the context.
128-
129-
#### WithSpan
130-
Enters the scope of code where the given `Span` is in the current context.
85+
The OpenTelemetry library achieves in-process context propagation of `Span`s by
86+
way of the `Tracer`.
13187

132-
Required parameters:
133-
134-
- The `Span` to be set to the current context.
135-
136-
Returns an object that defines a scope where the given `Span` will be set to the
137-
current context.
88+
The `Tracer` is responsible for tracking the currently active `Span`, and
89+
exposes methods for creating and activating new `Span`s. The `Tracer` is
90+
configured with `Propagator`s which support transferring span context across
91+
process boundaries.
13892

139-
The scope is exited and previous state should be restored when the returned
140-
object is closed.
93+
`Tracer`s are generally expected to be used as singletons. Implementations
94+
SHOULD provide a single global default `Tracer`.
14195

142-
#### SpanBuilder
143-
Returns a `SpanBuilder` to create and start a new `Span` if a `Builder` pattern
144-
for [Span creation](#span-creation) is used.
145-
146-
Required parameters:
96+
Some applications may require multiple `Tracer` instances, e.g. to create
97+
`Span`s on behalf of other applications. Implementations MAY provide a global
98+
registry of `Tracer`s for such applications.
14799

148-
- Name of the span.
149-
150-
Returns a `SpanBuilder` to create and start a new `Span`.
151-
152-
#### RecordSpanData
100+
### Obtaining a tracer
153101

154-
Records a `SpanData`.
102+
`Tracer` object construction and registration will vary by implementation.
103+
`Tracer`s may be explicitly created and registered from user code, or resolved
104+
from linked dependencies using the provider pattern.
155105

156-
Required parameters:
106+
Implementations might require the user to specify configuration properties at
107+
`Tracer` creation time, or rely on external configuration, e.g. when using the
108+
provider pattern.
157109

158-
- `SpanData` to be reported to all exporters.
110+
##### Runtimes with multiple deployments/applications
159111

160-
This API allows to send a pre-populated span object to the exporter. Sampling
161-
and recording decisions as well as other collection optimizations are a
162-
responsibility of a caller.
112+
Runtimes that support multiple deployments or applications might need to
113+
provide a different `Tracer` instance to each deployment. To support this,
163114

164-
Note, the `SpanContext` object in the span population with the values that will
165-
allow correlation of telemetry is also a caller responsibility.
115+
the global `Tracer` registry may delegate calls to create new `Tracer`s to a
116+
separate `Provider` component, and the runtime may include its own `Provider`
117+
implementation which returns a different `Tracer` for each deployment.
166118

167-
This API should be non-blocking.
119+
`Provider`s are registered with the API via some language-specific mechanism,
120+
for instance the `ServiceLoader` class in Java.
168121

169-
#### GetBinaryFormat
170-
Returns the binary format interface which can serialize/deserialize `Span`s.
122+
### Tracer operations
171123

172-
There should be no parameter.
124+
The `Tracer` MUST provide methods to:
173125

174-
Returns the binary format for this implementation. If no implementation is
175-
provided then no-op implementation will be used.
126+
- Get the currently active `Span`
127+
- Create a new `Span`
128+
- Make a given `Span` as active
176129

177-
#### GetHttpTextFormat
178-
Returns the HTTP text format interface which can inject/extract `Span`s.
130+
The `Tracer` SHOULD allow end users to configure other tracing components that
131+
control how `Span`s are passed across process boundaries, inclucding the binary
132+
and text format `Propagator`s used to serialize `Span`s created by the
133+
`Tracer`.
179134

180-
There should be no parameter.
135+
When getting the current span, the `Tracer` MUST return a placeholder `Span`
136+
with an invalid `SpanContext` if there is no currently active `Span`.
181137

182-
Returns the HTTP text format for this implementation. If no implementation is
183-
provided then no-op implementation will be used.
138+
When creating a new `Span`, the `Tracer` MUST allow the caller to specify the
139+
new `Span`'s parent in the form of a `Span` or `SpanContext`. The `Tracer`
140+
SHOULD create each new `Span` as a child of its active `Span` unless an
141+
explicit parent is provided or the option to create a span without a parent is
142+
selected, or the current active `Span` is invalid.
184143

185-
Usually this will be the W3C Trace Context as the HTTP text format. For more
144+
The `Tracer` MUST provide a way to update its active `Span`, and MAY provide
145+
convenience methods to manage a `Span`'s lifetime and the scope in which a
146+
`Span` is active. When an active `Span` is made inactive, the previously-active
147+
`Span` SHOULD be made active. A `Span` maybe finished (i.e. have a non-null end
148+
time) but stil active. A `Span` may be active on one thread after it has been
149+
made inactive on another.
150+
151+
The `Tracer` MUST support recording `Span`s that were created _out of band_,
152+
i.e. not by the tracer itself. For this reason, implementations MUST NOT
153+
require that a `Span`'s start and end timestamps match the wall time when it is
154+
created, made active, or finished.
155+
156+
The implementation MUST provide no-op binary and text `Propagator`s, which the
157+
`Tracer` SHOULD use by default if other propagators are not configured. SDKs
158+
SHOULD use the W3C HTTP Trace Context as the default text format. For more
186159
details, see [trace-context](https://github.com/w3c/trace-context).
187160

188161
## SpanContext
162+
189163
A `SpanContext` represents the portion of a `Span` which must be serialized and
190164
propagated along side of a distributed context. `SpanContext`s are immutable.
191165
`SpanContext` MUST be a final (sealed) class.
@@ -268,15 +242,6 @@ empty by default:
268242
- `Link`s
269243
- `Event`s
270244

271-
The `Tracer` MUST allow the caller to specify the new `Span`'s parent in the
272-
form of a `Span` or `SpanContext`. The `Tracer` SHOULD create each new `Span` as
273-
a child of its active `Span` unless an explicit parent is provided or the
274-
option to create a span without a parent is selected.```
275-
276-
The `Tracer` MUST provide a way to update its active `Span`, and MAY provide
277-
convenience methods to manage a `Span`'s lifetime of and the scope in which a
278-
`Span` is active.
279-
280245
Each span has zero or one parent span and zero or more child spans, which
281246
represent causally related operations. A tree of related spans comprises a
282247
trace. A span is said to be a _root span_ if it does not have a parent. Each

0 commit comments

Comments
 (0)