From d18fc360a2d3e6af64934bcbbe3190fc688adcd1 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Fri, 4 Oct 2019 20:21:31 -0700 Subject: [PATCH] clarifies parent and links (#283) * clarifies parent and links * Update specification/overview.md --- specification/overview.md | 23 +++++++++++++++++------ specification/sdk-tracing.md | 3 ++- 2 files changed, 19 insertions(+), 7 deletions(-) diff --git a/specification/overview.md b/specification/overview.md index aa3256f5bdb..87838ae133d 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -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 diff --git a/specification/sdk-tracing.md b/specification/sdk-tracing.md index 4f10bd6ec6a..dad5aa3965b 100644 --- a/specification/sdk-tracing.md +++ b/specification/sdk-tracing.md @@ -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:**