From 71ad7d03b8df36a8731af96b2f4756af534f618c Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Mon, 7 Oct 2019 12:15:09 -0700 Subject: [PATCH 1/9] addressed feedback from @haf --- specification/overview.md | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/specification/overview.md b/specification/overview.md index 87838ae133d..bde8a637f37 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -97,21 +97,24 @@ A **Span** may be linked to zero or more other **Spans** (defined by **SpanContexts** inside a single **Trace** or across different **Traces**. **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 +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 the generation of a new +Trace rather than trusting the incoming Trace context. The new linked Trace may +also represent a long running asynchronous data processing operation that 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. +When using the scatter/gather (also called fork/join) pattern, 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 From 3acb518cc12ef5d800b483f29794febc7c1e9a0a Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Wed, 9 Oct 2019 15:59:10 -0700 Subject: [PATCH 2/9] Update specification/overview.md Co-Authored-By: Chris Kleinknecht --- specification/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/overview.md b/specification/overview.md index bde8a637f37..857e26443a7 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -99,7 +99,7 @@ A **Span** may be linked to zero or more other **Spans** (defined by 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 +Another example of using a **Link** is to declare the relationship between originating and followed trace. This can be used when **Trace** enters trusted boundaries of a service and service policy requires the generation of a new Trace rather than trusting the incoming Trace context. The new linked Trace may From 3604728d3c6ff6ecf90c1c092b65e27a83a87364 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Wed, 9 Oct 2019 15:59:16 -0700 Subject: [PATCH 3/9] Update specification/overview.md Co-Authored-By: Chris Kleinknecht --- specification/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/overview.md b/specification/overview.md index 857e26443a7..89635743f41 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -100,7 +100,7 @@ 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 the relationship between -originating and followed trace. This can be used when **Trace** enters trusted +the originating and following trace. This can be used when a **Trace** enters trusted boundaries of a service and service policy requires the generation of a new Trace rather than trusting the incoming Trace context. The new linked Trace may also represent a long running asynchronous data processing operation that was From 65f13fd7aed2d65f8cb1957e3aa648773e08e2f6 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Wed, 9 Oct 2019 15:59:22 -0700 Subject: [PATCH 4/9] Update specification/overview.md Co-Authored-By: Chris Kleinknecht --- specification/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/overview.md b/specification/overview.md index 89635743f41..f3b7780514c 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -104,7 +104,7 @@ the originating and following trace. This can be used when a **Trace** enters tr boundaries of a service and service policy requires the generation of a new Trace rather than trusting the incoming Trace context. The new linked Trace may also represent a long running asynchronous data processing operation that was -initiated by one of many fast incoming request. +initiated by one of many fast incoming requests. When using the scatter/gather (also called fork/join) pattern, the root operation starts multiple downstream processing operations and all of them being From 9c782bb1c3995764ad0b2db95a5ca70acfe029ff Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Wed, 9 Oct 2019 15:59:27 -0700 Subject: [PATCH 5/9] Update specification/overview.md Co-Authored-By: Chris Kleinknecht --- specification/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/overview.md b/specification/overview.md index f3b7780514c..d7154bb1e92 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -108,7 +108,7 @@ initiated by one of many fast incoming requests. When using the scatter/gather (also called fork/join) pattern, 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 +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 From 6a5b5b4b92e2b8fcbca05be849b3cc2f1238f79a Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Wed, 9 Oct 2019 15:59:33 -0700 Subject: [PATCH 6/9] Update specification/overview.md Co-Authored-By: Chris Kleinknecht --- specification/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/overview.md b/specification/overview.md index d7154bb1e92..c16cd19cd91 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -107,7 +107,7 @@ also represent a long running asynchronous data processing operation that was initiated by one of many fast incoming requests. When using the scatter/gather (also called fork/join) pattern, the root -operation starts multiple downstream processing operations and all of them being +operation starts multiple downstream processing operations and all of them are 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 From e7ec4ea42e051282236dd4f7db763348452f2cba Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Wed, 9 Oct 2019 15:59:38 -0700 Subject: [PATCH 7/9] Update specification/overview.md Co-Authored-By: Chris Kleinknecht --- specification/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/overview.md b/specification/overview.md index c16cd19cd91..d869e9976cf 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -111,7 +111,7 @@ operation starts multiple downstream processing operations and all of them are 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 +set parent of the **Span** in this scenario as semantically the 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. From 1e7da19b5b77cb339788edbd9e9535a16609e449 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Wed, 9 Oct 2019 15:59:44 -0700 Subject: [PATCH 8/9] Update specification/overview.md Co-Authored-By: Chris Kleinknecht --- specification/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/overview.md b/specification/overview.md index d869e9976cf..1c7c36e2994 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -112,7 +112,7 @@ 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 the parent field -represents a single parent scenario, in many cases parent **Span** fully +represents a single parent scenario, in many cases the parent **Span** fully encloses the child **Span**. Which is not the case in scatter/gather and batch scenarios. From 8fefee6632f2c7beb9042ceb5dd27e183c582279 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Wed, 9 Oct 2019 15:59:49 -0700 Subject: [PATCH 9/9] Update specification/overview.md Co-Authored-By: Chris Kleinknecht --- specification/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/overview.md b/specification/overview.md index 1c7c36e2994..44abbb60b21 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -113,7 +113,7 @@ 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 the parent field represents a single parent scenario, in many cases the parent **Span** fully -encloses the child **Span**. Which is not the case in scatter/gather and batch +encloses the child **Span**. This is not the case in scatter/gather and batch scenarios. ## Metrics