From 6647ba3552cfda5e37afe91b8b958c8eb29cda09 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 14 Oct 2020 17:40:18 +0200 Subject: [PATCH] Rename SpanContext to SpanReference. (#1075) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Rename SpanContext to SpanReference. * More updates. * Update CHANGELOG * Update specification/metrics/api.md Co-authored-by: Christian Neumüller * Update specification/metrics/api.md Co-authored-by: Christian Neumüller * Update specification/metrics/api.md Co-authored-by: Christian Neumüller * Update specification/metrics/api.md Co-authored-by: Christian Neumüller * Update specification/overview.md Co-authored-by: Christian Neumüller * Update specification/overview.md Co-authored-by: Christian Neumüller * Update specification/metrics/api.md Co-authored-by: Armin Ruech * Add entry to the compliance matrix. * Update specification/overview.md Co-authored-by: Christian Neumüller Co-authored-by: Christian Neumüller Co-authored-by: Armin Ruech --- CHANGELOG.md | 2 + spec-compliance-matrix.md | 5 +- specification/context/api-propagators.md | 4 +- specification/metrics/api.md | 10 +-- specification/overview.md | 16 ++--- specification/trace/api.md | 68 +++++++++---------- specification/trace/sdk.md | 18 ++--- .../trace/semantic_conventions/messaging.md | 2 +- 8 files changed, 64 insertions(+), 61 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3a882d2fbf1..da51a64ba8c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -112,6 +112,8 @@ Updates: ([#993](https://github.com/open-telemetry/opentelemetry-specification/pull/993)) - Trace API: Clarifications for `Span.End`, e.g. IsRecording becomes false after End ([#1011](https://github.com/open-telemetry/opentelemetry-specification/pull/1011)) +- Rename SpanContext to SpanReference + ([#1075](https://github.com/open-telemetry/opentelemetry-specification/pull/1075)) ## v0.6.0 (07-01-2020) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 3f7f2ab3dc4..ead8b51d4fe 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -24,7 +24,8 @@ status of the feature is not known. |Get active Span | + | + | + | + | + | + | + | + | + | + | |Mark Span active | + | + | + | + | + | + | + | + | - | - | |Safe for concurrent calls | + | + | + | [-](https://github.com/open-telemetry/opentelemetry-python/issues/1156) | + | + | + | + | + | + | -|[SpanContext](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#spancontext)| +|[SpanReference](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#spanreference)| +|Use SpanReference instead of SpanContext | | | | | | | | | | | |IsValid | + | + | + | + | + | + | + | + | + | + | |IsRemote | - | + | + | + | + | + | + | + | + | + | |Conforms to the W3C TraceContext spec | + | + | + | + | + | + | | - | + | + | @@ -32,7 +33,7 @@ status of the feature is not known. |Create root span | + | + | + | + | + | + | + | + | + | + | |Create with default parent (active span) | + | + | + | + | + | + | + | + | + | + | |Create with parent from Context | + | + | + | + | + | + | + | + | + | + | -|No explicit parent Span/SpanContext allowed | | + | | | | | | | | | +|No explicit parent Span/SpanReference allowed | | + | | | | | | | | | |SpanProcessor.OnStart receives parent Context | | | | | | | | | | | |UpdateName | + | + | + | + | + | + | + | + | - | + | |User-defined start timestamp | + | + | + | + | + | + | + | + | + | + | diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 47967788349..c8db6b945ad 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -76,7 +76,7 @@ Injects the value into a carrier. For example, into the headers of an HTTP reque Required arguments: - A `Context`. The Propagator MUST retrieve the appropriate value from the `Context` first, such as -`SpanContext`, `Baggage` or another cross-cutting concern context. +`SpanReference`, `Baggage` or another cross-cutting concern context. - The carrier that holds the propagation fields. For example, an outgoing message or HTTP request. #### Extract @@ -93,7 +93,7 @@ Required arguments: - The carrier that holds the propagation fields. For example, an incoming message or http response. Returns a new `Context` derived from the `Context` passed as argument, -containing the extracted value, which can be a `SpanContext`, +containing the extracted value, which can be a `SpanReference`, `Baggage` or another cross-cutting concern context. ## TextMap Propagator diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 41a48f85a0e..570207732f6 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -148,7 +148,7 @@ which is the user-facing entry point to the SDK. Instruments are classified in several ways that distinguish them from one another. -1. Synchronicity: A synchronous instrument is called by the user in a distributed [Context](../context/context.md) (i.e., Span context, Baggage). An asynchronous instrument is called by the SDK once per collection interval, lacking a Context. +1. Synchronicity: A synchronous instrument is called by the user in a distributed [Context](../context/context.md) (i.e., with associated Span, Baggage, etc.). An asynchronous instrument is called by the SDK once per collection interval, lacking a Context. 2. Adding vs. Grouping: An adding instrument is one that records adding measurements, as opposed to a grouping instrument as described above. 3. Monotonicity: A monotonic instrument is an adding instrument, where the progression of sums is non-decreasing. Monotonic instruments are useful for monitoring rate information. @@ -165,7 +165,7 @@ are synchronous, adding, and/or monotonic. | ValueObserver | No | No | No | The synchronous instruments are useful for measurements that are -gathered in a distributed [Context](../context/context.md) (i.e., Span context, Baggage). The asynchronous instruments are +gathered in a distributed [Context](../context/context.md) (i.e., with associated Span, Baggage, etc.). The asynchronous instruments are useful when measurements are expensive, therefore should be gathered periodically. Read more [characteristics of synchronous and asynchronous instruments](#synchronous-and-asynchronous-instruments-compared) below. @@ -323,7 +323,7 @@ consist of: - [resources](../resource/sdk.md) associated with the SDK at startup. Synchronous events have one additional property, the distributed -[Context](../context/context.md) (i.e., Span context, Baggage) +[Context](../context/context.md) (containing Span, Baggage, etc.) that was active at the time. ## Meter provider @@ -421,7 +421,7 @@ libraries may be written to generate this metric. ### Synchronous and asynchronous instruments compared Synchronous instruments are called inside a request, meaning they -have an associated distributed [Context](../context/context.md) (i.e., Span context, Baggage). Multiple metric events may occur for a +have an associated distributed [Context](../context/context.md) (with Span, Baggage, etc.). Multiple metric events may occur for a synchronous instrument within a given collection interval. Asynchronous instruments are reported by a callback, once per @@ -944,7 +944,7 @@ convention. Synchronous measurements are implicitly associated with the distributed [Context](../context/context.md) at runtime, which may -include a Span context and Baggage entries. The Metric SDK may use +include a Span and Baggage entries. The Metric SDK may use this information in many ways, but one feature is of particular interest in OpenTelemetry. diff --git a/specification/overview.md b/specification/overview.md index b3576ac1268..adc74a31727 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -11,7 +11,7 @@ Table of Contents - [Distributed Tracing](#distributed-tracing) * [Trace](#trace) * [Span](#span) - * [SpanContext](#spancontext) + * [SpanReference](#spanreference) * [Links between spans](#links-between-spans) - [Metrics](#metrics) * [Recording raw measurements](#recording-raw-measurements) @@ -96,14 +96,14 @@ Each **Span** encapsulates the following state: - A set of zero or more **Events**, each of which is itself a tuple (timestamp, name, [**Attributes**](./common/common.md#attributes)). The name must be strings. - Parent's **Span** identifier. - [**Links**](#links-between-spans) to zero or more causally-related **Spans** - (via the **SpanContext** of those related **Spans**). -- **SpanContext** identification of a Span. See below. + (via the **SpanReference** of those related **Spans**). +- **SpanReference** information required to reference a Span. See below. -### SpanContext +### SpanReference Represents all the information that identifies **Span** in the **Trace** and MUST be propagated to child Spans and across process boundaries. A -**SpanContext** contains the tracing identifiers and the options that are +**SpanReference** contains the tracing identifiers and the options that are propagated from parent to child **Spans**. - **TraceId** is the identifier for a trace. It is worldwide unique with @@ -126,8 +126,8 @@ propagated from parent to child **Spans**. ### Links between spans A **Span** may be linked to zero or more other **Spans** (defined by -**SpanContext**) that are causally related. **Links** can point to -**SpanContexts** inside a single **Trace** or across different **Traces**. +**SpanReference**) that are causally related. **Links** can point to +**Spans** inside a single **Trace** or across different **Traces**. **Links** can be used to represent batched operations where a **Span** was initiated by multiple initiating **Spans**, each representing a single incoming item being processed in the batch. @@ -280,7 +280,7 @@ See the [Context](context/context.md) ## Propagators OpenTelemetry uses `Propagators` to serialize and deserialize cross-cutting concern values -such as `SpanContext` and `Baggage`. Different `Propagator` types define the restrictions +such as `Span`s (usually only the `SpanReference` portion) and `Baggage`. Different `Propagator` types define the restrictions imposed by a specific transport and bound to a data type. The Propagators API currently defines one `Propagator` type: diff --git a/specification/trace/api.md b/specification/trace/api.md index 3fa4a46852e..da128b12b5d 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -14,7 +14,7 @@ Table of Contents * [Tracing Context Utilities](#tracing-context-utilities) * [Tracer](#tracer) * [Tracer operations](#tracer-operations) -* [SpanContext](#spancontext) +* [SpanReference](#spanreference) * [Retrieving the TraceId and SpanId](#retrieving-the-traceid-and-spanid) * [IsValid](#isvalid) * [IsRemote](#isremote) @@ -163,12 +163,12 @@ The `Tracer` MAY provide functions to: These functions MUST delegate to the `Tracing Context Utilities`. -## SpanContext +## SpanReference -A `SpanContext` represents the portion of a `Span` which must be serialized and -propagated along side of a distributed context. `SpanContext`s are immutable. +A `SpanReference` represents the portion of a `Span` which must be serialized and +propagated along side of a distributed context. `SpanReference`s are immutable. -The OpenTelemetry `SpanContext` representation conforms to the [W3C TraceContext +The OpenTelemetry `SpanReference` representation conforms to the [W3C TraceContext specification](https://www.w3.org/TR/trace-context/). It contains two identifiers - a `TraceId` and a `SpanId` - along with a set of common `TraceFlags` and system-specific `TraceState` values. @@ -188,8 +188,8 @@ of key-value pairs. TraceState allows multiple tracing systems to participate in the same trace. It is fully described in the [W3C Trace Context specification](https://www.w3.org/TR/trace-context/#tracestate-header). -The API MUST implement methods to create a `SpanContext`. These methods SHOULD be the only way to -create a `SpanContext`. This functionality MUST be fully implemented in the API, and SHOULD NOT be +The API MUST implement methods to create a `SpanReference`. These methods SHOULD be the only way to +create a `SpanReference`. This functionality MUST be fully implemented in the API, and SHOULD NOT be overridable. ### Retrieving the TraceId and SpanId @@ -206,19 +206,19 @@ The API should not expose details about how they are internally stored. ### IsValid -An API called `IsValid`, that returns a boolean value, which is `true` if the SpanContext has a +An API called `IsValid`, that returns a boolean value, which is `true` if the SpanReference has a non-zero TraceID and a non-zero SpanID, MUST be provided. ### IsRemote -An API called `IsRemote`, that returns a boolean value, which is `true` if the SpanContext was +An API called `IsRemote`, that returns a boolean value, which is `true` if the SpanReference was propagated from a remote parent, MUST be provided. -When extracting a `SpanContext` through the [Propagators API](../context/api-propagators.md#propagators-api), -`IsRemote` MUST return true, whereas for the SpanContext of any child spans it MUST return false. +When extracting a `SpanReference` through the [Propagators API](../context/api-propagators.md#propagators-api), +`IsRemote` MUST return true, whereas for the SpanReference of any child spans it MUST return false. ### TraceState -`TraceState` is a part of [`SpanContext`](./api.md#spancontext), represented by an immutable list of string key/value pairs and +`TraceState` is a part of [`SpanReference`](./api.md#spanreference), represented by an immutable list of string key/value pairs and formally defined by the [W3C Trace Context specification](https://www.w3.org/TR/trace-context/#tracestate-header). Tracing API MUST provide at least the following operations on `TraceState`: @@ -234,9 +234,9 @@ Every mutating operations MUST validate input parameters. If invalid value is passed the operation MUST NOT return `TraceState` containing invalid data and MUST follow the [general error handling guidelines](../error-handling.md) (e.g. it usually must not return null or throw an exception). -Please note, since `SpanContext` is immutable, it is not possible to update `SpanContext` with a new `TraceState`. +Please note, since `SpanReference` is immutable, it is not possible to update `SpanReference` with a new `TraceState`. Such changes then make sense only right before -[`SpanContext` propagation](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/context/api-propagators.md) +[`SpanReference` propagation](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/context/api-propagators.md) or [telemetry data exporting](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk.md#span-exporter). In both cases, `Propagators` and `SpanExporters` may create a modified `TraceState` copy before serializing it to the wire. @@ -250,9 +250,9 @@ the entire operation and, optionally, one or more sub-spans for its sub-operatio `Span`s encapsulate: - The span name -- An immutable [`SpanContext`](#spancontext) that uniquely identifies the +- An immutable [`SpanReference`](#spanreference) that uniquely identifies the `Span` -- A parent span in the form of a [`Span`](#span), [`SpanContext`](#spancontext), +- A parent span in the form of a [`Span`](#span), [`SpanReference`](#spanreference), or null - A [`SpanKind`](#spankind) - A start timestamp @@ -309,7 +309,7 @@ MUST NOT be changed after the `Span`'s end time has been set. `Span`s are not meant to be used to propagate information within a process. To prevent misuse, implementations SHOULD NOT provide access to a `Span`'s -attributes besides its `SpanContext`. +attributes besides its `SpanReference`. Vendors may implement the `Span` interface to effect vendor-specific logic. However, alternative implementations MUST NOT allow callers to create `Span`s @@ -329,7 +329,7 @@ The API MUST accept the following parameters: - The parent `Context` or an indication that the new `Span` should be a root `Span`. The API MAY also have an option for implicitly using the current Context as parent as a default behavior. - This API MUST NOT accept a `Span` or `SpanContext` as parent, only a full `Context`. + This API MUST NOT accept a `Span` or `SpanReference` as parent, only a full `Context`. The semantic parent of the Span MUST be determined according to the rules described in [Determining the Parent Span from a Context](#determining-the-parent-span-from-a-context). @@ -358,7 +358,7 @@ Also, the child span MUST inherit all `TraceState` values of its parent by defau 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 +`IsRemote` to true on a parent `SpanReference` so `Span` creation knows if the parent is remote. Any span that is created MUST also be ended. @@ -373,7 +373,7 @@ When a new `Span` is created from a `Context`, the `Context` may contain a `Span representing the currently active instance, and will be used as parent. If there is no `Span` in the `Context`, the newly created `Span` will be a root span. -A `SpanContext` cannot be set as active in a `Context` directly, but through the use +A `SpanReference` cannot be set as active in a `Context` directly, but through the use of a [Propagated Span](#propagated-span-creation) wrapping it. For example, a `Propagator` performing context extraction may need this. @@ -386,14 +386,14 @@ Span creation. A `Link` is structurally defined by the following properties: -- `SpanContext` of the `Span` to link to. +- `SpanReference` of the `Span` to link to. - Zero or more [`Attributes`](../common/common.md#attributes) further describing the link. The Span creation API MUST provide: - An API to record a single `Link` where the `Link` properties are passed as - arguments. This MAY be called `AddLink`. This API takes the `SpanContext` of + arguments. This MAY be called `AddLink`. This API takes the `SpanReference` of the `Span` to link to and optional `Attributes`, either as individual parameters or as an immutable object encapsulating them, whichever is most appropriate for the language. @@ -402,14 +402,14 @@ Links SHOULD preserve the order in which they're set. ### Span operations -With the exception of the function to retrieve the `Span`'s `SpanContext` and +With the exception of the function to retrieve the `Span`'s `SpanReference` and recording status, none of the below may be called after the `Span` is finished. #### Get Context The Span interface MUST provide: -- An API that returns the `SpanContext` for the given `Span`. The returned value +- An API that returns the `SpanReference` for the given `Span`. The returned value may be used even after the `Span` is finished. The returned value MUST be the same for the entire Span lifetime. This MAY be called `GetContext`. @@ -430,7 +430,7 @@ This flag SHOULD be used to avoid expensive computations of a Span attributes or events in case when a Span is definitely not recorded. Note that any child span's recording is determined independently from the value of this flag (typically based on the `sampled` flag of a `TraceFlag` on -[SpanContext](#spancontext)). +[SpanReference](#spanreference)). This flag may be `true` despite the entire trace being sampled out. This allows to record and process information about the individual Span without @@ -635,15 +635,15 @@ calling of corresponding API. ### Propagated Span creation -The API MUST provide an operation for wrapping a `SpanContext` with an object -implementing the `Span` interface. This is done in order to expose a `SpanContext` +The API MUST provide an operation for wrapping a `SpanReference` with an object +implementing the `Span` interface. This is done in order to expose a `SpanReference` as a `Span` in operations such as in-process `Span` propagation. If a new type is required for supporting this operation, it SHOULD be named `PropagatedSpan`. The behavior is defined as follows: -- `GetContext()` MUST return the wrapped `SpanContext`. +- `GetContext()` MUST return the wrapped `SpanReference`. - `IsRecording` MUST return `false` to signal that events, attributes and other elements are not being recorded, i.e. they are being dropped. @@ -676,7 +676,7 @@ In order for `SpanKind` to be meaningful, callers should arrange that a single Span does not serve more than one purpose. For example, a server-side span should not be used directly as the parent of another remote span. As a simple guideline, instrumentation should create a -new Span prior to extracting and serializing the span context for a +new Span prior to extracting and serializing the SpanReference for a remote call. These are the possible SpanKinds: @@ -735,13 +735,13 @@ The API layer MAY include the following `Propagator`s: In general, in the absence of an installed SDK, the Trace API is a "no-op" API. This means that operations on a Tracer, or on Spans, should have no side effects and do nothing. However, there -is one important exception to this general rule, and that is related to propagation of a `SpanContext`: -The API MUST create a [Propagated Span](#propagated-span-creation) with the `SpanContext` +is one important exception to this general rule, and that is related to propagation of a `SpanReference`: +The API MUST create a [Propagated Span](#propagated-span-creation) with the `SpanReference` that is in the `Span` in the parent `Context` (whether explicitly given or implicit current) or, if the parent is a Propagated Span (which it usually always is if no SDK is present), it MAY return the same parent Propagated Span instance back from the creation method. If the parent `Context` contains no `Span`, an empty Propagated Span MUST be returned instead -(i.e., having a SpanContext with all-zero Span and Trace IDs, empty Tracestate, and unsampled TraceFlags). -This means that a `SpanContext` that has been provided by a configured `Propagator` +(i.e., having a SpanReference with all-zero Span and Trace IDs, empty Tracestate, and unsampled TraceFlags). +This means that a `SpanReference` that has been provided by a configured `Propagator` will be propagated through to any child span and ultimately also `Inject`, -but that no new `SpanContext`s will be created. +but that no new `SpanReference`s will be created. diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 0d6801d152a..09451c1a7a1 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -30,8 +30,8 @@ The OpenTelemetry API has two properties responsible for the data collection: Processor](#span-processor) MUST receive only those spans which have this field set to `true`. However, [Span Exporter](#span-exporter) SHOULD NOT receive them unless the `Sampled` flag was also set. -* `Sampled` flag in `TraceFlags` on `SpanContext`. This flag is propagated via - the `SpanContext` to child Spans. For more details see the [W3C Trace Context +* `Sampled` flag in `TraceFlags` on `SpanReference`. This flag is propagated via + the `SpanReference` to child Spans. For more details see the [W3C Trace Context specification](https://www.w3.org/TR/trace-context/#sampled-flag). This flag indicates that the `Span` has been `sampled` and will be exported. [Span Exporters](#span-exporter) MUST receive those spans which have `Sampled` flag set to true and they SHOULD NOT receive the ones @@ -78,9 +78,9 @@ Returns the sampling Decision for a `Span` to be created. **Required arguments:** -* Parent `SpanContext`. May be invalid to indicate a root span. +* Parent `SpanReference`. May be invalid to indicate a root span. * `TraceId` of the `Span` to be created. - If the parent `SpanContext` contains a valid `TraceId`, they MUST always match. + If the parent `SpanReference` contains a valid `TraceId`, they MUST always match. * Name of the `Span` to be created. * `SpanKind` of the `Span` to be created. * Initial set of `Attributes` of the `Span` to be created. @@ -100,7 +100,7 @@ It produces an output called `SamplingResult` which contains: * A set of span Attributes that will also be added to the `Span`. The returned object must be immutable (multiple calls may return different immutable objects). * A `Tracestate` that will be associated with the `Span` through the new - `SpanContext`. + `SpanReference`. If the sampler returns an empty `Tracestate` here, the `Tracestate` will be cleared, so samplers SHOULD normally return the passed-in `Tracestate` if they do not intend to change it. @@ -156,10 +156,10 @@ still be sampled and extra traces will be sampled on the backend only. * This is a composite sampler. `ParentBased` helps distinguished between the following cases: * No parent (root span). - * Remote parent (`SpanContext.IsRemote() == true`) with `SampledFlag` equals `true` - * Remote parent (`SpanContext.IsRemote() == true`) with `SampledFlag` equals `false` - * Local parent (`SpanContext.IsRemote() == false`) with `SampledFlag` equals `true` - * Local parent (`SpanContext.IsRemote() == false`) with `SampledFlag` equals `false` + * Remote parent (`SpanReference.IsRemote() == true`) with `SampledFlag` equals `true` + * Remote parent (`SpanReference.IsRemote() == true`) with `SampledFlag` equals `false` + * Local parent (`SpanReference.IsRemote() == false`) with `SampledFlag` equals `true` + * Local parent (`SpanReference.IsRemote() == false`) with `SampledFlag` equals `false` Required parameters: diff --git a/specification/trace/semantic_conventions/messaging.md b/specification/trace/semantic_conventions/messaging.md index b133f5929dc..ab2428bc3a1 100644 --- a/specification/trace/semantic_conventions/messaging.md +++ b/specification/trace/semantic_conventions/messaging.md @@ -241,7 +241,7 @@ Given is a process P, that sends two messages to a queue Q on messaging system M Since each span can only have one parent, C3 should not choose a random parent out of C1 and C2, but rather rely on the implicitly selected parent as defined by the [tracing API spec](../api.md). Similarly, only one value can be set as `message_id`, so C3 cannot report both `a1` and `a2` and therefore attribute is left out. Depending on the implementation, the producing spans might still be available in the meta data of the messages and should be added to C3 as links. -The client library or application could also add the receiver span's span context to the data structure it returns for each message. In this case, C3 could also add links to the receiver spans C1 and C2. +The client library or application could also add the receiver span's SpanReference to the data structure it returns for each message. In this case, C3 could also add links to the receiver spans C1 and C2. The status of the batch processing span is selected by the application. Depending on the semantics of the operation. A span status `Ok` could, for example, be set only if all messages or if just at least one were properly processed.