Rename SpanContext to SpanReference. (#1075)

* Rename SpanContext to SpanReference. * More updates. * Update CHANGELOG * Update specification/metrics/api.md Co-authored-by: Christian Neumüller <christian+github@neumueller.me> * Update specification/metrics/api.md Co-authored-by: Christian Neumüller <christian+github@neumueller.me> * Update specification/metrics/api.md Co-authored-by: Christian Neumüller <christian+github@neumueller.me> * Update specification/metrics/api.md Co-authored-by: Christian Neumüller <christian+github@neumueller.me> * Update specification/overview.md Co-authored-by: Christian Neumüller <christian+github@neumueller.me> * Update specification/overview.md Co-authored-by: Christian Neumüller <christian+github@neumueller.me> * Update specification/metrics/api.md Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com> * Add entry to the compliance matrix. * Update specification/overview.md Co-authored-by: Christian Neumüller <christian+github@neumueller.me> Co-authored-by: Christian Neumüller <christian+github@neumueller.me> Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com>
open-telemetry · Oct 14, 2020 · 6647ba3 · 6647ba3
1 parent c115d08
commit 6647ba3
Show file tree

Hide file tree

Showing 8 changed files with 64 additions and 61 deletions.
diff --git 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
@@ -24,15 +24,16 @@ 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         | + | +  | + | +    | +  | +    |   | -  | + | +  |
 |[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/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
@@ -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
@@ -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
@@ -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: