88 lines
4.4 KiB
Markdown
88 lines
4.4 KiB
Markdown
# Span
|
|
|
|
Span represents a single operation within a trace. Spans can be nested to form a trace tree.
|
|
Often, a trace contains a root span that describes the end-to-end latency and, optionally, one or
|
|
more sub-spans for its sub-operations.
|
|
|
|
A span contains a SpanContext and allows users to record tracing events based on the data model
|
|
defined [here][SpanDataModel].
|
|
|
|
## Span structure
|
|
|
|
### SpanContext
|
|
Represents all the information that MUST be propagated to child Spans and across process boundaries.
|
|
A span context contains the tracing identifiers and the options that are propagated from parent
|
|
to child Spans.
|
|
|
|
#### TraceId
|
|
Is the identifier for a trace. It is worldwide unique with practically sufficient
|
|
probability by being made as 16 randomly generated bytes. TraceId is used to group all spans for
|
|
a specific trace together across all processes.
|
|
|
|
#### SpanId
|
|
Is the identifier for a span. It is globally unique with practically sufficient probability by
|
|
being made as 8 randomly generated bytes. When passed to a child Span this identifier becomes the
|
|
parent span id for the child Span.
|
|
|
|
#### TraceOptions
|
|
Represents the options for a trace. It is represented as 1 byte (bitmap).
|
|
|
|
##### Supported bits
|
|
* Sampling bit - Bit to represent whether trace is sampled or not (mask `0x1`).
|
|
|
|
#### Tracestate
|
|
Carries tracing-system specific context in a list of key value pairs. Tracestate allows different
|
|
vendors propagate additional information and inter-operate with their legacy Id formats.
|
|
|
|
For more details see [this][TracestateLink].
|
|
|
|
## Span creation
|
|
The implementation MUST allow users to create two types of Spans:
|
|
* Root Spans - spans that do not have a parent.
|
|
* Child Spans - the parent can be explicitly set or inherit from the Context.
|
|
|
|
When creating a Span the implementation MUST allow users to create the Span attached or detached
|
|
from the Context, this allows users to manage the interaction with the Context independently of
|
|
the Span lifetime:
|
|
* Attached to the Context - the newly created Span is attached to the Context.
|
|
* Detached from the Context - the newly created Span is not attached to any Context.
|
|
|
|
### How Span interacts with Context?
|
|
Context interaction represents the process of attaching/detaching a Span to the Context
|
|
in order to propagate it in-process (possibly between threads) and between function calls.
|
|
|
|
There are two supported implementations for the Context based on how the propagation is implemented:
|
|
* With implicit propagation - implicitly passed between function calls and threads, usually
|
|
implemented using thread-local variables (e.g. Java [io.grpc.Context][javaContext])
|
|
* With explicit propagation - explicitly passed between function calls and threads (e.g. Go
|
|
[context.Context][goContext])
|
|
|
|
When an implicit propagated Context is used, the implementation MUST use scoped objects to
|
|
attach/detach a Span (scoped objects represent auto closable objects, e.g. stack allocated
|
|
objects in C++):
|
|
* When attach/detach an already created Span the API MAY be called `WithSpan`.
|
|
* When attach/detach at the creation time the API MAY be called `StartSpan` or `StartScopedSpan`.
|
|
|
|
When an explicit propagated Context is used, the implementation MUST create a new Context when a
|
|
Span is attached (immutable Context):
|
|
* When attach/detach an already created Span the API MAY be called `WithSpan`.
|
|
* When attach/detach at the creation time the API MAY be called `StartSpan` or `StartScopedSpan`.
|
|
|
|
### What is Span lifetime?
|
|
Span lifetime represents the process of recording the start and the end timestamps to the Span
|
|
object:
|
|
* The start time is recorded when the Span is created.
|
|
* The end time needs to be recorded when the operation is ended.
|
|
|
|
### Why support Spans that are not attached to the Context?
|
|
* Allow users to use the OpenCensus library without using a Context.
|
|
* Allow users to have more control for the lifetime of the Span.
|
|
* There are cases, for example HTTP/RPC interceptors, where the Span creation and usage happens in
|
|
different places, and the user does not have control of the framework to control the Context
|
|
propagation.
|
|
|
|
[goContext]: https://golang.org/pkg/context
|
|
[javaContext]: https://github.com/grpc/grpc-java/blob/master/context/src/main/java/io/grpc/Context.java
|
|
[SpanDataModel]: https://github.com/census-instrumentation/opencensus-proto/blob/master/src/opencensus/proto/trace/v1/trace.proto
|
|
[TracestateLink]: https://w3c.github.io/trace-context/#tracestate-field
|