diff --git a/terminology.md b/terminology.md index e2e2597f4..ba732e6b3 100644 --- a/terminology.md +++ b/terminology.md @@ -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 \ No newline at end of file diff --git a/work_in_progress/specification/README.md b/work_in_progress/specification/README.md index cb2fa5b17..a87b27303 100644 --- a/work_in_progress/specification/README.md +++ b/work_in_progress/specification/README.md @@ -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 diff --git a/work_in_progress/specification/trace/Span.md b/work_in_progress/specification/trace/Span.md index b42bdd972..60bfa91b9 100644 --- a/work_in_progress/specification/trace/Span.md +++ b/work_in_progress/specification/trace/Span.md @@ -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