From cf0bb600b2eef359dbdd8fbe6f4696ed3e67ed1d Mon Sep 17 00:00:00 2001 From: Matthew Wear Date: Tue, 28 Jan 2020 14:45:42 -0800 Subject: [PATCH 1/3] 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 From d212c5479cdc734d363ee893ae72bcbf2113c355 Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Wed, 29 Jan 2020 09:49:23 -0700 Subject: [PATCH 2/3] sdk-tracer: replace Factory with Provider (#422) Co-authored-by: Bogdan Drutu --- specification/sdk-tracing.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/specification/sdk-tracing.md b/specification/sdk-tracing.md index dfb602c8720..38e54cbb4e7 100644 --- a/specification/sdk-tracing.md +++ b/specification/sdk-tracing.md @@ -127,14 +127,15 @@ of the `TraceID`. ## Tracer Creation -New `Tracer` instances are always created through a `TracerFactory` (see [API](api-tracing.md#obtaining-a-tracer)). -The `name` and `version` arguments supplied to the `TracerFactory` must be used -to create a `Resource` instance which is stored on the created `Tracer`. +New `Tracer` instances are always created through a `TracerProvider` (see +[API](api-tracing.md#obtaining-a-tracer)). The `name` and `version` arguments +supplied to the `TracerProvider` must be used to create a +[`Resource`](sdk-resource.md) instance which is stored on the created `Tracer`. All configuration objects (SDK specific) and extension points (span processors, -propagators) must be provided to the `TracerFactory`. `Tracer` instances must +propagators) must be provided to the `TracerProvider`. `Tracer` instances must not duplicate this data (unless for read-only access) to avoid that different -`Tracer` instances of a `TracerFactory` have different versions of these data. +`Tracer` instances of a `TracerProvider` have different versions of these data. The readable representations of all `Span` instances created by a `Tracer` must provide a `getLibraryResource` method that returns this `Resource` information @@ -149,20 +150,20 @@ invocations. The span processors are invoked only when Built-in span processors are responsible for batching and conversion of spans to exportable representation and passing batches to exporters. -Span processors can be registered directly on SDK `TracerFactory` and they are +Span processors can be registered directly on SDK `TracerProvider` and they are invoked in the same order as they were registered. -All `Tracer` instances created by a `TracerFactory` share the same span processors. +All `Tracer` instances created by a `TracerProvider` share the same span processors. Changes to this collection reflect in all `Tracer` instances. Implementation-wise, this could mean that `Tracer` instances have a reference to -their `TracerFactory` and can access span processor objects only via this +their `TracerProvider` and can access span processor objects only via this reference. -Manipulation of the span processors collection must only happen on `TracerFactory` +Manipulation of the span processors collection must only happen on `TracerProvider` instances. This means methods like `addSpanProcessor` must be implemented on -`TracerFactory`. +`TracerProvider`. -Each processor registered on `TracerFactory` is a start of pipeline that consist +Each processor registered on `TracerProvider` is a start of pipeline that consist of span processor and optional exporter. SDK MUST allow to end each pipeline with individual exporter. From 3bbed37ba65df027721a6a3ab62f62dfc7fcf467 Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Thu, 30 Jan 2020 16:15:23 -0700 Subject: [PATCH 3/3] update Resource spec based on the move to the SDK and named tracers (#421) * update Resource spec based on the move to the SDK and named tracers * Update specification/sdk-resource.md Co-Authored-By: Tyler Yahn * Update specification/sdk-resource.md Co-Authored-By: Tyler Yahn * Update specification/sdk-resource.md Co-Authored-By: Tyler Yahn * provide example of what the entity producing telemetry means * Update specification/sdk-resource.md Co-Authored-By: John Watson Co-authored-by: Tyler Yahn Co-authored-by: John Watson Co-authored-by: Bogdan Drutu --- specification/sdk-resource.md | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/specification/sdk-resource.md b/specification/sdk-resource.md index 3cfa510c2f3..54d60320b50 100644 --- a/specification/sdk-resource.md +++ b/specification/sdk-resource.md @@ -1,25 +1,30 @@ # Resource SDK -A [Resource](overview.md#resources) represents the entity producing telemetry. -The primary purpose of resources as a first-class concept in the API is +A [Resource](overview.md#resources) represents the entity producing +telemetry. For example, a process producing telemetry that is running in a +container on Kubernetes has a Pod name, it is in a namespace and possibly is +part of a Deployment which also has a name. All three of these attributes can be +included in the `Resource`. + +The primary purpose of resources as a first-class concept in the SDK is decoupling of discovery of resource information from exporters. This allows for independent development and easy customization for users that need to integrate -with closed source environments. API MUST allow for creation of `Resources` and +with closed source environments. The SDK MUST allow for creation of `Resources` and for associating them with telemetry. When used with distributed tracing, a resource can be associated with the -[TracerSdk](sdk-tracing.md#tracer-sdk). When associated with `TracerSdk`, all -`Span`s produced by the `Tracer`, that is implemented by this `TracerSdk`, will +[TracerProvider](sdk-tracing.md#tracer-sdk). When associated with a +`TracerProvider`, all `Span`s produced by any `Tracer` from the provider will automatically be associated with this `Resource`. When used with metrics, a resource can be associated with the -[MeterSdk](sdk-metrics.md#meter-sdk). When associated with `MeterSdk`, all -`Metrics` produced by this `Meter`, that is implemented by this `MeterSdk`, will -automatically be associated with this `Resource`. +[MeterProvider](sdk-metrics.md#meter-sdk). When associated with a `MeterProvider`, +all `Metrics` produced by any `Meter` from the provider will automatically be +associated with this `Resource`. ## Resource creation -The API interface must support two ways to instantiate new resources. Those are: +The SDK must support two ways to instantiate new resources. Those are: ### Create @@ -66,7 +71,7 @@ In addition to resource creation, the following operations should be provided: ### Retrieve attributes -The API should provide a way to retrieve a read only collection of attributes +The SDK should provide a way to retrieve a read only collection of attributes associated with a resource. The attributes should consist of the name and values, both of which should be strings.