From d65d2f395d0109febe62052f8138075e4b965e6f Mon Sep 17 00:00:00 2001 From: Krzesimir Nowak Date: Tue, 4 Feb 2020 14:24:26 +0100 Subject: [PATCH 1/2] Require tracer to add ignored parents as links This also adds an initial document about semantic conventions of the link attributes. --- specification/api-tracing.md | 8 +++++ .../data-link-semantic-conventions.md | 34 +++++++++++++++++++ specification/data-semantic-conventions.md | 1 + 3 files changed, 43 insertions(+) create mode 100644 specification/data-link-semantic-conventions.md diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 6e6c8c0d258..85e9a4a4812 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -286,6 +286,14 @@ a root span, and MUST generate a new `TraceId` for each root span created. For a Span with a parent, the `TraceId` MUST be the same as the parent. Also, the child span MUST inherit all `TraceState` values of its parent by default. +The option for creating a span as a root span should allow to choose whether the +ignored parents in `Context` should be captured as links in the new span. If the +links should be captured then the implementation SHOULD add those possible +parents as [`Link`s](#add-links) to the new `Span`. For description of the +ignored-parent link attributes, see [Link +Conventions](data-link-semantic-conventions.md#ignored-parent). The capturing is +off by default. + A `Span` is said to have a _remote parent_ if it is the child of a `Span` created in another process. Each propagators' deserialization must set `IsRemote` to true on a parent `SpanContext` so `Span` creation knows if the diff --git a/specification/data-link-semantic-conventions.md b/specification/data-link-semantic-conventions.md new file mode 100644 index 00000000000..33266c3367d --- /dev/null +++ b/specification/data-link-semantic-conventions.md @@ -0,0 +1,34 @@ +# Link Conventions + +This document is about standard attributes for +[Links](api-tracing.md#add-links). + +## Document conventions + +Attributes are divided into groups, depending on the link type. Attributes in +each group are prefixed with the link type and a dot. + +Certain attribute groups in this document have a **Required** column. If an +attribute in the group that is described by the link type is marked as required +then the attribute MUST be present in the Link. If the **Required** column is +missing, then it is assumed that all the attributes in the group are optional. + +## Link types + +A link may be of a certain type and this can be described by the `link.type` +attribute. The value of the attribute MUST be a string. Each type of the link +below will provide a description with the value of the attribute. + +* [Ignored parent](#ignored-parent) + +### Ignored parent + +**Link type:** `ignored-parent` + +**Description:** These attributes are used to denote a span context that was +ignored during a span creation as a parent and thus became only linked to the +span. + +| Attribute | Description | Example | Required? | +|---|---|---|---| +| ignored-parent.kind | Kind of ignored span context. It MUST be either "local" or "remote". "local" denotes a span context that was a part of a current span at the time of a creation of the link. "remote" denotes a span context that was a part of remote span at the time of a creation of the link. | "local" | Yes | diff --git a/specification/data-semantic-conventions.md b/specification/data-semantic-conventions.md index 48280a63bec..453f4254b7a 100644 --- a/specification/data-semantic-conventions.md +++ b/specification/data-semantic-conventions.md @@ -5,6 +5,7 @@ Span attributes. * [Resource Conventions](data-resource-semantic-conventions.md) * [Span Conventions](#span-conventions) +* [Link Conventions](data-link-semantic-conventions.md) The type of the attribute SHOULD be specified in the semantic convention for that attribute. Array values are allowed for attributes. For From e596853d2fd419b4e16ae36f185fae8d1d837975 Mon Sep 17 00:00:00 2001 From: Krzesimir Nowak Date: Fri, 7 Feb 2020 16:28:12 +0100 Subject: [PATCH 2/2] Drop link-type attribute and simplify prefix for ignored parents --- .../data-link-semantic-conventions.md | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/specification/data-link-semantic-conventions.md b/specification/data-link-semantic-conventions.md index 33266c3367d..6f1cb03d3cf 100644 --- a/specification/data-link-semantic-conventions.md +++ b/specification/data-link-semantic-conventions.md @@ -5,25 +5,20 @@ This document is about standard attributes for ## Document conventions -Attributes are divided into groups, depending on the link type. Attributes in -each group are prefixed with the link type and a dot. +Attributes are divided into groups, describing certain characteristics of a +link. Attributes in each group start with a specified prefix and a dot. -Certain attribute groups in this document have a **Required** column. If an -attribute in the group that is described by the link type is marked as required -then the attribute MUST be present in the Link. If the **Required** column is -missing, then it is assumed that all the attributes in the group are optional. +Attribute groups in this document have a **Required** column. If a link has at +least one attribute from the group, then it MUST also contain all the required +attributes of the group. ## Link types -A link may be of a certain type and this can be described by the `link.type` -attribute. The value of the attribute MUST be a string. Each type of the link -below will provide a description with the value of the attribute. - * [Ignored parent](#ignored-parent) ### Ignored parent -**Link type:** `ignored-parent` +**Prefix:** parent **Description:** These attributes are used to denote a span context that was ignored during a span creation as a parent and thus became only linked to the @@ -31,4 +26,4 @@ span. | Attribute | Description | Example | Required? | |---|---|---|---| -| ignored-parent.kind | Kind of ignored span context. It MUST be either "local" or "remote". "local" denotes a span context that was a part of a current span at the time of a creation of the link. "remote" denotes a span context that was a part of remote span at the time of a creation of the link. | "local" | Yes | +| parent.kind | Kind of ignored span context. It MUST be either "local" or "remote". "local" denotes a span context that was a part of a current span at the time of a creation of the link. "remote" denotes a span context that was a part of remote span at the time of a creation of the link. | "local" | Yes |