diff --git a/CHANGELOG.md b/CHANGELOG.md index 09f79356db7..8de6d0fc0c6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,9 @@ release. ### Traces +- Add a new AddLink() operation to Span (experimental). + ([#3678](https://github.com/open-telemetry/opentelemetry-specification/pull/3678)) + ### Metrics ### Logs diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 2dca0bfe514..f557bf621a3 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -67,6 +67,7 @@ formats is required. Implementing more than one format is optional. | Unicode support for keys and string values | | + | + | + | + | + | + | + | + | + | + | + | | [Span linking](specification/trace/api.md#specifying-links) | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | | Links can be recorded on span creation | | + | + | | + | + | + | + | + | + | + | | +| Links can be recorded after span creation | | | | | | | | | | | | | | Links order is preserved | | + | + | | + | + | + | + | + | + | + | | | [Span events](specification/trace/api.md#add-events) | | | | | | | | | | | | | | AddEvent | | + | + | + | + | + | + | + | + | + | + | + | diff --git a/specification/common/README.md b/specification/common/README.md index 239bdf2014a..1f17536bb64 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -123,7 +123,7 @@ at this time, as discussed in [data points](../metrics/data-model.md#metric-points), [Spans](../trace/api.md#set-attributes), Span [Events](../trace/api.md#add-events), Span -[Links](../trace/api.md#specifying-links) and +[Links](../trace/api.md#link) and [Log Records](../logs/data-model.md) may contain a collection of attributes. The keys in each such collection are unique, i.e. there MUST NOT exist more than one key-value pair with the same key. The enforcement of uniqueness may be performed diff --git a/specification/compatibility/opencensus.md b/specification/compatibility/opencensus.md index 390935d427b..ea271517e93 100644 --- a/specification/compatibility/opencensus.md +++ b/specification/compatibility/opencensus.md @@ -180,7 +180,7 @@ using the OpenCensus <-> OpenTelemetry bridge. This leads to some issues with OpenCensus APIs that allowed flexible specification of parent spans post-initialization. 2. Links added to spans after the spans are created. This is [not supported in - OpenTelemetry](../trace/api.md#specifying-links), therefore OpenCensus spans + OpenTelemetry](../trace/api.md#link), therefore OpenCensus spans that have links added to them after creation will be mapped to OpenTelemetry spans without the links. 3. OpenTelemetry specifies that samplers are diff --git a/specification/compatibility/opentracing.md b/specification/compatibility/opentracing.md index b75547b8577..b76a5363cba 100644 --- a/specification/compatibility/opentracing.md +++ b/specification/compatibility/opentracing.md @@ -544,7 +544,7 @@ OpenTracing defines two types of references: OpenTelemetry does not define strict equivalent semantics for these references. These reference types must not be confused with the -[Link](../trace/api.md#specifying-links) functionality. This information +[Link](../trace/api.md#link) functionality. This information is however preserved as the `opentracing.ref_type` attribute. ## In process Propagation exceptions diff --git a/specification/trace/api.md b/specification/trace/api.md index 425eff9d822..7cc1901ae74 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -4,7 +4,7 @@ linkTitle: API # Tracing API -**Status**: [Stable, Feature-freeze](../document-status.md) +**Status**: [Stable, Feature-freeze](../document-status.md), except where otherwise specified
Table of Contents @@ -35,6 +35,7 @@ linkTitle: API + [IsRecording](#isrecording) + [Set Attributes](#set-attributes) + [Add Events](#add-events) + + [Add Link](#add-link) + [Set Status](#set-status) + [UpdateName](#updatename) + [End](#end) @@ -42,6 +43,7 @@ linkTitle: API * [Span lifetime](#span-lifetime) * [Wrapping a SpanContext in a Span](#wrapping-a-spancontext-in-a-span) - [SpanKind](#spankind) +- [Link](#link) - [Concurrency](#concurrency) - [Included Propagators](#included-propagators) - [Behavior of the API in the absence of an installed SDK](#behavior-of-the-api-in-the-absence-of-an-installed-sdk) @@ -300,7 +302,7 @@ the entire operation and, optionally, one or more sub-spans for its sub-operatio - A start timestamp - An end timestamp - [`Attributes`](../common/README.md#attribute) -- A list of [`Link`s](#specifying-links) to other `Span`s +- A list of [`Link`s](#link) to other `Span`s - A list of timestamped [`Event`s](#add-events) - A [`Status`](#set-status). @@ -386,7 +388,7 @@ The API MUST accept the following parameters: to calling `SetAttribute` later, as samplers can only consider information already present during span creation. -- `Link`s - an ordered sequence of Links, see API definition [here](#specifying-links). +- `Link`s - an ordered sequence of Links, see [API definition](#link). - `Start timestamp`, default to current time. This argument SHOULD only be set when span creation time has already passed. If API is called at a moment of a Span logical start, API user MUST NOT explicitly set this argument. @@ -423,27 +425,10 @@ For example, a `Propagator` performing context extraction may need this. #### Specifying links -During `Span` creation, a user MUST have the ability to record links to other -`Span`s. Linked `Span`s can be from the same or a different trace -- see [Links -between spans](../overview.md#links-between-spans). `Link`s cannot be added after -Span creation. - -A `Link` is structurally defined by the following properties: - -- `SpanContext` of the `Span` to link to. -- Zero or more [`Attributes`](../common/README.md#attribute) 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 - 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. Implementations MAY ignore links with an - [invalid](#isvalid) `SpanContext`. - -Links SHOULD preserve the order in which they're set. +During `Span` creation, a user MUST have the ability to record links to other `Span`s. +Linked `Span`s can be from the same or a different trace -- see [links](#link). +`Link`s added at `Span` creation may be considered by [Samplers](sdk.md#sampler) +to make a sampling decision. ### Span operations @@ -556,6 +541,13 @@ keys"](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/REA Note that [`RecordException`](#record-exception) is a specialized variant of `AddEvent` for recording exception events. +#### Add Link + +**Status**: [Experimental](../document-status.md) + +A `Span` MUST have the ability to add `Link`s associated with it after its creation - see [Links](#link). +`Link`s added after `Span` creation may not be considered by [Samplers](sdk.md#sampler). + #### Set Status Sets the `Status` of the `Span`. If used, this will override the default `Span` @@ -797,6 +789,38 @@ To summarize the interpretation of these kinds: | `CONSUMER` | | yes | maybe | | | `INTERNAL` | | | | | +## Link + +A user MUST have the ability to record links to other `SpanContext`s. +Linked `SpanContext`s can be from the same or a different trace -- see [Links +between spans](../overview.md#links-between-spans). + +A `Link` is structurally defined by the following properties: + +- `SpanContext` of the `Span` to link to. +- Zero or more [`Attributes`](../common/README.md#attribute) further describing + the link. + +The 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 + 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. Implementations MAY ignore links with an + [invalid](#isvalid) `SpanContext`. + +The Span interface MAY provide: + +- An API to add multiple `Link`s at once, where the `Link`s are passed in a + single method call. + +Span SHOULD preserve the order in which `Link`s are set. + +The API documentation MUST state that adding links at span creation is preferred +to calling `AddLink` later, for contexts that are available during span creation, +because head sampling decisions can only consider information present during span creation. + ## Concurrency For languages which support concurrent execution the Tracing APIs provide