From d35f451f165b5b8ec56ebb4f8362d3ffc6f0a9b6 Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Wed, 26 Jun 2024 12:32:59 +0200 Subject: [PATCH 1/5] CloudEvents should re-use existing HTTP or messaging conventions --- docs/cloudevents/cloudevents-spans.md | 184 ++++---------------------- 1 file changed, 25 insertions(+), 159 deletions(-) diff --git a/docs/cloudevents/cloudevents-spans.md b/docs/cloudevents/cloudevents-spans.md index ca5ea0d0e6..e409f8b98b 100644 --- a/docs/cloudevents/cloudevents-spans.md +++ b/docs/cloudevents/cloudevents-spans.md @@ -11,12 +11,8 @@ linkTitle: CloudEvents Spans - [Definitions](#definitions) -- [Overview](#overview) - [Conventions](#conventions) - - [Spans](#spans) - - [Creation](#creation) - - [Processing](#processing) - - [Attributes](#attributes) + - [Span attributes](#span-attributes) @@ -35,168 +31,38 @@ 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_%28networking%29) -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 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. - -``` -+-------------------------------------------------+ -| 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.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. - -The remainder of this section describes the semantic conventions for Spans -required to achieve the proposed trace. - -### Spans - -#### Creation - -Instrumentation SHOULD create a new span and populate the -[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. - 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. +CloudEvents can be sent via various transports, such as HTTP or via messaging +systems. Each transport defines its own mechanism of +[trace context propagation](https://opentelemetry.io/docs/concepts/context-propagation/). -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. +In HTTP for example, context is propagated via headers as specified by the +[W3C TraceContext](https://www.w3.org/TR/trace-context/) specification. Other +transports, such [MQTT](https://w3c.github.io/trace-context-mqtt/) +or [AMQP](https://w3c.github.io/trace-context-amqp/) +are also defining their own trace context propagation mechanisms. -- Span name: `CloudEvents Create ` +CloudEvent SDKs and instrumentations SHOULD rely on existing context propagation +mechanisms and follow the existing semantic conventions for each scenario. -- Span kind: PRODUCER +When sending CloudEvents via HTTP, the +[Semantic Conventions for HTTP Spans](../http/http-spans.md) SHOULD be followed. +When CloudEvents are sent via message brokers, the +[Semantic Conventions for Messaging Spans](../messaging/messaging-spans.md) +SHOULD be followed. -- Span attributes: Instrumentation MUST add the required attributes defined - in the [table below](#attributes). - -#### Processing - -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. -Instrumentation MAY add attributes to the link to further describe it. - -- Span name: `CloudEvents Process ` - -- Span kind: CONSUMER - -- Span attributes: Instrumentation MUST add the required attributes defined - in the [table below](#attributes). +When the transport being used does not have a well stablished +progation mechanism, instrumentations MAY rely on the +[CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/extensions/distributed-tracing.md). +as means to propagate the trace context, while still following either the HTTP +or Messaging span semantic conventions. -### Attributes +The remainder of this section describes additional CloudEvents attributes +that can be recorded on spans in addition to the ones defined by +the aforedmentioned conventions. -The following attributes are applicable to creation and processing Spans. +### Span attributes From 9a876ad1a8606e91c1e7be798f7f36ea6576a930 Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Wed, 26 Jun 2024 12:39:43 +0200 Subject: [PATCH 2/5] Add changelog --- .chloggen/cloud-events-restructure.yaml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100755 .chloggen/cloud-events-restructure.yaml diff --git a/.chloggen/cloud-events-restructure.yaml b/.chloggen/cloud-events-restructure.yaml new file mode 100755 index 0000000000..cbec7e070a --- /dev/null +++ b/.chloggen/cloud-events-restructure.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: 'enhancement' + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: cloudevents + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: CloudEvents conventions to follow HTTP/Messaging Span conventions + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [654] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: From eeca3eae32b9260512c7478cf4bded71749cf552 Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Fri, 28 Jun 2024 11:25:18 +0200 Subject: [PATCH 3/5] Change things around --- docs/cloudevents/cloudevents-spans.md | 38 +++++++++------------------ 1 file changed, 13 insertions(+), 25 deletions(-) diff --git a/docs/cloudevents/cloudevents-spans.md b/docs/cloudevents/cloudevents-spans.md index e409f8b98b..9959ed8c26 100644 --- a/docs/cloudevents/cloudevents-spans.md +++ b/docs/cloudevents/cloudevents-spans.md @@ -33,34 +33,22 @@ document. ## Conventions -CloudEvents can be sent via various transports, such as HTTP or via messaging -systems. Each transport defines its own mechanism of -[trace context propagation](https://opentelemetry.io/docs/concepts/context-propagation/). - -In HTTP for example, context is propagated via headers as specified by the -[W3C TraceContext](https://www.w3.org/TR/trace-context/) specification. Other -transports, such [MQTT](https://w3c.github.io/trace-context-mqtt/) -or [AMQP](https://w3c.github.io/trace-context-amqp/) -are also defining their own trace context propagation mechanisms. - -CloudEvent SDKs and instrumentations SHOULD rely on existing context propagation -mechanisms and follow the existing semantic conventions for each scenario. - -When sending CloudEvents via HTTP, the -[Semantic Conventions for HTTP Spans](../http/http-spans.md) SHOULD be followed. -When CloudEvents are sent via message brokers, the -[Semantic Conventions for Messaging Spans](../messaging/messaging-spans.md) -SHOULD be followed. - -When the transport being used does not have a well stablished -progation mechanism, instrumentations MAY rely on the +CloudEvents can be sent via various communication protocols. When the protocol +used to send CloudEvents has a well established support for trace context propagation, +instrumentations SHOULD propagate the context using this built-in mechanism. + +If CloudEvents are instrumented independently of the protocol used, +CloudEvent-specific instrumentations SHOULD use the [CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/extensions/distributed-tracing.md). -as means to propagate the trace context, while still following either the HTTP -or Messaging span semantic conventions. +as means to propagate the trace context. + +When CloudEvents are used in messaging scenarios, where an event can go through +many [hops](https://en.wikipedia.org/wiki/Hop_%28networking%29), +CloudEvent-specific instrumentations SHOULD follow the span structure described in +[Semantic Conventions for Messaging Spans](../messaging/messaging-spans.md). The remainder of this section describes additional CloudEvents attributes -that can be recorded on spans in addition to the ones defined by -the aforedmentioned conventions. +that can be recorded on spans. ### Span attributes From ad3506c97ff673b7a9d456c972ee6df05f7b0347 Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Fri, 28 Jun 2024 11:28:07 +0200 Subject: [PATCH 4/5] Remove . --- .chloggen/cloud-events-restructure.yaml | 17 ----------------- docs/cloudevents/cloudevents-spans.md | 2 +- 2 files changed, 1 insertion(+), 18 deletions(-) diff --git a/.chloggen/cloud-events-restructure.yaml b/.chloggen/cloud-events-restructure.yaml index cbec7e070a..90e15f3bc9 100755 --- a/.chloggen/cloud-events-restructure.yaml +++ b/.chloggen/cloud-events-restructure.yaml @@ -1,22 +1,5 @@ -# Use this changelog template to create an entry for release notes. -# -# If your change doesn't affect end users you should instead start -# your pull request title with [chore] or use the "Skip Changelog" label. - -# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' change_type: 'enhancement' - -# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) component: cloudevents - -# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). note: CloudEvents conventions to follow HTTP/Messaging Span conventions - -# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. -# The values here must be integers. issues: [654] - -# (Optional) One or more lines of additional information to render under the primary note. -# These lines will be padded with 2 spaces and then inserted directly into the document. -# Use pipe (|) for multiline entries. subtext: diff --git a/docs/cloudevents/cloudevents-spans.md b/docs/cloudevents/cloudevents-spans.md index 9959ed8c26..727a2342fa 100644 --- a/docs/cloudevents/cloudevents-spans.md +++ b/docs/cloudevents/cloudevents-spans.md @@ -39,7 +39,7 @@ instrumentations SHOULD propagate the context using this built-in mechanism. If CloudEvents are instrumented independently of the protocol used, CloudEvent-specific instrumentations SHOULD use the -[CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/extensions/distributed-tracing.md). +[CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/extensions/distributed-tracing.md) as means to propagate the trace context. When CloudEvents are used in messaging scenarios, where an event can go through From ef6ad5f799bd8c807530ce2d03580bd7270c5d1e Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Thu, 11 Jul 2024 11:05:43 +0200 Subject: [PATCH 5/5] Simplify and only mention messaging conventions --- docs/cloudevents/cloudevents-spans.md | 22 ++++++++-------------- 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/docs/cloudevents/cloudevents-spans.md b/docs/cloudevents/cloudevents-spans.md index 727a2342fa..79672b8e15 100644 --- a/docs/cloudevents/cloudevents-spans.md +++ b/docs/cloudevents/cloudevents-spans.md @@ -12,7 +12,7 @@ linkTitle: CloudEvents Spans - [Definitions](#definitions) - [Conventions](#conventions) - - [Span attributes](#span-attributes) +- [Span attributes](#span-attributes) @@ -33,24 +33,18 @@ document. ## Conventions -CloudEvents can be sent via various communication protocols. When the protocol -used to send CloudEvents has a well established support for trace context propagation, -instrumentations SHOULD propagate the context using this built-in mechanism. +CloudEvent-specific instrumentations SHOULD follow the span structure described in +the [Semantic Conventions for Messaging Spans](../messaging/messaging-spans.md). -If CloudEvents are instrumented independently of the protocol used, -CloudEvent-specific instrumentations SHOULD use the +If CloudEvents are instrumented independently of the above conventions, +instrumentations can rely on the [CloudEvents Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/extensions/distributed-tracing.md) as means to propagate the trace context. -When CloudEvents are used in messaging scenarios, where an event can go through -many [hops](https://en.wikipedia.org/wiki/Hop_%28networking%29), -CloudEvent-specific instrumentations SHOULD follow the span structure described in -[Semantic Conventions for Messaging Spans](../messaging/messaging-spans.md). - -The remainder of this section describes additional CloudEvents attributes -that can be recorded on spans. +## Span attributes -### Span attributes +Additionally, instrumentations may record the following CloudEvent-specific +attributes on spans created from the conventions described above.