From 1040881729d86415cf5e59f95959e28de0603f52 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Wed, 29 Sep 2021 18:58:09 +0200 Subject: [PATCH 01/25] Introduce semantic conventions for CloudEvents Co-authored-by: Armin Ruech --- CHANGELOG.md | 2 + semantic_conventions/trace/cloudevents.yaml | 33 +++++++++++++ .../trace/semantic_conventions/cloudevents.md | 47 +++++++++++++++++++ 3 files changed, 82 insertions(+) create mode 100644 semantic_conventions/trace/cloudevents.yaml create mode 100644 specification/trace/semantic_conventions/cloudevents.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 1b96a6e2a79..4046a159de0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -115,6 +115,8 @@ release. ([#1898](https://github.com/open-telemetry/opentelemetry-specification/pull/1898)) - Add `k8s.container.restart_count` Resource attribute. ([#1945](https://github.com/open-telemetry/opentelemetry-specification/pull/1945)) +- Add semantic conventions for [CloudEvents](https://cloudevents.io). + ([#???](https://github.com/open-telemetry/opentelemetry-specification/pull/???)) ### Compatibility diff --git a/semantic_conventions/trace/cloudevents.yaml b/semantic_conventions/trace/cloudevents.yaml new file mode 100644 index 00000000000..a600ef24583 --- /dev/null +++ b/semantic_conventions/trace/cloudevents.yaml @@ -0,0 +1,33 @@ +groups: + - id: cloudevents + prefix: cloudevents + brief: > + This document defines attributes for CloudEvents. + CloudEvents is a specification on how to define event data in a standard way. + These attributes can be attached to spans when performing operations with CloudEvents, regardless of the protocol being used. + attributes: + - id: event_id + type: string + brief: > + The [event_id](https://github.com/cloudevents/spec/blob/master/spec.md#id) identifies the event within the scope of a producer. + examples: ['123e4567-e89b-12d3-a456-426614174000', 'producer-1'] + - id: source + type: string + brief: > + The [source](https://github.com/cloudevents/spec/blob/master/spec.md#source-1) identifies the context in which an event happened. + examples: ['https://github.com/cloudevents', '/cloudevents/spec/pull/123', 'my-service' ] + - id: spec_version + type: string + brief: > + The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/master/spec.md#specversion) which the event uses. + examples: '1.0' + - id: event_type + type: string + brief: > + The [event_type](https://github.com/cloudevents/spec/blob/master/spec.md#type) contains a value describing the type of event related to the originating occurrence. + examples: ['com.github.pull_request.opened', 'com.example.object.deleted.v2'] + - id: subject + type: string + brief: > + The [subject](https://github.com/cloudevents/spec/blob/master/spec.md#subject) of the event in the context of the event producer (identified by source). + examples: 'mynewfile.jpg' diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md new file mode 100644 index 00000000000..73009d89306 --- /dev/null +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -0,0 +1,47 @@ +# CloudEvents + +This document defines how to describe sending and receiving [CloudEvents](https://cloudevents.io/) with spans. + +The transport involved in sending/receiving CloudEvents is represented by a separate span, depending on the underlying protocol used. + +**Status**: [Experimental](../../document-status.md) + + + + + +- [Span name](#span-name) +- [Span kind](#span-kind) +- [Attributes](#attributes) + + + +## Span name + +The span name should be a combination of the `CloudEvents` prefix, followed by the event type as in the following format: + +``` +CloudEvents +``` + +The event type SHOULD only be used as part of the span name if it is known to be of low cardinality (cf. [general span name guidelines](../api.md#span)). + +Examples: + +* `CloudEvents com.github.pull_request.opened` + +## Span kind + +When an entity is acting as a sender of CloudEvents, it should set the span kind to `PRODUCER`. When acting as a receiver, it should set the span kind to `CONSUMER`. + +## Attributes + + +| Attribute | Type | Description | Examples | Required | +|---|---|---|---|---| +| `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/master/spec.md#id) identifies the event within the scope of a producer. | `123e4567-e89b-12d3-a456-426614174000`; `producer-1` | No | +| `cloudevents.source` | string | The [source](https://github.com/cloudevents/spec/blob/master/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | No | +| `cloudevents.spec_version` | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/master/spec.md#specversion) which the event uses. | `1.0` | No | +| `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/master/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | No | +| `cloudevents.subject` | string | The [subject](https://github.com/cloudevents/spec/blob/master/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | No | + From 022345018a0374ed40ff01c466e147ac96ee4fcb Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Wed, 29 Sep 2021 19:19:59 +0200 Subject: [PATCH 02/25] Update changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4046a159de0..9ec2301fd9e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -116,7 +116,7 @@ release. - Add `k8s.container.restart_count` Resource attribute. ([#1945](https://github.com/open-telemetry/opentelemetry-specification/pull/1945)) - Add semantic conventions for [CloudEvents](https://cloudevents.io). - ([#???](https://github.com/open-telemetry/opentelemetry-specification/pull/???)) + ([#1978](https://github.com/open-telemetry/opentelemetry-specification/pull/1978)) ### Compatibility From f82fef8bf0f67a57238e0046a0b2bacaecfad75f Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Mon, 4 Oct 2021 13:10:34 +0200 Subject: [PATCH 03/25] Change wording to reflect the scope of this document --- .../trace/semantic_conventions/cloudevents.md | 34 ++++++------------- 1 file changed, 11 insertions(+), 23 deletions(-) diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index 73009d89306..81e49209a07 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -1,38 +1,26 @@ # CloudEvents -This document defines how to describe sending and receiving [CloudEvents](https://cloudevents.io/) with spans. - -The transport involved in sending/receiving CloudEvents is represented by a separate span, depending on the underlying protocol used. - **Status**: [Experimental](../../document-status.md) - +This specification defines attributes for [CloudEvents](https://cloudevents.io/). +The attributes described in this document are not specific to a particular operation but rather generic. They may be used in any Span they apply to. - +At this time, this specification does not cover: -- [Span name](#span-name) -- [Span kind](#span-kind) -- [Attributes](#attributes) - - +- How and when Spans are created for CloudEvents -## Span name +- Transport aspects of sending and receiving CloudEvents -The span name should be a combination of the `CloudEvents` prefix, followed by the event type as in the following format: +The above points are being worked on in the messaging semantic conventions. +This document will be updated with further guidance once the messaging semantic conventions reaches a stable state. -``` -CloudEvents -``` - -The event type SHOULD only be used as part of the span name if it is known to be of low cardinality (cf. [general span name guidelines](../api.md#span)). - -Examples: + -* `CloudEvents com.github.pull_request.opened` + -## Span kind +- [Attributes](#attributes) -When an entity is acting as a sender of CloudEvents, it should set the span kind to `PRODUCER`. When acting as a receiver, it should set the span kind to `CONSUMER`. + ## Attributes From 86e4e4ef797cc809ed14470acf969f571c23779c Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Tue, 5 Oct 2021 10:01:49 +0200 Subject: [PATCH 04/25] PR suggestions --- semantic_conventions/trace/cloudevents.yaml | 14 +++++++++----- .../trace/semantic_conventions/cloudevents.md | 13 ++++++------- 2 files changed, 15 insertions(+), 12 deletions(-) diff --git a/semantic_conventions/trace/cloudevents.yaml b/semantic_conventions/trace/cloudevents.yaml index a600ef24583..423e2b6c9a7 100644 --- a/semantic_conventions/trace/cloudevents.yaml +++ b/semantic_conventions/trace/cloudevents.yaml @@ -9,14 +9,18 @@ groups: - id: event_id type: string brief: > - The [event_id](https://github.com/cloudevents/spec/blob/master/spec.md#id) identifies the event within the scope of a producer. - examples: ['123e4567-e89b-12d3-a456-426614174000', 'producer-1'] - - id: source + The [event_id](https://github.com/cloudevents/spec/blob/master/spec.md#id) uniquely identifies the event. + note: > + Producers MUST ensure that event_source + event_id is unique for each distinct event. + If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same id. + Consumers MAY assume that Events with identical event_source and event_id are duplicates. + examples: ['123e4567-e89b-12d3-a456-426614174000', '0001'] + - id: event_source type: string brief: > The [source](https://github.com/cloudevents/spec/blob/master/spec.md#source-1) identifies the context in which an event happened. examples: ['https://github.com/cloudevents', '/cloudevents/spec/pull/123', 'my-service' ] - - id: spec_version + - id: event_spec_version type: string brief: > The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/master/spec.md#specversion) which the event uses. @@ -26,7 +30,7 @@ groups: brief: > The [event_type](https://github.com/cloudevents/spec/blob/master/spec.md#type) contains a value describing the type of event related to the originating occurrence. examples: ['com.github.pull_request.opened', 'com.example.object.deleted.v2'] - - id: subject + - id: event_subject type: string brief: > The [subject](https://github.com/cloudevents/spec/blob/master/spec.md#subject) of the event in the context of the event producer (identified by source). diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index 81e49209a07..2754d033002 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -11,9 +11,6 @@ At this time, this specification does not cover: - Transport aspects of sending and receiving CloudEvents -The above points are being worked on in the messaging semantic conventions. -This document will be updated with further guidance once the messaging semantic conventions reaches a stable state. - @@ -27,9 +24,11 @@ This document will be updated with further guidance once the messaging semantic | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| -| `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/master/spec.md#id) identifies the event within the scope of a producer. | `123e4567-e89b-12d3-a456-426614174000`; `producer-1` | No | -| `cloudevents.source` | string | The [source](https://github.com/cloudevents/spec/blob/master/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | No | -| `cloudevents.spec_version` | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/master/spec.md#specversion) which the event uses. | `1.0` | No | +| `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/master/spec.md#id) uniquely identifies the event. [1] | `123e4567-e89b-12d3-a456-426614174000`; `0001` | No | +| `cloudevents.event_source` | string | The [source](https://github.com/cloudevents/spec/blob/master/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | No | +| `cloudevents.event_spec_version` | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/master/spec.md#specversion) which the event uses. | `1.0` | No | | `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/master/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | No | -| `cloudevents.subject` | string | The [subject](https://github.com/cloudevents/spec/blob/master/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | No | +| `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/master/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | No | + +**[1]:** Producers MUST ensure that event_source + event_id is unique for each distinct event. If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same id. Consumers MAY assume that Events with identical event_source and event_id are duplicates. From a1051c36566f98d68221d3ae081f78d5afc31f9b Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Tue, 5 Oct 2021 10:05:13 +0200 Subject: [PATCH 05/25] Remove section of not covered scenarios --- specification/trace/semantic_conventions/cloudevents.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index 2754d033002..c1f1d6c1ae9 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -5,12 +5,6 @@ This specification defines attributes for [CloudEvents](https://cloudevents.io/). The attributes described in this document are not specific to a particular operation but rather generic. They may be used in any Span they apply to. -At this time, this specification does not cover: - -- How and when Spans are created for CloudEvents - -- Transport aspects of sending and receiving CloudEvents - From 6d3cf0a6c29ddf5a30cf7cbbfda9b0956bb879bf Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Tue, 5 Oct 2021 10:21:21 +0200 Subject: [PATCH 06/25] Fix lint errors --- semantic_conventions/trace/cloudevents.yaml | 4 ++-- specification/trace/semantic_conventions/cloudevents.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/semantic_conventions/trace/cloudevents.yaml b/semantic_conventions/trace/cloudevents.yaml index 423e2b6c9a7..639241e1875 100644 --- a/semantic_conventions/trace/cloudevents.yaml +++ b/semantic_conventions/trace/cloudevents.yaml @@ -11,8 +11,8 @@ groups: brief: > The [event_id](https://github.com/cloudevents/spec/blob/master/spec.md#id) uniquely identifies the event. note: > - Producers MUST ensure that event_source + event_id is unique for each distinct event. - If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same id. + Producers MUST ensure that event_source + event_id is unique for each distinct event. + If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same id. Consumers MAY assume that Events with identical event_source and event_id are duplicates. examples: ['123e4567-e89b-12d3-a456-426614174000', '0001'] - id: event_source diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index c1f1d6c1ae9..b28c4826259 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -24,5 +24,5 @@ The attributes described in this document are not specific to a particular opera | `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/master/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | No | | `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/master/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | No | -**[1]:** Producers MUST ensure that event_source + event_id is unique for each distinct event. If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same id. Consumers MAY assume that Events with identical event_source and event_id are duplicates. +**[1]:** Producers MUST ensure that event_source + event_id is unique for each distinct event. If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same id. Consumers MAY assume that Events with identical event_source and event_id are duplicates. From 0d7cdec98315cacda979f9dceda45b07486ef33c Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Fri, 15 Oct 2021 17:20:07 +0200 Subject: [PATCH 07/25] Move changelog into unreleased section --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ec2301fd9e..76c05184c63 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -44,6 +44,8 @@ release. ([#1919](https://github.com/open-telemetry/opentelemetry-specification/pull/1916)) - Change meaning and discourage use of `faas.trigger` for FaaS clients (outgoing). ([#1921](https://github.com/open-telemetry/opentelemetry-specification/pull/1921)) +- Add semantic conventions for [CloudEvents](https://cloudevents.io). + ([#1978](https://github.com/open-telemetry/opentelemetry-specification/pull/1978)) ### Compatibility From a37ac6e1b01efc9ec1e61d3d26ba4ff6f2a37281 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 22 Oct 2021 00:38:24 -0700 Subject: [PATCH 08/25] Adding spans to cloudevents spec (#17) Co-authored-by: Joao Grassi --- .../trace/semantic_conventions/cloudevents.md | 34 +++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index b28c4826259..494196d5c26 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -2,8 +2,13 @@ **Status**: [Experimental](../../document-status.md) -This specification defines attributes for [CloudEvents](https://cloudevents.io/). -The attributes described in this document are not specific to a particular operation but rather generic. They may be used in any Span they apply to. +This specification defines semantic conventions for [CloudEvents](https://cloudevents.io/). It covers creation, processing and context propagation between producer and consumer. It does not cover transport aspects of publishing and receiving cloud events. + +## Overview + +To be individually traceable, each CloudEvent has to have its own trace context. The trace context is populated in the event using the [Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.1/extensions/distributed-tracing.md). + +Once the trace context is set on the event, it MUST not be modified. @@ -13,8 +18,33 @@ The attributes described in this document are not specific to a particular opera +## Spans + +### Creation + +Instrumentation SHOULD create a new span and populate the [Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.1/extensions/distributed-tracing.md) on the event. This applies when: + +- A CloudEvent is created by the instrumented library. It may be impossible or impractical to create the Span during event creation (e.g. inside the constructor or in a factory method) - instrumentation MAY create the Span later, when passing the event to the transport layer. +- A CloudEvent is created outside of the instrumented library (e.g. directly constructed by the application owner, without calling a constructor or factory method), but passed without the 'Distributed Tracing Extension' populated. + +In case a CloudEvent is passed to the instrumented library with the Distributed Tracing Extension populated, instrumentation MUST NOT create a span and MUST NOT modify the Distributed Tracing Extension on the event. + +**Span name:** `CloudEvents Create ` +**Span kind:** PRODUCER + +### Processing + +To trace the processing of one or more CloudEvents, instrumentation SHOULD create a new span. +If a single event is processed, instrumentation SHOULD use the remote trace context from Distributed Tracing Extension as a parent or MAY instead add it as a link on the processing span. +If multiple events are processed together, for each event being processed, if the event has Distributed Tracing Extension populated, instrumentation MUST add a link to the trace context from the extension on the processing span. + +**Span name:** `CloudEvents Process ` +**Span kind:** CONSUMER + ## Attributes +Attributes are applicable to creation and processing spans. + | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| From 8b362c597373b3b07657e734dd2f731835b33374 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Fri, 22 Oct 2021 10:06:11 +0200 Subject: [PATCH 09/25] Update TOC --- .../trace/semantic_conventions/cloudevents.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index 494196d5c26..6cd8aff85b4 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -14,6 +14,9 @@ Once the trace context is set on the event, it MUST not be modified. +- [Spans](#spans) + * [Creation](#creation) + * [Processing](#processing) - [Attributes](#attributes) @@ -25,7 +28,7 @@ Once the trace context is set on the event, it MUST not be modified. Instrumentation SHOULD create a new span and populate the [Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.1/extensions/distributed-tracing.md) on the event. This applies when: - A CloudEvent is created by the instrumented library. It may be impossible or impractical to create the Span during event creation (e.g. inside the constructor or in a factory method) - instrumentation MAY create the Span later, when passing the event to the transport layer. -- A CloudEvent is created outside of the instrumented library (e.g. directly constructed by the application owner, without calling a constructor or factory method), but passed without the 'Distributed Tracing Extension' populated. +- A CloudEvent is created outside of the instrumented library (e.g. directly constructed by the application owner, without calling a constructor or factory method), and passed without the Distributed Tracing Extension populated. In case a CloudEvent is passed to the instrumented library with the Distributed Tracing Extension populated, instrumentation MUST NOT create a span and MUST NOT modify the Distributed Tracing Extension on the event. @@ -35,15 +38,16 @@ In case a CloudEvent is passed to the instrumented library with the Distributed ### Processing To trace the processing of one or more CloudEvents, instrumentation SHOULD create a new span. -If a single event is processed, instrumentation SHOULD use the remote trace context from Distributed Tracing Extension as a parent or MAY instead add it as a link on the processing span. -If multiple events are processed together, for each event being processed, if the event has Distributed Tracing Extension populated, instrumentation MUST add a link to the trace context from the extension on the processing span. +If a single event is processed, instrumentation SHOULD use the remote trace context from the Distributed Tracing Extension as a parent or MAY instead add it as a link on the processing span. + +If multiple events are processed together, for each event being processed, if the event has the Distributed Tracing Extension populated, instrumentation MUST add a link to the trace context from the extension on the processing span. **Span name:** `CloudEvents Process ` **Span kind:** CONSUMER ## Attributes -Attributes are applicable to creation and processing spans. +The following attributes are applicable to creation and processing Spans. | Attribute | Type | Description | Examples | Required | From 1a30c696b980751985561b3813d9b9a5fecf6e59 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 10 Nov 2021 14:10:11 -0800 Subject: [PATCH 10/25] Update CloudEvents spec based on meeting discussion (#18) * SIG feedback: process span - always links, no batching on receive * address some feedback * update note on handlers --- specification/trace/semantic_conventions/cloudevents.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index 6cd8aff85b4..85ff7335a64 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -37,14 +37,13 @@ In case a CloudEvent is passed to the instrumented library with the Distributed ### Processing -To trace the processing of one or more CloudEvents, instrumentation SHOULD create a new span. -If a single event is processed, instrumentation SHOULD use the remote trace context from the Distributed Tracing Extension as a parent or MAY instead add it as a link on the processing span. - -If multiple events are processed together, for each event being processed, if the event has the Distributed Tracing Extension populated, instrumentation MUST add a link to the trace context from the extension on the processing span. +When instrumented library supports processing of a single CloudEvent, instrumentation SHOULD create a new span to trace it. Instrumentation SHOULD set the remote trace context from the Distributed Tracing Extension as a link on the processing span. **Span name:** `CloudEvents Process ` **Span kind:** CONSUMER +Note: CloudEvents processing does not follow a common pattern. Some "CloudEvents-enabled" libraries expose handlers for processing (e.g. [CloudEvents Go SDK](https://github.com/cloudevents/sdk-go#receive-your-first-cloudevent)) and can auto-instrument the processing calls. Alternatively, a library might offer a handler, but the user chooses not to use it, or a library does not offer one at all. In such cases, the instrumentation responsibility falls under the application owner. + ## Attributes The following attributes are applicable to creation and processing Spans. From b513e29adaa40afd409c50198315886b06086e7c Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Thu, 11 Nov 2021 09:56:19 +0100 Subject: [PATCH 11/25] Update specification/trace/semantic_conventions/cloudevents.md Co-authored-by: Johannes Tax --- specification/trace/semantic_conventions/cloudevents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index 85ff7335a64..0f9fb417b00 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -42,7 +42,7 @@ When instrumented library supports processing of a single CloudEvent, instrument **Span name:** `CloudEvents Process ` **Span kind:** CONSUMER -Note: CloudEvents processing does not follow a common pattern. Some "CloudEvents-enabled" libraries expose handlers for processing (e.g. [CloudEvents Go SDK](https://github.com/cloudevents/sdk-go#receive-your-first-cloudevent)) and can auto-instrument the processing calls. Alternatively, a library might offer a handler, but the user chooses not to use it, or a library does not offer one at all. In such cases, the instrumentation responsibility falls under the application owner. +Note: CloudEvents processing does not follow a common pattern. Some "CloudEvents-enabled" libraries expose handlers for processing (e.g. [CloudEvents Go SDK](https://github.com/cloudevents/sdk-go#receive-your-first-cloudevent)) and can auto-instrument the processing calls. Alternatively, a library might offer a handler, but the user chooses not to use it, or a library does not offer one at all. In such cases, the instrumentation responsibility lies with the application owner. ## Attributes From bbdc4f608f34adb87010119cada221a7d30d9407 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Thu, 18 Nov 2021 14:25:43 +0100 Subject: [PATCH 12/25] Clarify paragraph around cloud events libraries --- specification/trace/semantic_conventions/cloudevents.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index 0f9fb417b00..ab7278250b5 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -42,7 +42,12 @@ When instrumented library supports processing of a single CloudEvent, instrument **Span name:** `CloudEvents Process ` **Span kind:** CONSUMER -Note: CloudEvents processing does not follow a common pattern. Some "CloudEvents-enabled" libraries expose handlers for processing (e.g. [CloudEvents Go SDK](https://github.com/cloudevents/sdk-go#receive-your-first-cloudevent)) and can auto-instrument the processing calls. Alternatively, a library might offer a handler, but the user chooses not to use it, or a library does not offer one at all. In such cases, the instrumentation responsibility lies with the application owner. +## Instrumentation + +CloudEvents libraries SHOULD offer mechanisms to make the aforementioned Span +operations (creation, extraction, and injection of context into events) transparent +for application owners. CloudEvents libraries expose such mechanisms using +language idiomatic approaches, for example, via handlers or middlewares. ## Attributes From ce87cf061b83f3e86c86815a3adcc2313af60541 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Thu, 18 Nov 2021 14:53:08 +0100 Subject: [PATCH 13/25] Change a bit paragraph around cloud events libraries --- .../trace/semantic_conventions/cloudevents.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index ab7278250b5..1608738060a 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -17,6 +17,7 @@ Once the trace context is set on the event, it MUST not be modified. - [Spans](#spans) * [Creation](#creation) * [Processing](#processing) +- [Instrumentation](#instrumentation) - [Attributes](#attributes) @@ -44,10 +45,11 @@ When instrumented library supports processing of a single CloudEvent, instrument ## Instrumentation -CloudEvents libraries SHOULD offer mechanisms to make the aforementioned Span -operations (creation, extraction, and injection of context into events) transparent -for application owners. CloudEvents libraries expose such mechanisms using -language idiomatic approaches, for example, via handlers or middlewares. +CloudEvents libraries SHOULD have built-in mechanisms to make the aforementioned +Span operations (creation, extraction, and injection of context into events) +transparent for application owners. When auto-instrumentation +is not feasible, CloudEvents libraries SHOULD offer such mechanisms in a form that +application owners can "plug in" to apply the Span operations above by themselves. ## Attributes From 95523cf967687b12240c3ab4ff846a475507b73b Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Mon, 20 Dec 2021 12:32:54 +0100 Subject: [PATCH 14/25] PR suggestions --- semantic_conventions/trace/cloudevents.yaml | 10 ++--- .../trace/semantic_conventions/cloudevents.md | 41 +++++++++++++------ 2 files changed, 34 insertions(+), 17 deletions(-) diff --git a/semantic_conventions/trace/cloudevents.yaml b/semantic_conventions/trace/cloudevents.yaml index 639241e1875..ae44e7d071f 100644 --- a/semantic_conventions/trace/cloudevents.yaml +++ b/semantic_conventions/trace/cloudevents.yaml @@ -9,7 +9,7 @@ groups: - id: event_id type: string brief: > - The [event_id](https://github.com/cloudevents/spec/blob/master/spec.md#id) uniquely identifies the event. + The [event_id](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#id) uniquely identifies the event. note: > Producers MUST ensure that event_source + event_id is unique for each distinct event. If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same id. @@ -18,20 +18,20 @@ groups: - id: event_source type: string brief: > - The [source](https://github.com/cloudevents/spec/blob/master/spec.md#source-1) identifies the context in which an event happened. + The [source](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#source-1) identifies the context in which an event happened. examples: ['https://github.com/cloudevents', '/cloudevents/spec/pull/123', 'my-service' ] - id: event_spec_version type: string brief: > - The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/master/spec.md#specversion) which the event uses. + The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#specversion) which the event uses. examples: '1.0' - id: event_type type: string brief: > - The [event_type](https://github.com/cloudevents/spec/blob/master/spec.md#type) contains a value describing the type of event related to the originating occurrence. + The [event_type](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#type) contains a value describing the type of event related to the originating occurrence. examples: ['com.github.pull_request.opened', 'com.example.object.deleted.v2'] - id: event_subject type: string brief: > - The [subject](https://github.com/cloudevents/spec/blob/master/spec.md#subject) of the event in the context of the event producer (identified by source). + The [subject](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#subject) of the event in the context of the event producer (identified by source). examples: 'mynewfile.jpg' diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index 1608738060a..3a00efe2469 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -2,11 +2,15 @@ **Status**: [Experimental](../../document-status.md) -This specification defines semantic conventions for [CloudEvents](https://cloudevents.io/). It covers creation, processing and context propagation between producer and consumer. It does not cover transport aspects of publishing and receiving cloud events. +This specification defines semantic conventions for [CloudEvents](https://cloudevents.io/). +It covers creation, processing and context propagation between producer and consumer. +It does not cover transport aspects of publishing and receiving cloud events. ## Overview -To be individually traceable, each CloudEvent has to have its own trace context. The trace context is populated in the event using the [Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.1/extensions/distributed-tracing.md). +To be individually traceable, each CloudEvent has to have its own trace context. +The trace context is populated in the event using the +[CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.1/extensions/distributed-tracing.md). Once the trace context is set on the event, it MUST not be modified. @@ -26,19 +30,32 @@ Once the trace context is set on the event, it MUST not be modified. ### Creation -Instrumentation SHOULD create a new span and populate the [Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.1/extensions/distributed-tracing.md) on the event. This applies when: +Instrumentation SHOULD create a new span and populate the +[CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.1/extensions/distributed-tracing.md) +on the event. This applies when: -- A CloudEvent is created by the instrumented library. It may be impossible or impractical to create the Span during event creation (e.g. inside the constructor or in a factory method) - instrumentation MAY create the Span later, when passing the event to the transport layer. -- A CloudEvent is created outside of the instrumented library (e.g. directly constructed by the application owner, without calling a constructor or factory method), and passed without the Distributed Tracing Extension populated. +- A CloudEvent is created by the instrumented library. +It may be impossible or impractical to create the Span during event +creation (e.g. inside the constructor or in a factory method), +so instrumentation MAY create the Span later, when passing the event to the transport layer. +- A CloudEvent is created outside of the instrumented library +(e.g. directly constructed by the application owner, without calling a constructor or factory method), +and passed without the Distributed Tracing Extension populated. -In case a CloudEvent is passed to the instrumented library with the Distributed Tracing Extension populated, instrumentation MUST NOT create a span and MUST NOT modify the Distributed Tracing Extension on the event. +In case a CloudEvent is passed to the instrumented library with the +Distributed Tracing Extension already populated, instrumentation MUST NOT create +a span and MUST NOT modify the Distributed Tracing Extension on the event. **Span name:** `CloudEvents Create ` **Span kind:** PRODUCER ### Processing -When instrumented library supports processing of a single CloudEvent, instrumentation SHOULD create a new span to trace it. Instrumentation SHOULD set the remote trace context from the Distributed Tracing Extension as a link on the processing span. +When an instrumented library supports processing of a single CloudEvent, +instrumentation SHOULD create a new span to trace it. + +Instrumentation SHOULD set the remote trace context from the +Distributed Tracing Extension as a link on the processing span. **Span name:** `CloudEvents Process ` **Span kind:** CONSUMER @@ -58,11 +75,11 @@ The following attributes are applicable to creation and processing Spans. | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| -| `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/master/spec.md#id) uniquely identifies the event. [1] | `123e4567-e89b-12d3-a456-426614174000`; `0001` | No | -| `cloudevents.event_source` | string | The [source](https://github.com/cloudevents/spec/blob/master/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | No | -| `cloudevents.event_spec_version` | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/master/spec.md#specversion) which the event uses. | `1.0` | No | -| `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/master/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | No | -| `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/master/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | No | +| `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#id) uniquely identifies the event. [1] | `123e4567-e89b-12d3-a456-426614174000`; `0001` | No | +| `cloudevents.event_source` | string | The [source](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | No | +| `cloudevents.event_spec_version` | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#specversion) which the event uses. | `1.0` | No | +| `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | No | +| `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | No | **[1]:** Producers MUST ensure that event_source + event_id is unique for each distinct event. If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same id. Consumers MAY assume that Events with identical event_source and event_id are duplicates. From be229c8bf227b6ef49a74d5957196e41ad927b11 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Tue, 28 Dec 2021 09:35:36 +0100 Subject: [PATCH 15/25] Remove instrumentation section As discussed in the comments, this spec should not make recommendations on what instrumentation libraries/sdks should do or offer regarding the ease of auto-instrumentation. This recommendation is of better use in their own documentation/specification, which is the case for CloudEvents. --- semantic_conventions/trace/cloudevents.yaml | 4 ---- .../trace/semantic_conventions/cloudevents.md | 15 +++------------ 2 files changed, 3 insertions(+), 16 deletions(-) diff --git a/semantic_conventions/trace/cloudevents.yaml b/semantic_conventions/trace/cloudevents.yaml index ae44e7d071f..e02a25a3c67 100644 --- a/semantic_conventions/trace/cloudevents.yaml +++ b/semantic_conventions/trace/cloudevents.yaml @@ -10,10 +10,6 @@ groups: type: string brief: > The [event_id](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#id) uniquely identifies the event. - note: > - Producers MUST ensure that event_source + event_id is unique for each distinct event. - If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same id. - Consumers MAY assume that Events with identical event_source and event_id are duplicates. examples: ['123e4567-e89b-12d3-a456-426614174000', '0001'] - id: event_source type: string diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index 3a00efe2469..6e129523e87 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -21,7 +21,6 @@ Once the trace context is set on the event, it MUST not be modified. - [Spans](#spans) * [Creation](#creation) * [Processing](#processing) -- [Instrumentation](#instrumentation) - [Attributes](#attributes) @@ -47,6 +46,7 @@ Distributed Tracing Extension already populated, instrumentation MUST NOT create a span and MUST NOT modify the Distributed Tracing Extension on the event. **Span name:** `CloudEvents Create ` + **Span kind:** PRODUCER ### Processing @@ -58,15 +58,8 @@ Instrumentation SHOULD set the remote trace context from the Distributed Tracing Extension as a link on the processing span. **Span name:** `CloudEvents Process ` -**Span kind:** CONSUMER - -## Instrumentation -CloudEvents libraries SHOULD have built-in mechanisms to make the aforementioned -Span operations (creation, extraction, and injection of context into events) -transparent for application owners. When auto-instrumentation -is not feasible, CloudEvents libraries SHOULD offer such mechanisms in a form that -application owners can "plug in" to apply the Span operations above by themselves. +**Span kind:** CONSUMER ## Attributes @@ -75,11 +68,9 @@ The following attributes are applicable to creation and processing Spans. | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| -| `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#id) uniquely identifies the event. [1] | `123e4567-e89b-12d3-a456-426614174000`; `0001` | No | +| `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#id) uniquely identifies the event. | `123e4567-e89b-12d3-a456-426614174000`; `0001` | No | | `cloudevents.event_source` | string | The [source](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | No | | `cloudevents.event_spec_version` | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#specversion) which the event uses. | `1.0` | No | | `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | No | | `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | No | - -**[1]:** Producers MUST ensure that event_source + event_id is unique for each distinct event. If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same id. Consumers MAY assume that Events with identical event_source and event_id are duplicates. From 7128a5cdeb2298509d81297471ec73da57d1f778 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Wed, 16 Feb 2022 11:30:58 +0100 Subject: [PATCH 16/25] Mark required attributes --- semantic_conventions/trace/cloudevents.yaml | 4 ++++ specification/trace/semantic_conventions/cloudevents.md | 8 ++++---- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/semantic_conventions/trace/cloudevents.yaml b/semantic_conventions/trace/cloudevents.yaml index e02a25a3c67..3f62a6568ff 100644 --- a/semantic_conventions/trace/cloudevents.yaml +++ b/semantic_conventions/trace/cloudevents.yaml @@ -8,21 +8,25 @@ groups: attributes: - id: event_id type: string + required: always brief: > The [event_id](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#id) uniquely identifies the event. examples: ['123e4567-e89b-12d3-a456-426614174000', '0001'] - id: event_source type: string + required: always brief: > The [source](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#source-1) identifies the context in which an event happened. examples: ['https://github.com/cloudevents', '/cloudevents/spec/pull/123', 'my-service' ] - id: event_spec_version type: string + required: always brief: > The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#specversion) which the event uses. examples: '1.0' - id: event_type type: string + required: always brief: > The [event_type](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#type) contains a value describing the type of event related to the originating occurrence. examples: ['com.github.pull_request.opened', 'com.example.object.deleted.v2'] diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index 6e129523e87..2052e176ea7 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -68,9 +68,9 @@ The following attributes are applicable to creation and processing Spans. | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| -| `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#id) uniquely identifies the event. | `123e4567-e89b-12d3-a456-426614174000`; `0001` | No | -| `cloudevents.event_source` | string | The [source](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | No | -| `cloudevents.event_spec_version` | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#specversion) which the event uses. | `1.0` | No | -| `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | No | +| `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#id) uniquely identifies the event. | `123e4567-e89b-12d3-a456-426614174000`; `0001` | Yes | +| `cloudevents.event_source` | string | The [source](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | Yes | +| `cloudevents.event_spec_version` | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#specversion) which the event uses. | `1.0` | Yes | +| `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | Yes | | `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | No | From b17e28f14dc3475c69fa0b29e29b52f6fa435590 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Wed, 16 Feb 2022 16:35:04 +0100 Subject: [PATCH 17/25] Add clarification about CloudEvents --- .../trace/semantic_conventions/cloudevents.md | 33 +++++++++++++++++-- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index 2052e176ea7..fd7c145b379 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -2,9 +2,36 @@ **Status**: [Experimental](../../document-status.md) -This specification defines semantic conventions for [CloudEvents](https://cloudevents.io/). -It covers creation, processing and context propagation between producer and consumer. -It does not cover transport aspects of publishing and receiving cloud events. +## Definitions + + From the + [CloudEvents specification:](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#overview) + +> CloudEvents is a specification for describing event data in common formats +to provide interoperability across services, platforms and systems. + +For more information and background on the history of how CloudEvents came to +fruition, consult the +[CloudEvents Primer](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/primer.md) +document. + +CloudEvents are typically used in distributed, event-based systems. +Tracing such event-based systems can be a challenging task to achieve. +Many components can produce and consume events and such events can trigger +the dispatch of further events, all in an asynchronous manner. + +The semantic conventions below, define how to model the different stages of a +CloudEvent in event-based systems. It covers creation, processing, +context propagation between producer and consumer and how to enrich spans +with CloudEvent-specific attributes. + +With the proposed model, it is possible to have an overview of everything +that happened as the result of an event. One can, for example, answer the +following questions: + +- Which components in a system reacted to an event +- What further events were sent due to an incoming event +- Which event caused an exception in the chain ## Overview From dc6a944b7eed303285f95276af6f350854007fcf Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Wed, 16 Feb 2022 16:48:10 +0100 Subject: [PATCH 18/25] Improve wording --- specification/trace/semantic_conventions/cloudevents.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index fd7c145b379..953fd54abd5 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -29,9 +29,9 @@ With the proposed model, it is possible to have an overview of everything that happened as the result of an event. One can, for example, answer the following questions: -- Which components in a system reacted to an event +- What components in a system reacted to an event - What further events were sent due to an incoming event -- Which event caused an exception in the chain +- Which event caused the exception ## Overview From 56426fe68fabdc899a39c416cc8009c667def8db Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Fri, 25 Feb 2022 12:41:05 +0100 Subject: [PATCH 19/25] Move reasoning + diagrams from comments to the document --- .../trace/semantic_conventions/cloudevents.md | 153 ++++++++++++++---- 1 file changed, 123 insertions(+), 30 deletions(-) diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index 953fd54abd5..3672fa03b45 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -2,6 +2,20 @@ **Status**: [Experimental](../../document-status.md) + + + + +- [Definitions](#definitions) +- [Overview](#overview) +- [Conventions](#conventions) + * [Spans](#spans) + + [Creation](#creation) + + [Processing](#processing) + * [Attributes](#attributes) + + + ## Definitions From the @@ -9,21 +23,69 @@ > CloudEvents is a specification for describing event data in common formats to provide interoperability across services, platforms and systems. +> -For more information and background on the history of how CloudEvents came to -fruition, consult the +For more information on the concepts, terminology and background of CloudEvents +consult the [CloudEvents Primer](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/primer.md) document. -CloudEvents are typically used in distributed, event-based systems. -Tracing such event-based systems can be a challenging task to achieve. -Many components can produce and consume events and such events can trigger -the dispatch of further events, all in an asynchronous manner. +## Overview -The semantic conventions below, define how to model the different stages of a -CloudEvent in event-based systems. It covers creation, processing, -context propagation between producer and consumer and how to enrich spans -with CloudEvent-specific attributes. +A CloudEvent can be sent directly from producer to consumer. +For such a scenario, the traditional parent-child trace model works well. +However, CloudEvents are also used in distributed systems where an event +can go through many [hops](https://en.wikipedia.org/wiki/Hop_(networking)) +until it reaches a consumer. In this scenario, the traditional parent-child +trace model is not sufficient to produce a meaningful trace. + +Consider the following scenario: + +``` + +----------+ +--------------+ + | Producer | ---------------> | Intermediary | + +----------+ +--------------+ + | + | + | + v + +----------+ +----------+ + | Consumer | <----------------- | Queue | + +----------+ +----------+ +``` + +With the traditional parent-child trace model, the above scenario would produce +two traces, completely independent from each other. It is not possible to +correlate a producer with a consumer(s). + +``` ++---------------------------------------------------+ +| Trace 1 | +| | +| +---------------------------------------+ | +| | Send (auto-instr) | | +| +---------------------------------------+ | +| +------------------------------------+ | +| | Intermediary: Received (auto-instr)| | +| +------------------------------------+ | +| +------------------------------------+ | +| | Intermediary: Send (auto-instr) | | +| +------------------------------------+ | +| | +| Trace 2 | +| | +| +---------------------------------------+ | +| | Consumer: Receive (auto-instr) | | +| +---------------------------------------+ | +| | ++---------------------------------------------------+ +``` + +This document defines semantic conventions to model the different stages +a CloudEvent can go through in a system, making it possible to create traces +that are meaningful and consistent. It covers creation, processing, +context propagation between producer and consumer(s) and attributes +to be added to spans. With the proposed model, it is possible to have an overview of everything that happened as the result of an event. One can, for example, answer the @@ -33,28 +95,59 @@ following questions: - What further events were sent due to an incoming event - Which event caused the exception -## Overview - -To be individually traceable, each CloudEvent has to have its own trace context. -The trace context is populated in the event using the +With the conventions in this document, the application scenario above would +produce a trace where it is possible to correlate a producer with a consumer(s): + +``` ++-------------------------------------------------------+ +| Trace 1 | +| | +| +---------------------------------------+ | +| +---> | Create event | | +| | +---------------------------------------+ | +| | +---------------------------------------+ | +| | | Send (auto-instr) | | +| | +---------------------------------------+ | +| | +------------------------------------+ | +| | | Intermediary: Received (auto-instr)| | +| | +------------------------------------+ | +| | +------------------------------------+ | +| | | Intermediary: Send (auto-instr) | | +| |Link +------------------------------------+ | +| | | +| | | +| | | +| | Trace 2 | +| | | +| | +---------------------------------------+ | +| | | Consumer: Receive (auto-instr) | | +| | +---------------------------------------+ | +| | +-------------------------------------+ | +| +------ | Consumer: Process | | +| +-------------------------------------+ | +| | ++-------------------------------------------------------+ +``` + +## Conventions + +To achieve the trace above, it is necessary to capture the context of +the event creation so that when the CloudEvent reaches its destination(s), this +context can be continued. Each CloudEvent acts then as the medium of this +context propagation. + +This document relies on the CloudEvents specification, which defines this +context propagation mechanism via the [CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.1/extensions/distributed-tracing.md). +Once the trace context is set on the event +via the Distributed Tracing Extension, it MUST not be modified. -Once the trace context is set on the event, it MUST not be modified. - - - - - -- [Spans](#spans) - * [Creation](#creation) - * [Processing](#processing) -- [Attributes](#attributes) - - +The remainder of this section describes the semantic conventions for Spans +required to achieve the proposed trace. -## Spans +### Spans -### Creation +#### Creation Instrumentation SHOULD create a new span and populate the [CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.1/extensions/distributed-tracing.md) @@ -76,7 +169,7 @@ a span and MUST NOT modify the Distributed Tracing Extension on the event. **Span kind:** PRODUCER -### Processing +#### Processing When an instrumented library supports processing of a single CloudEvent, instrumentation SHOULD create a new span to trace it. @@ -88,7 +181,7 @@ Distributed Tracing Extension as a link on the processing span. **Span kind:** CONSUMER -## Attributes +### Attributes The following attributes are applicable to creation and processing Spans. From ca0da3d965cb81850cdade1f3caedac0127d3b41 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Thu, 10 Mar 2022 14:14:27 +0100 Subject: [PATCH 20/25] Apply suggestions from code review Co-authored-by: Armin Ruech --- .../trace/semantic_conventions/cloudevents.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index 3672fa03b45..5ee7f9f6aae 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -19,7 +19,7 @@ ## Definitions From the - [CloudEvents specification:](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#overview) + [CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#overview): > CloudEvents is a specification for describing event data in common formats to provide interoperability across services, platforms and systems. @@ -55,8 +55,9 @@ Consider the following scenario: ``` With the traditional parent-child trace model, the above scenario would produce -two traces, completely independent from each other. It is not possible to -correlate a producer with a consumer(s). +two traces, completely independent from each other because the consumer +starts receiving (and thus has to specify a parent span) before it receives the event. +It is not possible to correlate a producer with a consumer(s) solely via a parent-child relationship. ``` +---------------------------------------------------+ @@ -138,7 +139,7 @@ context propagation. This document relies on the CloudEvents specification, which defines this context propagation mechanism via the -[CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.1/extensions/distributed-tracing.md). +[CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/extensions/distributed-tracing.md). Once the trace context is set on the event via the Distributed Tracing Extension, it MUST not be modified. @@ -150,7 +151,7 @@ required to achieve the proposed trace. #### Creation Instrumentation SHOULD create a new span and populate the -[CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.1/extensions/distributed-tracing.md) +[CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/extensions/distributed-tracing.md) on the event. This applies when: - A CloudEvent is created by the instrumented library. From 704059fbd783f719d16c82e815e5bc52c4821f9e Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Thu, 10 Mar 2022 15:20:00 +0100 Subject: [PATCH 21/25] Update links to point to the new CloudEvents spec --- semantic_conventions/trace/cloudevents.yaml | 10 +++++----- .../trace/semantic_conventions/cloudevents.md | 10 +++++----- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/semantic_conventions/trace/cloudevents.yaml b/semantic_conventions/trace/cloudevents.yaml index 3f62a6568ff..6a6f6c9a7fd 100644 --- a/semantic_conventions/trace/cloudevents.yaml +++ b/semantic_conventions/trace/cloudevents.yaml @@ -10,28 +10,28 @@ groups: type: string required: always brief: > - The [event_id](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#id) uniquely identifies the event. + The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event. examples: ['123e4567-e89b-12d3-a456-426614174000', '0001'] - id: event_source type: string required: always brief: > - The [source](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#source-1) identifies the context in which an event happened. + The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened. examples: ['https://github.com/cloudevents', '/cloudevents/spec/pull/123', 'my-service' ] - id: event_spec_version type: string required: always brief: > - The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#specversion) which the event uses. + The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses. examples: '1.0' - id: event_type type: string required: always brief: > - The [event_type](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#type) contains a value describing the type of event related to the originating occurrence. + The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence. examples: ['com.github.pull_request.opened', 'com.example.object.deleted.v2'] - id: event_subject type: string brief: > - The [subject](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#subject) of the event in the context of the event producer (identified by source). + The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source). examples: 'mynewfile.jpg' diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index 5ee7f9f6aae..2f9648b261b 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -189,9 +189,9 @@ The following attributes are applicable to creation and processing Spans. | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| -| `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#id) uniquely identifies the event. | `123e4567-e89b-12d3-a456-426614174000`; `0001` | Yes | -| `cloudevents.event_source` | string | The [source](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | Yes | -| `cloudevents.event_spec_version` | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#specversion) which the event uses. | `1.0` | Yes | -| `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | Yes | -| `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.1/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | No | +| `cloudevents.event_id` | string | The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event. | `123e4567-e89b-12d3-a456-426614174000`; `0001` | Yes | +| `cloudevents.event_source` | string | The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened. | `https://github.com/cloudevents`; `/cloudevents/spec/pull/123`; `my-service` | Yes | +| `cloudevents.event_spec_version` | string | The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses. | `1.0` | Yes | +| `cloudevents.event_type` | string | The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence. | `com.github.pull_request.opened`; `com.example.object.deleted.v2` | Yes | +| `cloudevents.event_subject` | string | The [subject](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#subject) of the event in the context of the event producer (identified by source). | `mynewfile.jpg` | No | From 7ec8648b2dc258c85e025d4ebddc601afca71b94 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Thu, 10 Mar 2022 15:40:01 +0100 Subject: [PATCH 22/25] Address PR comments --- .../trace/semantic_conventions/cloudevents.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index 2f9648b261b..c7e30491ef9 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -166,9 +166,12 @@ In case a CloudEvent is passed to the instrumented library with the Distributed Tracing Extension already populated, instrumentation MUST NOT create a span and MUST NOT modify the Distributed Tracing Extension on the event. -**Span name:** `CloudEvents Create ` +- Span name: `CloudEvents Create ` -**Span kind:** PRODUCER +- Span kind: PRODUCER + +- Span attributes: Instrumentation MUST add the required attributes defined +in the [table below](#attributes). #### Processing @@ -178,9 +181,12 @@ instrumentation SHOULD create a new span to trace it. Instrumentation SHOULD set the remote trace context from the Distributed Tracing Extension as a link on the processing span. -**Span name:** `CloudEvents Process ` +- Span name: `CloudEvents Process ` + +- Span kind: CONSUMER -**Span kind:** CONSUMER +- Span attributes: Instrumentation MUST add the required attributes defined +in the [table below](#attributes). ### Attributes From 7cf0a88d2b62a4dce3b2ca73bbb432a6080a2c87 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Thu, 10 Mar 2022 15:45:45 +0100 Subject: [PATCH 23/25] Improve diagram spaces a bit --- .../trace/semantic_conventions/cloudevents.md | 60 +++++++++---------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index c7e30491ef9..4262a8d3375 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -42,16 +42,16 @@ trace model is not sufficient to produce a meaningful trace. Consider the following scenario: ``` - +----------+ +--------------+ - | Producer | ---------------> | Intermediary | - +----------+ +--------------+ - | - | - | - v - +----------+ +----------+ - | Consumer | <----------------- | Queue | - +----------+ +----------+ ++----------+ +--------------+ +| Producer | ---------------> | Intermediary | ++----------+ +--------------+ + | + | + | + v ++----------+ +----------+ +| Consumer | <----------------- | Queue | ++----------+ +----------+ ``` With the traditional parent-child trace model, the above scenario would produce @@ -60,26 +60,26 @@ starts receiving (and thus has to specify a parent span) before it receives the It is not possible to correlate a producer with a consumer(s) solely via a parent-child relationship. ``` -+---------------------------------------------------+ -| Trace 1 | -| | -| +---------------------------------------+ | -| | Send (auto-instr) | | -| +---------------------------------------+ | -| +------------------------------------+ | -| | Intermediary: Received (auto-instr)| | -| +------------------------------------+ | -| +------------------------------------+ | -| | Intermediary: Send (auto-instr) | | -| +------------------------------------+ | -| | -| Trace 2 | -| | -| +---------------------------------------+ | -| | Consumer: Receive (auto-instr) | | -| +---------------------------------------+ | -| | -+---------------------------------------------------+ ++-------------------------------------------------+ +| Trace 1 | +| | +| +---------------------------------------+ | +| | Send (auto-instr) | | +| +---------------------------------------+ | +| +------------------------------------+ | +| | Intermediary: Received (auto-instr)| | +| +------------------------------------+ | +| +------------------------------------+ | +| | Intermediary: Send (auto-instr) | | +| +------------------------------------+ | +| | +| Trace 2 | +| | +| +---------------------------------------+ | +| | Consumer: Receive (auto-instr) | | +| +---------------------------------------+ | +| | ++-------------------------------------------------+ ``` This document defines semantic conventions to model the different stages From 5d2585d75c5b44bccd5ae682d7d874de0c52187f Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Thu, 10 Mar 2022 15:50:40 +0100 Subject: [PATCH 24/25] Improve diagram spaces a bit --- .../trace/semantic_conventions/cloudevents.md | 24 +++++++++++-------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index 4262a8d3375..5e9ab2e3386 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -42,16 +42,20 @@ trace model is not sufficient to produce a meaningful trace. Consider the following scenario: ``` -+----------+ +--------------+ -| Producer | ---------------> | Intermediary | -+----------+ +--------------+ - | - | - | - v -+----------+ +----------+ -| Consumer | <----------------- | Queue | -+----------+ +----------+ ++--------------------------------------------------+ +| | +| +----------+ +--------------+ | +| | Producer | ---------------> | Intermediary | | +| +----------+ +--------------+ | +| | | +| | | +| | | +| v | +| +----------+ +----------+ | +| | Consumer | <----------------- | Queue | | +| +----------+ +----------+ | +| | ++--------------------------------------------------+ ``` With the traditional parent-child trace model, the above scenario would produce From 714543a8963eea5f7cf7ebbe8efa29f52a3dae78 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Thu, 10 Mar 2022 16:26:17 +0100 Subject: [PATCH 25/25] Address PR comments --- .../trace/semantic_conventions/cloudevents.md | 25 ++++++++----------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/specification/trace/semantic_conventions/cloudevents.md b/specification/trace/semantic_conventions/cloudevents.md index 5e9ab2e3386..bddf3ea79a9 100644 --- a/specification/trace/semantic_conventions/cloudevents.md +++ b/specification/trace/semantic_conventions/cloudevents.md @@ -42,20 +42,16 @@ trace model is not sufficient to produce a meaningful trace. Consider the following scenario: ``` -+--------------------------------------------------+ -| | -| +----------+ +--------------+ | -| | Producer | ---------------> | Intermediary | | -| +----------+ +--------------+ | -| | | -| | | -| | | -| v | -| +----------+ +----------+ | -| | Consumer | <----------------- | Queue | | -| +----------+ +----------+ | -| | -+--------------------------------------------------+ ++----------+ +--------------+ +| Producer | ---------------> | Intermediary | ++----------+ +--------------+ + | + | + | + v ++----------+ +----------+ +| Consumer | <----------------- | Queue | ++----------+ +----------+ ``` With the traditional parent-child trace model, the above scenario would produce @@ -184,6 +180,7 @@ instrumentation SHOULD create a new span to trace it. Instrumentation SHOULD set the remote trace context from the Distributed Tracing Extension as a link on the processing span. +Instrumentation MAY add attributes to the link to further describe it. - Span name: `CloudEvents Process `