open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

moved distributed tracing terminology (#22) 

* distributed tracing terminology

* added comment

* addressed feedback
This commit is contained in:
Sergey Kanzhelev 2019-05-31 08:05:16 -07:00 committed by GitHub
parent 92b416804d
commit 647e98a2e1
3 changed files with 165 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

122
terminology.md
View File

@ -1 +1,123 @@
# Terminology
## Distributed Tracing
A distributed trace is a set of events, triggered as a result of a single
logical operation, consolidated across various components of an application. A
distributed trace contains events that cross process, network and security
boundaries. A distributed trace may be initiated when someone presses a button
to start an action on a website - in this example, the trace will represent
calls made between the downstream services that handled the chain of requests
initiated by this button being pressed.
### Trace
**Traces** in OpenTelemetry are defined implicitly by their **Spans**. In
particular, a **Trace** can be thought of as a directed acyclic graph (DAG) of
**Spans**, where the edges between **Spans** are defined as parent/child
relationship.
For example, the following is an example **Trace** made up of 8 **Spans**:
```
Causal relationships between Spans in a single Trace
[Span A] ←←←(the root span)
|
+------+------+
| |
[Span B] [Span C] ←←←(Span C is a `child` of Span A)
| |
[Span D] +---+-------+
| |
[Span E] [Span F]
```
Sometimes it's easier to visualize **Traces** with a time axis as in the diagram
below:
```
Temporal relationships between Spans in a single Trace
––|–––––––|–––––––|–––––––|–––––––|–––––––|–––––––|–––––––|–> time
[Span A···················································]
[Span B··············································]
[Span D··········································]
[Span C········································]
[Span E·······] [Span F··]
```
### Span
Each **Span** encapsulates the following state:
- An operation name
- A start and finish timestamp
- A set of zero or more key:value **Attributes**. The keys must be strings. The
values may be strings, bools, or numeric types.
- A set of zero or more **Events**, each of which is itself a key:value map
paired with a timestamp. The keys must be strings, though the values may be of
the same types as Span **Attributes**.
- Parent's **Span** identifier.
- [**Links**](#links-between-spans) to zero or more causally-related **Spans**
(via the **SpanContext** of those related **Spans**).
- **SpanContext** identification of a Span. See below.
### SpanContext
Represents all the information that identifies **Span** in the **Trace** and
MUST be propagated to child Spans and across process boundaries. A
**SpanContext** 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).
- 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][https://w3c.github.io/trace-context/#tracestate-field].
### Links between spans
A **Span** may be linked to zero or more other **Spans** (defined by
**SpanContext**) that are causally related. **Links** can point to
**SpanContexts** inside a single **Trace** or across different **Traces**.
**Links** can be used to represent batched operations where a **Span** has
multiple parents, each representing a single incoming item being processed in
the batch. Another example of using a **Link** is to declare relationship
between originating and restarted trace. This can be used when **Trace** enters
trusted boundaries of an service and service policy requires to generate a new
Trace instead of trusting incoming Trace context.
## Metrics
TODO: Describe metrics terminology https://github.com/open-telemetry/opentelemetry-specification/issues/45
## Tags
TODO: Describe tags terminology https://github.com/open-telemetry/opentelemetry-specification/issues/46
## Resources
TODO: Describe resources terminology https://github.com/open-telemetry/opentelemetry-specification/issues/47
## Agent/Collector
TODO: Describe agent/collector terminology https://github.com/open-telemetry/opentelemetry-specification/issues/48
## Adaptors
TODO: Describe adaptors terminology https://github.com/open-telemetry/opentelemetry-specification/issues/49

119
work_in_progress/specification/README.md
View File

@ -12,47 +12,7 @@ The OpenTracing specification uses a `Major.Minor` version number but has no `.P
## The OpenTracing Data Model
**Traces** in OpenTracing are defined implicitly by their **Spans**. In
particular, a **Trace** can be thought of as a directed acyclic graph (DAG) of
**Spans**, where the edges between **Spans** are called **References**.
For example, the following is an example **Trace** made up of 8 **Spans**:
~~~
Causal relationships between Spans in a single Trace
[Span A] ←←←(the root span)
|
+------+------+
| |
[Span B] [Span C] ←←←(Span C is a `ChildOf` Span A)
| |
[Span D] +---+-------+
| |
[Span E] [Span F] >>> [Span G] >>> [Span H]
↑
↑
↑
(Span G `FollowsFrom` Span F)
~~~
Sometimes it's easier to visualize **Traces** with a time axis as in the
diagram below:
~~~
Temporal relationships between Spans in a single Trace
––|–––––––|–––––––|–––––––|–––––––|–––––––|–––––––|–––––––|–> time
[Span A···················································]
[Span B··············································]
[Span D··········································]
[Span C········································]
[Span E·······] [Span F··] [Span G··] [Span H··]
~~~
... moved to [terminology.md](../terminology.md) ...
Each **Span** encapsulates the following state:
@ -76,44 +36,47 @@ Each **SpanContext** encapsulates the following state:
### References between Spans
A Span may reference zero or more other **SpanContexts** that are causally related. OpenTracing presently defines two types of references: `ChildOf` and `FollowsFrom`. **Both reference types specifically model direct causal relationships between a child Span and a parent Span.** In the future, OpenTracing may also support reference types for Spans with non-causal relationships (e.g., Spans that are batched together, Spans that are stuck in the same queue, etc).
**`ChildOf` references:** A Span may be the `ChildOf` a parent Span. In a `ChildOf` reference, the parent Span depends on the child Span in some capacity. All of the following would constitute `ChildOf` relationships:
- A Span representing the server side of an RPC may be the `ChildOf` a Span representing the client side of that RPC
- A Span representing a SQL insert may be the `ChildOf` a Span representing an ORM save method
- Many Spans doing concurrent (perhaps distributed) work may all individually be the `ChildOf` a single parent Span that merges the results for all children that return within a deadline
These could all be valid timing diagrams for children that are the `ChildOf` a parent.
~~~
[-Parent Span---------]
[-Child Span----]
[-Parent Span--------------]
[-Child Span A----]
[-Child Span B----]
[-Child Span C----]
[-Child Span D---------------]
[-Child Span E----]
~~~
**`FollowsFrom` references:** Some parent Spans do not depend in any way on the result of their child Spans. In these cases, we say merely that the child Span `FollowsFrom` the parent Span in a causal sense. There are many distinct `FollowsFrom` reference sub-categories, and in future versions of OpenTracing they may be distinguished more formally.
These can all be valid timing diagrams for children that "FollowFrom" a parent.
~~~
[-Parent Span-] [-Child Span-]
[-Parent Span--]
[-Child Span-]
[-Parent Span-]
[-Child Span-]
~~~
OpenTelemetry doesn't support references. Links are described in
[terminology.md](../terminology.md)
> A Span may reference zero or more other **SpanContexts** that are causally related. OpenTracing presently defines two types of references: `ChildOf` and `FollowsFrom`. **Both reference types specifically model direct causal relationships between a child Span and a parent Span.** In the future, OpenTracing may also support reference types for Spans with non-causal relationships (e.g., Spans that are batched together, Spans that are stuck in the same queue, etc).
>
> **`ChildOf` references:** A Span may be the `ChildOf` a parent Span. In a `ChildOf` reference, the parent Span depends on the child Span in some capacity. All of the following would constitute `ChildOf` relationships:
>
> - A Span representing the server side of an RPC may be the `ChildOf` a Span representing the client side of that RPC
>- A Span representing a SQL insert may be the `ChildOf` a Span representing an ORM save method
>- Many Spans doing concurrent (perhaps distributed) work may all individually be the `ChildOf` a single parent Span that merges the results for all children that return within a deadline
>
>These could all be valid timing diagrams for children that are the `ChildOf` a parent.
>
>~~~
> [-Parent Span---------]
> [-Child Span----]
>
> [-Parent Span--------------]
> [-Child Span A----]
> [-Child Span B----]
> [-Child Span C----]
> [-Child Span D---------------]
> [-Child Span E----]
>~~~
>
>**`FollowsFrom` references:** Some parent Spans do not depend in any way on the result of their child Spans. In these cases, we say merely that the child Span `FollowsFrom` the parent Span in a causal sense. There are many distinct `FollowsFrom` reference sub-categories, and in future versions of OpenTracing they may be distinguished more formally.
>
>These can all be valid timing diagrams for children that "FollowFrom" a parent.
>
>~~~
> [-Parent Span-] [-Child Span-]
>
>
> [-Parent Span--]
> [-Child Span-]
>
>
> [-Parent Span-]
> [-Child Span-]
>~~~
>
## The OpenTracing API

33
work_in_progress/specification/trace/Span.md
View File

@ -1,40 +1,12 @@
# 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.
... parts of this document moved to [terminology.md](../terminology.md) ...
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:
@ -84,4 +56,3 @@ 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