From 121bb389cdceeae56ca7c7f3b84fec7314078c90 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Wed, 2 Oct 2019 23:11:53 -0700 Subject: [PATCH 1/2] clarifies parent and links --- 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..d1823e01369 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 parent 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:** From 279a26d70a2ef27f6dd83b25aa09315b5d1454b7 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Thu, 3 Oct 2019 10:28:14 -0700 Subject: [PATCH 2/2] Update specification/overview.md --- specification/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/overview.md b/specification/overview.md index d1823e01369..87838ae133d 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -106,7 +106,7 @@ 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 parent operations it +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