Skip to content

Commit

Permalink
clarifies parent and links (#283)
Browse files Browse the repository at this point in the history
* clarifies parent and links

* Update specification/overview.md
  • Loading branch information
SergeyKanzhelev authored and bogdandrutu committed Oct 5, 2019
1 parent 5622123 commit d18fc36
Show file tree
Hide file tree
Showing 2 changed files with 19 additions and 7 deletions.
23 changes: 17 additions & 6 deletions specification/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,12 +95,23 @@ propagated from parent to child **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.
**Links** can be used to represent batched operations where a **Span** was
initiated by multiple initiating **Span**s, each representing a single incoming
item being processed in the batch. Another example of using a **Link** is to
declare relationship between originating and followed trace. This can be used
when **Trace** enters trusted boundaries of a service and service policy
requires to generate a new Trace instead of trusting incoming Trace context. Or
when long running Trace representing asynchronous data processing operation was
initiated by one of many fast incoming request.

In case of scatter/gather pattern, when the root operation starts multiple
downstream processing operations and all of them being aggregated back in a
single **Span**, this last **Span** is linked to many operations it
aggregates. All of them are the **Span**s from the same Trace. And similar to
the Parent field of a **Span**. It is recommended, however, to not set parent of
the **Span** in this scenario as semantically parent field represents a single
parent scenario, in many cases parent **Span** fully encloses the child
**Span**. Which is not the case in scatter/gather and batch scenarios.

## Metrics

Expand Down
3 changes: 2 additions & 1 deletion specification/sdk-tracing.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,8 @@ Returns the sampling Decision for a `Span` to be created.
- `SpanId` of the `Span` to be created.
- Name of the `Span` to be created.
- Collection of links that will be associated with the `Span` to be created.
Typically useful for batch operations.
Typically useful for batch operations, see [Links Between
Spans](overview.md#links-between-spans).

**Return value:**

Expand Down

0 comments on commit d18fc36

Please sign in to comment.