From f649f7e619f202f63d1e0302f05500bdd0f37023 Mon Sep 17 00:00:00 2001 From: Matthew Wear Date: Tue, 28 Jan 2020 14:45:42 -0800 Subject: [PATCH] Add details for determining the parent Span from a Context (#423) * Add details for parenting a span from a context * Integrate suggested feedback * Apply suggestion Co-Authored-By: Yuri Shkuro * Apply suggestion Co-Authored-By: Yuri Shkuro * Apply suggestion Co-Authored-By: Yuri Shkuro * Add comma Co-Authored-By: Armin Ruech * Rephrase parenting a span * Fix broken link Co-authored-by: Yuri Shkuro Co-authored-by: Armin Ruech Co-authored-by: Bogdan Drutu --- specification/api-tracing.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 6702d1ef596..85dd23b36fa 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -20,6 +20,7 @@ Table of Contents * [SpanContext](#spancontext) * [Span](#span) * [Span creation](#span-creation) + * [Determining the Parent Span from a Context](#determining-the-parent-span-from-a-context) * [Add Links](#add-links) * [Span operations](#span-operations) * [Get Context](#get-context) @@ -257,9 +258,11 @@ as a separate operation. The API MUST accept the following parameters: - The span name. This is a required parameter. -- The parent Span or parent Span context, and whether the new `Span` should be a - root `Span`. API MAY also have an option for implicit parent context - extraction from the current context as a default behavior. +- The parent `Span` or a `Context` containing a parent `Span` or `SpanContext`, + and whether the new `Span` should be a root `Span`. API MAY also have an + option for implicit parenting from the current context as a default behavior. + See [Determining the Parent Span from a Context](#determining-the-parent-span-from-a-context) + for guidance on `Span` parenting from explicit and implicit `Context`s. - [`SpanKind`](#spankind), default to `SpanKind.Internal` if not specified. - `Attribute`s - A collection of key-value pairs, with the same semantics as the ones settable with [Span::SetAttributes](#set-attributes). Additionally, @@ -290,6 +293,21 @@ created in another process. Each propagators' deserialization must set `IsRemote` to true on a parent `SpanContext` so `Span` creation knows if the parent is remote. +#### Determining the Parent Span from a Context + +When a new `Span` is created from a `Context`, the `Context` may contain: + +- A current `Span` +- An extracted `SpanContext` +- A current `Span` and an extracted `SpanContext` +- Neither a current `Span` nor an extracted `Span` context + +The parent should be selected in the following order of precedence: + +- Use the current `Span`, if available. +- Use the extracted `SpanContext`, if available. +- There is no parent. Create a root `Span`. + #### Add Links During the `Span` creation user MUST have the ability to record links to other `Span`s. Linked