From 65db847cad177f84d8ab50e038b71f54e007c210 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Fri, 9 Aug 2019 13:04:41 -0700 Subject: [PATCH 01/12] s/content/contents/ --- specification/api-metrics.md | 2 +- specification/api-propagators.md | 2 +- specification/api-tracing.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/api-metrics.md b/specification/api-metrics.md index 87cb682540b..544fafd2fde 100644 --- a/specification/api-metrics.md +++ b/specification/api-metrics.md @@ -2,7 +2,7 @@
-Table of Content +Table of Contents - [Meter](#meater) diff --git a/specification/api-propagators.md b/specification/api-propagators.md index d7ff5a97c2f..3a53a9b9628 100644 --- a/specification/api-propagators.md +++ b/specification/api-propagators.md @@ -2,7 +2,7 @@
-Table of Content +Table of Contents - [Binary Format](#binary-format) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 980762214e0..31f6292ac2b 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -2,7 +2,7 @@
-Table of Content +Table of Contents * [Data types](#data-types) From 00cf95a472b2411a3029b559654261aa6b93b01c Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Fri, 9 Aug 2019 13:57:43 -0700 Subject: [PATCH 02/12] Fix typo --- specification/api-tracing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 31f6292ac2b..5dd9c88d7ae 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -272,7 +272,7 @@ empty by default: The `Tracer` MUST allow the caller to specify the new `Span`'s parent in the form of a `Span` or `SpanContext`. The `Tracer` SHOULD create each new `Span` as a child of its active `Span` unless an explicit parent is provided or the -option to create a span without a parent is selected.``` +option to create a span without a parent is selected. The `Tracer` MUST provide a way to update its active `Span`, and MAY provide convenience methods to manage a `Span`'s lifetime of and the scope in which a From 8f59e21b5d273f274c962f5e04a5646bf1713f42 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Fri, 9 Aug 2019 16:36:22 -0700 Subject: [PATCH 03/12] Remove impl-specific details, shuffle text --- specification/api-tracing.md | 132 +++++++++++++---------------------- 1 file changed, 50 insertions(+), 82 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 5dd9c88d7ae..5c03fb5bdb0 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -83,22 +83,31 @@ A duration is the elapsed time between two events. ## Tracer -### Obtaining a tracer +The OpenTelemetry library achieves in-process context propagation of `Span`s by +way of the `Tracer`. + +The `Tracer` is responsible for tracking the currently active `Span`, and +exposes methods for creating and activating new `Span`s. The `Tracer` is +configured with `Propagator`s which support transferring context across process +boundaries, and `Exporter`s and `SpanProcessor`s which control how spans are +exported to APMs. -A tracer SHOULD be obtained from a global registry, for example -`OpenTelemetry.getTracer()`. +`Tracer`s are generally expected to be used as singletons. Implementations +SHOULD provide a single global default `Tracer`. -The registration to the registry depends on the language. In some languages the -tracer is explicitly created and registered from user code and other languages -the tracer implementation is resolved from linked dependencies using provider -pattern. +Some applications may require multiple `Tracer` instances, e.g. to create +`Span`s on behalf of other applications. Implementations MAY provide a global +registry of `Tracer`s for such applications. -The tracer object construction depends on the implementation. Various -implementations might require to specify different configuration properties at -creation time. In languages where provider pattern is used the configuration is -provided externally. +### Obtaining a tracer -#### Tracer provider +`Tracer` object construction and registration will vary by implementation. +`Tracer`s may be explicitly created and registered from user code, or resolved +from linked dependencies using the provider pattern. + +Implementations might require the user to specify configuration properties at +`Tracer` creation time, or rely on external configuration, e.g. in the case of +the provider pattern. Tracer provider is an internal class used by the global registry (`OpenTelemetry`) to get a tracer instance. The global registry delegates calls @@ -117,76 +126,44 @@ tracer for each deployment. ### Tracer operations -#### GetCurrentSpan - -Returns the current Span from the current context. - -There should be no parameter. - -Returns the default `Span` that does nothing and has an invalid `SpanContext` if -no `Span` is associated with the current context, otherwise the current `Span` -from the context. - -#### WithSpan -Enters the scope of code where the given `Span` is in the current context. +The `Tracer` MUST provide methods to: -Required parameters: - -- The `Span` to be set to the current context. - -Returns an object that defines a scope where the given `Span` will be set to the -current context. +- Get the currently active `Span` +- Create a new `Span` +- Set a given `Span` as active -The scope is exited and previous state should be restored when the returned -object is closed. +The `Tracer` SHOULD allow end users to configure other tracing components that +control how spans are serialized and exported: -#### SpanBuilder -Returns a `SpanBuilder` to create and start a new `Span` if a `Builder` pattern -for [Span creation](#span-creation) is used. - -Required parameters: +- the binary and text format `Propagator`s used to serialize `Spans` created by the `Tracer` +- the `SpanProcessor`s and `Exporter`s used to export `Spans` created by the `Tracer` -- Name of the span. +When getting the current span, the `Tracer` MUST return a placeholder `Span` +with an invalid `SpanContext` if there is no currently active `Span`. -Returns a `SpanBuilder` to create and start a new `Span`. - -#### RecordSpanData - -Records a `SpanData`. - -Required parameters: +When creating a new `Span`, the `Tracer` MUST allow the caller to specify the +new `Span`'s parent in the form of a `Span` or `SpanContext`. The `Tracer` +SHOULD create each new `Span` as a child of its active `Span` unless an +explicit parent is provided or the option to create a span without a parent is +selected. -- `SpanData` to be reported to all exporters. - -This API allows to send a pre-populated span object to the exporter. Sampling -and recording decisions as well as other collection optimizations are a -responsibility of a caller. - -Note, the `SpanContext` object in the span population with the values that will -allow correlation of telemetry is also a caller responsibility. - -This API should be non-blocking. - -#### GetBinaryFormat -Returns the binary format interface which can serialize/deserialize `Span`s. - -There should be no parameter. - -Returns the binary format for this implementation. If no implementation is -provided then no-op implementation will be used. - -#### GetHttpTextFormat -Returns the HTTP text format interface which can inject/extract `Span`s. - -There should be no parameter. - -Returns the HTTP text format for this implementation. If no implementation is -provided then no-op implementation will be used. - -Usually this will be the W3C Trace Context as the HTTP text format. For more +The `Tracer` MUST provide a way to update its active `Span`, and MAY provide +convenience methods to manage a `Span`'s lifetime and the scope in which a +`Span` is active. When an active span is finished, the previously-active span +SHOULD be made active. + +The `Tracer` MUST support recording spans that were created _out of band_, i.e. +not by the tracer itself. For this reason, implementations MUST NOT require +that a `Span`'s start and end timestamps match the wall time when it is +created, made active, or finished. + +The implementation MUST provide no-op binary and text `Propagator`s, which the +`Tracer` SHOULD use by default if other propagators are not configured. SDKs +SHOULD use the W3C HTTP Trace Context as the default text format. For more details, see [trace-context](https://github.com/w3c/trace-context). ## SpanContext + A `SpanContext` represents the portion of a `Span` which must be serialized and propagated along side of a distributed context. `SpanContext`s are immutable. `SpanContext` MUST be a final (sealed) class. @@ -269,15 +246,6 @@ empty by default: - `Link`s - `Event`s -The `Tracer` MUST allow the caller to specify the new `Span`'s parent in the -form of a `Span` or `SpanContext`. The `Tracer` SHOULD create each new `Span` as -a child of its active `Span` unless an explicit parent is provided or the -option to create a span without a parent is selected. - -The `Tracer` MUST provide a way to update its active `Span`, and MAY provide -convenience methods to manage a `Span`'s lifetime of and the scope in which a -`Span` is active. - Each span has zero or one parent span and zero or more child spans, which represent causally related operations. A tree of related spans comprises a trace. A span is said to be a _root span_ if it does not have a parent. Each From 48f99139c24aeee8e74f23f4cd6ece39cd2ce7ba Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Fri, 9 Aug 2019 16:44:38 -0700 Subject: [PATCH 04/12] Shuffle section on multi-deployment runtime --- specification/api-tracing.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 5c03fb5bdb0..6aee613c0c0 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -109,20 +109,17 @@ Implementations might require the user to specify configuration properties at `Tracer` creation time, or rely on external configuration, e.g. in the case of the provider pattern. -Tracer provider is an internal class used by the global registry -(`OpenTelemetry`) to get a tracer instance. The global registry delegates calls -to the provider every time a tracer instance is requested. This is necessary -for use-cases when a single instrumentation code runs for multiple deployments. +##### Runtimes with multiple deployments/applications -The tracer provider is registered to API usually via language-specific -mechanism, for instance `ServiceLoader` in Java. +Runtimes that support multiple deployments or applications might need to +provide a different `Tracer` instance to each deployment. To support this, -##### Runtime with multiple deployments/applications +the global `Tracer` registry may delegate calls to create new `Tracer`s to a +separate `Provider` component, and the runtime may include its own `Provider` +implementation which returns a different `Tracer` for each deployment. -Application runtimes which support multiple deployments/applications might need -to provide a different tracer instance to each deployment. In this case the -runtime provides its own implementation of provider which returns a different -tracer for each deployment. +`Provider`s are registered with the API via some language-specific mechanism, +for instance the `ServiceLoader` class in Java. ### Tracer operations From a67891b43787109f22ff837cb4ecc0c633c2f983 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Fri, 9 Aug 2019 16:47:43 -0700 Subject: [PATCH 05/12] Less flowery language --- specification/api-tracing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 6aee613c0c0..6e4e01973c9 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -106,8 +106,8 @@ registry of `Tracer`s for such applications. from linked dependencies using the provider pattern. Implementations might require the user to specify configuration properties at -`Tracer` creation time, or rely on external configuration, e.g. in the case of -the provider pattern. +`Tracer` creation time, or rely on external configuration, e.g. when using the +provider pattern. ##### Runtimes with multiple deployments/applications From 5cc2516c4e34282bd9fb23528eea8860d09e4937 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Fri, 9 Aug 2019 16:49:00 -0700 Subject: [PATCH 06/12] Backtick fixes --- specification/api-tracing.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 6e4e01973c9..7eb084a375b 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -130,10 +130,10 @@ The `Tracer` MUST provide methods to: - Set a given `Span` as active The `Tracer` SHOULD allow end users to configure other tracing components that -control how spans are serialized and exported: +control how `Span`s are serialized and exported: -- the binary and text format `Propagator`s used to serialize `Spans` created by the `Tracer` -- the `SpanProcessor`s and `Exporter`s used to export `Spans` created by the `Tracer` +- the binary and text format `Propagator`s used to serialize `Span`s created by the `Tracer` +- the `SpanProcessor`s and `Exporter`s used to export `Span`s created by the `Tracer` When getting the current span, the `Tracer` MUST return a placeholder `Span` with an invalid `SpanContext` if there is no currently active `Span`. @@ -146,12 +146,12 @@ selected. The `Tracer` MUST provide a way to update its active `Span`, and MAY provide convenience methods to manage a `Span`'s lifetime and the scope in which a -`Span` is active. When an active span is finished, the previously-active span -SHOULD be made active. +`Span` is active. When an active `Span` is finished, the previously-active +`Span` SHOULD be made active. -The `Tracer` MUST support recording spans that were created _out of band_, i.e. -not by the tracer itself. For this reason, implementations MUST NOT require -that a `Span`'s start and end timestamps match the wall time when it is +The `Tracer` MUST support recording `Span`s that were created _out of band_, +i.e. not by the tracer itself. For this reason, implementations MUST NOT +require that a `Span`'s start and end timestamps match the wall time when it is created, made active, or finished. The implementation MUST provide no-op binary and text `Propagator`s, which the From 9a780b79577ae84fec909d6c4bbaf5d89947dea8 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Wed, 14 Aug 2019 11:35:03 -0700 Subject: [PATCH 07/12] Apply @songy23's suggestions from PR Co-Authored-By: Yang Song --- specification/api-tracing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 7eb084a375b..b6984082163 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -88,9 +88,9 @@ way of the `Tracer`. The `Tracer` is responsible for tracking the currently active `Span`, and exposes methods for creating and activating new `Span`s. The `Tracer` is -configured with `Propagator`s which support transferring context across process +configured with `Propagator`s which support transferring span context across process boundaries, and `Exporter`s and `SpanProcessor`s which control how spans are -exported to APMs. +exported to APMs and Z pages. `Tracer`s are generally expected to be used as singletons. Implementations SHOULD provide a single global default `Tracer`. @@ -142,7 +142,7 @@ When creating a new `Span`, the `Tracer` MUST allow the caller to specify the new `Span`'s parent in the form of a `Span` or `SpanContext`. The `Tracer` SHOULD create each new `Span` as a child of its active `Span` unless an explicit parent is provided or the option to create a span without a parent is -selected. +selected, or the current active `Span` is invalid. The `Tracer` MUST provide a way to update its active `Span`, and MAY provide convenience methods to manage a `Span`'s lifetime and the scope in which a From 539bad56d230de4f7bd79bbad9feef0296279b6c Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Wed, 14 Aug 2019 11:37:41 -0700 Subject: [PATCH 08/12] Reword tracer config description --- specification/api-tracing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index b6984082163..b97a713bbe9 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -130,7 +130,7 @@ The `Tracer` MUST provide methods to: - Set a given `Span` as active The `Tracer` SHOULD allow end users to configure other tracing components that -control how `Span`s are serialized and exported: +control how `Span`s are passed across process boundaries and exported: - the binary and text format `Propagator`s used to serialize `Span`s created by the `Tracer` - the `SpanProcessor`s and `Exporter`s used to export `Span`s created by the `Tracer` From 48fb1bcbe31852050e194099bfd54c2f5ffda196 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Wed, 14 Aug 2019 11:48:21 -0700 Subject: [PATCH 09/12] Note that SpanProcessor does more than export --- specification/api-tracing.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index b97a713bbe9..207d05cbfbb 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -88,9 +88,10 @@ way of the `Tracer`. The `Tracer` is responsible for tracking the currently active `Span`, and exposes methods for creating and activating new `Span`s. The `Tracer` is -configured with `Propagator`s which support transferring span context across process -boundaries, and `Exporter`s and `SpanProcessor`s which control how spans are -exported to APMs and Z pages. +configured with `Propagator`s which support transferring span context across +process boundaries, `Exporter`s responsible for exporting span data to APMs and +Z pages, and `SpanProcessor`s which affect how spans are exported and allow end +users to extend the export pipeline with custom behavior. `Tracer`s are generally expected to be used as singletons. Implementations SHOULD provide a single global default `Tracer`. From cdacd77d57a903aecd2f694f587a8b73f03bf5b1 Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Fri, 16 Aug 2019 15:43:50 -0700 Subject: [PATCH 10/12] s/set/make/ --- specification/api-tracing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 207d05cbfbb..cd2e7750cd2 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -128,7 +128,7 @@ The `Tracer` MUST provide methods to: - Get the currently active `Span` - Create a new `Span` -- Set a given `Span` as active +- Make a given `Span` as active The `Tracer` SHOULD allow end users to configure other tracing components that control how `Span`s are passed across process boundaries and exported: From e9d77b34d1692eeb9cacdbdf0f35d03dd5aebc3e Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Fri, 16 Aug 2019 15:55:29 -0700 Subject: [PATCH 11/12] Lose refs to exporters, processors --- specification/api-tracing.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index cd2e7750cd2..7069deb0fef 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -89,9 +89,7 @@ way of the `Tracer`. The `Tracer` is responsible for tracking the currently active `Span`, and exposes methods for creating and activating new `Span`s. The `Tracer` is configured with `Propagator`s which support transferring span context across -process boundaries, `Exporter`s responsible for exporting span data to APMs and -Z pages, and `SpanProcessor`s which affect how spans are exported and allow end -users to extend the export pipeline with custom behavior. +process boundaries. `Tracer`s are generally expected to be used as singletons. Implementations SHOULD provide a single global default `Tracer`. @@ -131,10 +129,9 @@ The `Tracer` MUST provide methods to: - Make a given `Span` as active The `Tracer` SHOULD allow end users to configure other tracing components that -control how `Span`s are passed across process boundaries and exported: - -- the binary and text format `Propagator`s used to serialize `Span`s created by the `Tracer` -- the `SpanProcessor`s and `Exporter`s used to export `Span`s created by the `Tracer` +control how `Span`s are passed across process boundaries, inclucding the binary +and text format `Propagator`s used to serialize `Span`s created by the +`Tracer`. When getting the current span, the `Tracer` MUST return a placeholder `Span` with an invalid `SpanContext` if there is no currently active `Span`. From 8e0b5b27b2b61bcf708795b44a358c5a21a3f04e Mon Sep 17 00:00:00 2001 From: Chris Kleinknecht Date: Fri, 16 Aug 2019 15:55:56 -0700 Subject: [PATCH 12/12] Separate span lifetime and activation --- specification/api-tracing.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 7069deb0fef..dd3832f0e4c 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -144,8 +144,10 @@ selected, or the current active `Span` is invalid. The `Tracer` MUST provide a way to update its active `Span`, and MAY provide convenience methods to manage a `Span`'s lifetime and the scope in which a -`Span` is active. When an active `Span` is finished, the previously-active -`Span` SHOULD be made active. +`Span` is active. When an active `Span` is made inactive, the previously-active +`Span` SHOULD be made active. A `Span` maybe finished (i.e. have a non-null end +time) but stil active. A `Span` may be active on one thread after it has been +made inactive on another. The `Tracer` MUST support recording `Span`s that were created _out of band_, i.e. not by the tracer itself. For this reason, implementations MUST NOT