Revert "Rename SpanContext to SpanReference. (#1075)" (#1127)

CHANGELOG.md

@@ -125,8 +125,6 @@ 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)
 

spec-compliance-matrix.md

@@ -23,18 +23,17 @@ status of the feature is not known.
 |Create a new Span                             | + | +  | + | +    | +  | +    | + | +  | + | +  |
 |Get active Span                               | + | +  | + | +    | +  | +    | + | +  | + | +  |
 |Mark Span active                              | + | +  | + | +    | +  | +    | + | +  | - | -  |
-|Safe for concurrent calls                     | + | +  | + | +    | +  | +    | + | +  | + | +  |
-|[SpanReference](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#spanreference)|
-|Use SpanReference instead of SpanContext      |   |    |   |      |    |      |   |    |   |    |
+|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)|
 |IsValid                                       | + | +  | + | +    | +  | +    | + | +  | + | +  |
 |IsRemote                                      | - | +  | + | +    | +  | +    | + | +  | + | +  |
 |Conforms to the W3C TraceContext spec         | + | +  | + | +    | +  | +    |   | -  | + | +  |
 |[Span](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#span)|
 |Create root span                              | + | +  | + | +    | +  | +    | + | +  | + | +  |
 |Create with default parent (active span)      | + | +  | + | +    | +  | +    | + | +  | + | +  |
 |Create with parent from Context               | + | +  | + | +    | +  | +    | + | +  | + | +  |
-|No explicit parent Span/SpanReference allowed |   | +  |   | +    |    |      |   |    |   |    |
-|SpanProcessor.OnStart receives parent Context |   |    |   | +    |    |      |   |    |   |    |
+|No explicit parent Span/SpanContext allowed   |   | +  |   |      |    |      |   |    |   |    |
+|SpanProcessor.OnStart receives parent Context |   |    |   |      |    |      |   |    |   |    |
 |UpdateName                                    | + | +  | + | +    | +  | +    | + | +  | - | +  |
 |User-defined start timestamp                  | + | +  | + | +    | +  | +    | + | +  | + | +  |
 |End                                           | + | +  | + | +    | +  | +    | + | +  | + | +  |

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
-`SpanReference`, `Baggage` or another cross-cutting concern context.
+`SpanContext`, `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 `SpanReference`,
+containing the extracted value, which can be a `SpanContext`,
 `Baggage` or another cross-cutting concern context.
 
 ## TextMap Propagator

specification/overview.md

@@ -11,7 +11,7 @@ Table of Contents
 - [Distributed Tracing](#distributed-tracing)
   * [Trace](#trace)
   * [Span](#span)
-  * [SpanReference](#spanreference)
+  * [SpanContext](#spancontext)
   * [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 **SpanReference** of those related **Spans**).
-- **SpanReference** information required to reference a Span. See below.
+  (via the **SpanContext** of those related **Spans**).
+- **SpanContext** information required to reference a Span. See below.
 
-### SpanReference
+### SpanContext
 
 Represents all the information that identifies **Span** in the **Trace** and
 MUST be propagated to child Spans and across process boundaries. A
-**SpanReference** contains the tracing identifiers and the options that are
+**SpanContext** 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,7 +126,7 @@ propagated from parent to child **Spans**.
 ### Links between spans
 
 A **Span** may be linked to zero or more other **Spans** (defined by
-**SpanReference**) that are causally related. **Links** can point to
+**SpanContext**) 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
@@ -280,7 +280,7 @@ See the [Context](context/context.md)
 ## Propagators
 
 OpenTelemetry uses `Propagators` to serialize and deserialize cross-cutting concern values
-such as `Span`s (usually only the `SpanReference` portion) and `Baggage`. Different `Propagator` types define the restrictions
+such as `Span`s (usually only the `SpanContext` 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:

specification/trace/api.md

@@ -14,7 +14,7 @@ Table of Contents
 * [Context Interaction](#context-interaction)
 * [Tracer](#tracer)
   * [Tracer operations](#tracer-operations)
-* [SpanReference](#spanreference)
+* [SpanContext](#spancontext)
   * [Retrieving the TraceId and SpanId](#retrieving-the-traceid-and-spanid)
   * [IsValid](#isvalid)
   * [IsRemote](#isremote)
@@ -167,12 +167,12 @@ The `Tracer` MUST provide functions to:
 
 - [Create a new `Span`](#span-creation) (see the section on `Span`)
 
-## SpanReference
+## SpanContext
 
-A `SpanReference` represents the portion of a `Span` which must be serialized and
-propagated along side of a distributed context. `SpanReference`s are immutable.
+A `SpanContext` represents the portion of a `Span` which must be serialized and
+propagated along side of a distributed context. `SpanContext`s are immutable.
 
-The OpenTelemetry `SpanReference` representation conforms to the [W3C TraceContext
+The OpenTelemetry `SpanContext` 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.
@@ -192,8 +192,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 `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
+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
 overridable.
 
 ### Retrieving the TraceId and SpanId
@@ -210,19 +210,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 SpanReference has a
+An API called `IsValid`, that returns a boolean value, which is `true` if the SpanContext 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 SpanReference was
+An API called `IsRemote`, that returns a boolean value, which is `true` if the SpanContext was
 propagated from a remote parent, MUST be provided.
-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.
+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.
 
 ### TraceState
 
-`TraceState` is a part of [`SpanReference`](./api.md#spanreference), represented by an immutable list of string key/value pairs and
+`TraceState` is a part of [`SpanContext`](./api.md#spancontext), 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`:
 
@@ -238,9 +238,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 `SpanReference` is immutable, it is not possible to update `SpanReference` with a new `TraceState`.
+Please note, since `SpanContext` is immutable, it is not possible to update `SpanContext` with a new `TraceState`.
 Such changes then make sense only right before
-[`SpanReference` propagation](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/context/api-propagators.md)
+[`SpanContext` 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.
 
@@ -254,9 +254,9 @@ the entire operation and, optionally, one or more sub-spans for its sub-operatio
 `Span`s encapsulate:
 
 - The span name
-- An immutable [`SpanReference`](#spanreference) that uniquely identifies the
+- An immutable [`SpanContext`](#spancontext) that uniquely identifies the
   `Span`
-- A parent span in the form of a [`Span`](#span), [`SpanReference`](#spanreference),
+- A parent span in the form of a [`Span`](#span), [`SpanContext`](#spancontext),
   or null
 - A [`SpanKind`](#spankind)
 - A start timestamp
@@ -313,7 +313,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 `SpanReference`.
+attributes besides its `SpanContext`.
 
 Vendors may implement the `Span` interface to effect vendor-specific logic.
 However, alternative implementations MUST NOT allow callers to create `Span`s
@@ -333,7 +333,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 `SpanReference` as parent, only a full `Context`.
+  This API MUST NOT accept a `Span` or `SpanContext` 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).
@@ -362,7 +362,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 `SpanReference` so `Span` creation knows if the
+`IsRemote` to true on a parent `SpanContext` so `Span` creation knows if the
 parent is remote.
 
 Any span that is created MUST also be ended.
@@ -377,7 +377,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 `SpanReference` cannot be set as active in a `Context` directly, but through the use
+A `SpanContext` 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.
 
@@ -390,14 +390,14 @@ Span creation.
 
 A `Link` is structurally defined by the following properties:
 
-- `SpanReference` of the `Span` to link to.
+- `SpanContext` 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 `SpanReference` of
+  arguments. This MAY be called `AddLink`. This API takes the `SpanContext` 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.
@@ -406,14 +406,14 @@ Links SHOULD preserve the order in which they're set.
 
 ### Span operations
 
-With the exception of the function to retrieve the `Span`'s `SpanReference` and
+With the exception of the function to retrieve the `Span`'s `SpanContext` 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 `SpanReference` for the given `Span`. The returned value
+- An API that returns the `SpanContext` 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`.
 
@@ -434,7 +434,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
-[SpanReference](#spanreference)).
+[SpanContext](#spancontext)).
 
 This flag may be `true` despite the entire trace being sampled out. This
 allows to record and process information about the individual Span without
@@ -639,15 +639,15 @@ calling of corresponding API.
 
 ### Propagated Span creation
 
-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`
+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`
 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 `SpanReference`.
+- `GetContext()` MUST return the wrapped `SpanContext`.
 - `IsRecording` MUST return `false` to signal that events, attributes and other elements
   are not being recorded, i.e. they are being dropped.
 
@@ -680,7 +680,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 SpanReference for a
+new Span prior to extracting and serializing the SpanContext for a
 remote call.
 
 These are the possible SpanKinds:
@@ -742,13 +742,13 @@ for how propagators are to be distributed.
 
 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 `SpanReference`:
-The API MUST create a [Propagated Span](#propagated-span-creation) with the `SpanReference`
+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`
 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 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`
+(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`
 will be propagated through to any child span and ultimately also `Inject`,
-but that no new `SpanReference`s will be created.
+but that no new `SpanContext`s will be created.