Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rename SpanContext to SpanReference. #1075

Merged
merged 13 commits into from
Oct 14, 2020
Merged

Rename SpanContext to SpanReference. #1075

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
809fb37
Rename SpanContext to SpanReference.
carlosalberto Oct 8, 2020
32d0d88
More updates.
carlosalberto Oct 8, 2020
434fcde
Update CHANGELOG
carlosalberto Oct 8, 2020
674815d
Update specification/metrics/api.md
carlosalberto Oct 11, 2020
8fcf58c
Update specification/metrics/api.md
carlosalberto Oct 11, 2020
b411406
Update specification/metrics/api.md
carlosalberto Oct 11, 2020
a5c2d6b
Update specification/metrics/api.md
carlosalberto Oct 11, 2020
7c5a93c
Update specification/overview.md
carlosalberto Oct 11, 2020
e23cc28
Update specification/overview.md
carlosalberto Oct 11, 2020
1d1be11
Update specification/metrics/api.md
carlosalberto Oct 11, 2020
9b267aa
Merge branch 'master' into rename_spancontext_spanreference
carlosalberto Oct 13, 2020
3e894df
Add entry to the compliance matrix.
carlosalberto Oct 13, 2020
01f145b
Update specification/overview.md
carlosalberto Oct 13, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,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)

Expand Down
5 changes: 3 additions & 2 deletions spec-compliance-matrix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,15 +23,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)|
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved
|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 | + | + | + | + | + | + | + | + | + | + |
Expand Down
4 changes: 2 additions & 2 deletions specification/context/api-propagators.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since we only put Span in Context, should we use Span for this and the next few files?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Oberon00 Perhaps this is appropriate for #1079?

Copy link
Member

@Oberon00 Oberon00 Oct 9, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this would more be a follow-up of #994. I suggested related changes right in this PR as it neatly highlights all usages, but I think you are right that this could be in a separate PR. I don't think it belongs into #1079 though.

- The carrier that holds the propagation fields. For example, an outgoing message or HTTP request.

#### Extract
Expand All @@ -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
Expand Down
10 changes: 5 additions & 5 deletions specification/metrics/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand Down
16 changes: 8 additions & 8 deletions specification/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a suggestion:

Suggested change
Represents all the information that identifies **Span** in the **Trace** and
Represents all the information that is required to reference a **Span** in the **Trace** unambiguously and efficiently and

E.g. in Dynatrace we could reference the span with just span+trace ID but require some routing info in the trace state to do so efficiently. Not sure if this is generally applicable enough.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Definitely something that can be done in a another PR, specially because this was not even touched in this PR.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this one is more related to that PR, as the name change reflects a change in the understanding of that type. But I'm fine with doing this in a follow-up too (I already approved)

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
**SpanReference** contains the tracing identifiers and the options that are
**SpanReference** contains the tracing identifiers, tracestate and the options that are

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same, the lack of trace state is not related to this PR.

propagated from parent to child **Spans**.

- **TraceId** is the identifier for a trace. It is worldwide unique with
Expand All @@ -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.
Expand Down Expand Up @@ -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:
Expand Down
Loading