diff --git a/CHANGELOG.md b/CHANGELOG.md index 2d96cd1ef85..2d83afe92bb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,6 +41,8 @@ Updates: ([#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. +- Clarify event timestamp origin and range + ([#839](https://github.com/open-telemetry/opentelemetry-specification/pull/839)) - Clean up api-propagators.md, by extending documentation and removing redundant sections ([#577](https://github.com/open-telemetry/opentelemetry-specification/pull/577)) diff --git a/specification/trace/api.md b/specification/trace/api.md index 75793290fc5..23bc120126e 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -432,9 +432,10 @@ with the moment when they are added to the `Span`. 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. +- 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. +- [`Attributes`](../common/common.md#attributes) further describing the event. The `Event` SHOULD be an immutable type. @@ -442,9 +443,20 @@ 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`. - -Events SHOULD preserve the order in which they're set. This will typically match -the ordering of the events' timestamps. + 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. + +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 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.