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.

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

Add a new AddLink() operation to Span. #3678

Merged
merged 28 commits into from
Oct 10, 2023
Merged
Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
630af80
Add a new AddLink() operation to Span.
carlosalberto Aug 29, 2023
d1df1fb
Update specification/trace/api.md
carlosalberto Aug 30, 2023
c996c59
Feedback.
carlosalberto Aug 31, 2023
b1d9676
Add experimental status to AddLink()
carlosalberto Aug 31, 2023
06e18c2
Mention AddEvent() can be used for this.
carlosalberto Aug 31, 2023
992bdf8
Fix links.
carlosalberto Aug 31, 2023
c178cb3
Merge branch 'main' into add-link
carlosalberto Sep 5, 2023
555b4d6
Merge branch 'main' into add-link
carlosalberto Sep 6, 2023
fdc1307
Merge branch 'main' into add-link
carlosalberto Sep 18, 2023
1a20e93
Clear old sentence.
carlosalberto Sep 18, 2023
8e0b9db
Dot not include timestamp nor event-name for now.
carlosalberto Sep 18, 2023
6a71b9d
Clarification.
carlosalberto Sep 18, 2023
b6f0576
Merge branch 'main' into add-link
carlosalberto Sep 21, 2023
5b3d503
Remove AddEvent() as an option.
carlosalberto Sep 21, 2023
c73fa5d
Be verbose about links at Span creation.
carlosalberto Oct 3, 2023
eef3634
Merge branch 'main' into add-link
carlosalberto Oct 3, 2023
3cba8e0
Update header.
carlosalberto Oct 3, 2023
c34b5f1
Relocate the note about sampling for links added at Span creation.
carlosalberto Oct 3, 2023
6657270
Update specification/trace/api.md
carlosalberto Oct 5, 2023
d9ae319
Add spec compliance matrix entry.
carlosalberto Oct 6, 2023
404fa99
Update specification/trace/api.md
carlosalberto Oct 6, 2023
b963f23
Update specification/trace/api.md
carlosalberto Oct 6, 2023
cb404ca
Merge branch 'main' into add-link
carlosalberto Oct 6, 2023
5a89469
Update CHANGELOG.
carlosalberto Oct 6, 2023
44afd4e
Update specification/trace/api.md
carlosalberto Oct 6, 2023
a41fb10
Merge branch 'main' into add-link
carlosalberto Oct 10, 2023
86101dd
Make linter happy again.
carlosalberto Oct 10, 2023
24bb1bc
Merge branch 'main' into add-link
carlosalberto Oct 10, 2023
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: 1 addition & 1 deletion specification/common/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion specification/compatibility/opencensus.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
pyohannes marked this conversation as resolved.
Show resolved Hide resolved
3. OpenTelemetry specifies that samplers are
Expand Down
2 changes: 1 addition & 1 deletion specification/compatibility/opentracing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
79 changes: 51 additions & 28 deletions specification/trace/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved

<details>
<summary>Table of Contents</summary>
Expand All @@ -29,19 +29,20 @@ linkTitle: API
- [Span](#span)
* [Span Creation](#span-creation)
+ [Determining the Parent Span from a Context](#determining-the-parent-span-from-a-context)
+ [Specifying links](#specifying-links)
* [Span operations](#span-operations)
+ [Get Context](#get-context)
+ [IsRecording](#isrecording)
+ [Set Attributes](#set-attributes)
+ [Add Events](#add-events)
+ [Add Link](#add-link)
+ [Set Status](#set-status)
+ [UpdateName](#updatename)
+ [End](#end)
+ [Record Exception](#record-exception)
* [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)
Expand Down Expand Up @@ -300,7 +301,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).

Expand Down Expand Up @@ -386,7 +387,9 @@ 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).
`Link`s added at `Span` creation are considered by [Samplers](sdk.md#sampler)
to make a sampling decision
- `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.
Expand Down Expand Up @@ -421,30 +424,6 @@ A `SpanContext` cannot be set as active in a `Context` directly, but by
[wrapping it into a Span](#wrapping-a-spancontext-in-a-span).
For example, a `Propagator` performing context extraction may need this.

#### Specifying links
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved

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.

### Span operations

With the exception of the function to retrieve the `Span`'s `SpanContext` and
Expand Down Expand Up @@ -556,6 +535,13 @@ keys"](semantic_conventions/README.md) which have prescribed semantic meanings.
Note that [`RecordException`](#record-exception) is a specialized variant of
`AddEvent` for recording exception events.

#### Add Link

carlosalberto marked this conversation as resolved.
Show resolved Hide resolved
**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`
Expand Down Expand Up @@ -797,6 +783,43 @@ To summarize the interpretation of these kinds:
| `CONSUMER` | | yes | maybe | |
| `INTERNAL` | | | | |

## Link
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved

A user MUST have the ability to record links to other `Span`s.
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved
Linked `Span`s can be from the same or a different trace -- see [Links
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved
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.
- `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.

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` and `timestamp`, 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`. Alternatively, this functionality MAY be provided
through the `AddEvent` operation instead with the respective addition of the new
parameters, e.g. the `SpanContext` to link to.

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.

Note that [Samplers](sdk.md#sampler) may only consider information already
present during span creation. Any `Link`s added later may not change the sampling
decision.

carlosalberto marked this conversation as resolved.
Show resolved Hide resolved
## Concurrency

For languages which support concurrent execution the Tracing APIs provide
Expand Down
Loading