From 02ecf0c71e9fa74d09d81c48e04a132db2b7060b Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Tue, 16 Jul 2024 09:13:08 +0200 Subject: [PATCH] CloudEvents should re-use existing HTTP or messaging conventions (#1182) --- .chloggen/cloud-events-restructure.yaml | 5 + docs/cloudevents/cloudevents-spans.md | 170 ++---------------------- 2 files changed, 14 insertions(+), 161 deletions(-) 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..90e15f3bc9 --- /dev/null +++ b/.chloggen/cloud-events-restructure.yaml @@ -0,0 +1,5 @@ +change_type: 'enhancement' +component: cloudevents +note: CloudEvents conventions to follow HTTP/Messaging Span conventions +issues: [654] +subtext: diff --git a/docs/cloudevents/cloudevents-spans.md b/docs/cloudevents/cloudevents-spans.md index ca5ea0d0e6..79672b8e15 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,20 @@ 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 +CloudEvent-specific instrumentations SHOULD follow the span structure described in +the [Semantic Conventions for Messaging Spans](../messaging/messaging-spans.md). -#### Creation - -Instrumentation SHOULD create a new span and populate 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) -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. - -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 - -- 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). +as means to propagate the trace context. -### Attributes +## Span attributes -The following attributes are applicable to creation and processing Spans. +Additionally, instrumentations may record the following CloudEvent-specific +attributes on spans created from the conventions described above.