Introduce new semantic conventions for CloudEvents

CHANGELOG.md

@@ -35,10 +35,11 @@ release.
 
 ### Semantic Conventions
 
-- Prohibit usage of retired names in semantic conventions.
-  ([#2191](https://github.com/open-telemetry/opentelemetry-specification/pull/2191))
-- Add `device.manufacturer` to describe mobile device manufacturers.
-  ([2100](https://github.com/open-telemetry/opentelemetry-specification/pull/2100))
+- Changed `rpc.system` to an enum (allowing custom values), and changed the
+  `rpc.system` value for .NET WCF from `wcf` to `dotnet_wcf`.
+  ([#2377](https://github.com/open-telemetry/opentelemetry-specification/pull/2377))
+- Define JavaScript runtime semantic conventions.
+  ([#2290](https://github.com/open-telemetry/opentelemetry-specification/pull/2290))
 - Add semantic conventions for [CloudEvents](https://cloudevents.io).
   ([#1978](https://github.com/open-telemetry/opentelemetry-specification/pull/1978))
 

semantic_conventions/trace/cloudevents.yaml

@@ -8,25 +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.
-        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
+        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']

specification/trace/semantic_conventions/cloudevents.md

@@ -2,33 +2,152 @@
 
 **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.
+<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
 
-## Overview
+<!-- toc -->
 
-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).
+- [Definitions](#definitions)
+- [Overview](#overview)
+- [Conventions](#conventions)
+  * [Spans](#spans)
+    + [Creation](#creation)
+    + [Processing](#processing)
+  * [Attributes](#attributes)
 
-Once the trace context is set on the event, it MUST not be modified.
+<!-- tocstop -->
 
-<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
+## Definitions
 
-<!-- toc -->
+ From the
+ [CloudEvents specification:](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#overview)
 
-- [Spans](#spans)
-  * [Creation](#creation)
-  * [Processing](#processing)
-- [Instrumentation](#instrumentation)
-- [Attributes](#attributes)
+> CloudEvents is a specification for describing event data in common formats
+to provide interoperability across services, platforms and systems.
+>
 
-<!-- tocstop -->
+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.
+
+## Overview
+
+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
+following questions:
+
+- What components in a system reacted to an event
+- What further events were sent due to an incoming event
+- Which event caused the exception
+
+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.
 
-## Spans
+The remainder of this section describes the semantic conventions for Spans
+required to achieve the proposed trace.
 
-### Creation
+### Spans
+
+#### 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)
@@ -47,9 +166,10 @@ 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 <event_type>`
+
 **Span kind:** PRODUCER
 
-### Processing
+#### Processing
 
 When an instrumented library supports processing of a single CloudEvent,
 instrumentation SHOULD create a new span to trace it.
@@ -58,28 +178,19 @@ Instrumentation SHOULD set the remote trace context from the
 Distributed Tracing Extension as a link on the processing span.
 
 **Span name:** `CloudEvents Process <event_type>`
-**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
+### Attributes
 
 The following attributes are applicable to creation and processing Spans.
 
 <!-- semconv cloudevents -->
 | 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_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 |
-
-**[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.
 <!-- endsemconv -->