diff --git a/CHANGELOG.md b/CHANGELOG.md index e7a43160ae9..8be51623621 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ 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. @@ -25,6 +26,7 @@ Updates: - 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) diff --git a/specification/trace/api.md b/specification/trace/api.md index a2e13eb70e7..54aca9ac00c 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -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: @@ -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: - 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. @@ -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. @@ -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