From bb1e2339359f1120e7027eacd94b4ceea0647489 Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Thu, 20 Aug 2020 10:54:34 +0200 Subject: [PATCH 1/7] Document that event timestamps might be out of range --- specification/trace/api.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/specification/trace/api.md b/specification/trace/api.md index a52997c542d..a1a9d383d27 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -448,6 +448,12 @@ The Span interface MUST provide: Events SHOULD preserve the order in which they're set. This will typically match the ordering of the events' timestamps. +Consumers should be aware that an event's timestamp might be before the start or +after the end of the span if such timestamp was provided by the user to the +`AddEvent` API. +The specification does not require any normalization if the provided timestamp +is out of this range. + Note that the OpenTelemetry project documents certain ["standard event names and keys"](semantic_conventions/README.md) which have prescribed semantic meanings. From fcbc5fe1ab8b24ddd13a09a1ec4b8504a7e78bb1 Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Thu, 20 Aug 2020 13:25:21 +0200 Subject: [PATCH 2/7] Add to changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0014957af6f..0e7be5c67e5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,7 @@ Updates: * 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)) +- Document that event timestamps might be out of range ([#839](https://github.com/open-telemetry/opentelemetry-specification/pull/839)) ## v0.6.0 (07-01-2020) From 8ded9fa9bf8d2730225df197de19372a5ac3dab9 Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Thu, 20 Aug 2020 13:46:42 +0200 Subject: [PATCH 3/7] Update specification/trace/api.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Christian Neumüller --- specification/trace/api.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index a1a9d383d27..180b7863ff9 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -445,8 +445,9 @@ The Span interface MUST provide: 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. +Events SHOULD preserve the order in which they are recorded. +This will typically match the ordering of the events' timestamps, +but events may be recorded out-of-order using custom timestamps. Consumers should be aware that an event's timestamp might be before the start or after the end of the span if such timestamp was provided by the user to the From c5ff2f34f8731a93da7b27fb0017da7b5b4069df Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Thu, 20 Aug 2020 13:55:02 +0200 Subject: [PATCH 4/7] Clarify that custom timestamps should only be used when necessary --- CHANGELOG.md | 2 +- specification/trace/api.md | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0e7be5c67e5..2cc40379929 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,7 +22,7 @@ Updates: * 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)) -- Document that event timestamps might be out of range ([#839](https://github.com/open-telemetry/opentelemetry-specification/pull/839)) +- Clarify event timestamp origin and range ([#839](https://github.com/open-telemetry/opentelemetry-specification/pull/839)) ## v0.6.0 (07-01-2020) diff --git a/specification/trace/api.md b/specification/trace/api.md index 180b7863ff9..ba49ecd6db3 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -429,7 +429,10 @@ An `Event` is defined by the following properties: - (Required) Name of the event. - (Optional) [`Attributes`](../common/common.md#attributes). -- (Optional) Timestamp for the event. If not provided, the current time when the event is added MUST be used. +- (Optional) Custom Timestamp for the event. A custom timestamp SHOULD only be provided, +if there is a significant difference between the time at which the event occurred and +the time it is recorded at. If a custom timestamp is not provided, the current time +at recording the event is added by the implementation. The `Event` SHOULD be an immutable type. From 8f17b7f2fb5cf91918d3daa92503f4a2bf341a11 Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Thu, 20 Aug 2020 16:10:59 +0200 Subject: [PATCH 5/7] Generalize occasions when timestamps might be out of range --- specification/trace/api.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index ba49ecd6db3..9233329368d 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -453,10 +453,10 @@ This will typically match the ordering of the events' timestamps, but events may be recorded out-of-order using custom timestamps. Consumers should be aware that an event's timestamp might be before the start or -after the end of the span if such timestamp was provided by the user to the -`AddEvent` API. -The specification does not require any normalization if the provided timestamp -is out of this range. +after the end of the span if custom timestamps were provided by the user for the +event or when starting or ending the span. +The specification does not require any normalization if provided timestamps are +out of range. Note that the OpenTelemetry project documents certain ["standard event names and keys"](semantic_conventions/README.md) which have prescribed semantic meanings. From d5ba3bb6b4e441df29b91789eb571990089b7109 Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Thu, 20 Aug 2020 16:32:50 +0200 Subject: [PATCH 6/7] Point out that a timestamp is always there but can be overriden by the user --- specification/trace/api.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 9233329368d..553d700edab 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -428,11 +428,9 @@ with the moment when they are added to the `Span`. An `Event` is defined by the following properties: - (Required) Name of the event. +- (Required) A timestamp for the event. Either the time at which the event was +added or a custom timestamp provided by the user. - (Optional) [`Attributes`](../common/common.md#attributes). -- (Optional) Custom Timestamp for the event. A custom timestamp SHOULD only be provided, -if there is a significant difference between the time at which the event occurred and -the time it is recorded at. If a custom timestamp is not provided, the current time -at recording the event is added by the implementation. The `Event` SHOULD be an immutable type. @@ -440,6 +438,10 @@ 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`. + This API takes the name of the event, optional `Attributes` and an optional + `Timestamp` which can be used to specify the time at which the event occurred. + If no custom timestamp is provided by the user, the implementation automatically + sets the time at which this API is called on the event. - 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 From d0f6e62193349aaff634c30b0f77a49d9f754c33 Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Fri, 21 Aug 2020 09:44:39 +0200 Subject: [PATCH 7/7] Remove inconsistent required/optional from property list --- specification/trace/api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 553d700edab..42922f8b1b6 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -427,10 +427,10 @@ with the moment when they are added to the `Span`. An `Event` is defined by the following properties: -- (Required) Name of the event. -- (Required) A timestamp for the event. Either the time at which the event was +- Name of the event. +- A timestamp for the event. Either the time at which the event was added or a custom timestamp provided by the user. -- (Optional) [`Attributes`](../common/common.md#attributes). +- [`Attributes`](../common/common.md#attributes) further describing the event. The `Event` SHOULD be an immutable type.