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

Remove lazy Event and Link API from Span interface #840

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,15 @@ Updates:

- Add semantic convention for NGINX custom HTTP 499 status code.
- Adapt semantic conventions for the span name of messaging systems ([#690](https://github.com/open-telemetry/opentelemetry-specification/pull/690))
- Remove lazy Event and Link API from Span interface ([#840](https://github.com/open-telemetry/opentelemetry-specification/pull/840))
- Provide clear definitions for readable and read/write span interfaces in the SDK ([#669](https://github.com/open-telemetry/opentelemetry-specification/pull/669))
* SpanProcessors must provide read/write access at least in OnStart.
- Specify how `Probability` sampler is used with `ParentOrElse` sampler.
- Clean up api-propagators.md, by extending documentation and removing redundant sections ([#577](https://github.com/open-telemetry/opentelemetry-specification/pull/577))
- Rename HTTPText propagator to TextMap ([#793](https://github.com/open-telemetry/opentelemetry-specification/pull/793))
- Rename ParentOrElse sampler to ParentBased and add multiple delegate samplers ([#610](https://github.com/open-telemetry/opentelemetry-specification/pull/610))
- Rename ProbabilitySampler to TraceIdRatioBasedSampler and add requirements ([#611](https://github.com/open-telemetry/opentelemetry-specification/pull/611))
* SIGs are recommended to remove any existing implementation of the lazy APIs to avoid conflicts/breaking changes in case they will be reintroduced to the spec in future.

## v0.6.0 (07-01-2020)

Expand Down
28 changes: 5 additions & 23 deletions specification/trace/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -337,8 +337,8 @@ The parent should be selected in the following order of precedence:

#### Add Links

During the `Span` creation 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
During the `Span` creation 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
description](../overview.md#links-between-spans).

A `Link` is defined by the following properties:
Expand All @@ -348,17 +348,10 @@ A `Link` is defined by the following properties:

The `Link` SHOULD be an immutable type.

The Span creation API should provide:
The Span creation API MUST provide:
Copy link
Member

Choose a reason for hiding this comment

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

why does this say "Span creation"? This section looks like adding links to already created spans. Span creation is covered in previous section, L272.

Copy link
Member Author

Choose a reason for hiding this comment

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

It just specifies in more detail how the API is supposed to look like (i.e., accepting both properties as arguments).

Copy link
Member

Choose a reason for hiding this comment

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

@yurishkuro This is a subsection of that previous section (since links can only be created at span creation time).


- An API to record a single `Link` where the `Link` properties are passed as
arguments. This MAY be called `AddLink`.
- An API to record a single `Link` whose attributes or attribute values are
lazily constructed, with the intention of avoiding unnecessary work if a link
is unused. If the language supports overloads then this SHOULD be called
`AddLink` otherwise `AddLazyLink` MAY be considered. In some languages, it might
be easier to defer `Link` or attribute creation entirely by providing a wrapping
class or function that returns a `Link` or formatted attributes. When providing
a wrapping class or function it SHOULD be named `LinkFormatter`.

Links SHOULD preserve the order in which they're set.

Expand Down Expand Up @@ -437,13 +430,6 @@ The Span interface MUST provide:

- An API to record a single `Event` where the `Event` properties are passed as
arguments. This MAY be called `AddEvent`.
- An API to record a single `Event` whose attributes or attribute values are
lazily constructed, with the intention of avoiding unnecessary work if an event
is unused. If the language supports overloads then this SHOULD be called
`AddEvent` otherwise `AddLazyEvent` MAY be considered. In some languages, it
might be easier to defer `Event` or attribute creation entirely by providing a
wrapping class or function that returns an `Event` or formatted attributes. When
providing a wrapping class or function it SHOULD be named `EventFormatter`.

Events SHOULD preserve the order in which they're set. This will typically match
the ordering of the events' timestamps.
Expand Down Expand Up @@ -680,13 +666,9 @@ SpanBuilder is used by more than one thread/coroutine.

**Span** - All methods of Span are safe to be called concurrently.

**Event** - Events are immutable and safe to be used concurrently. Lazy
initialized events must be thread safe. This is the responsibility of the
implementer of these events.
**Event** - Events are immutable and safe to be used concurrently.

**Link** - Links are immutable and is safe to be used concurrently. Lazy
initialized links must be thread safe. This is the responsibility of the
implementer of these links.
**Link** - Links are immutable and safe to be used concurrently.

## Included Propagators

Expand Down