Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

CloudEvents should re-use existing HTTP or messaging conventions #1182

Merged
merged 10 commits into from
Jul 16, 2024
Merged

CloudEvents should re-use existing HTTP or messaging conventions #1182

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
d35f451
CloudEvents should re-use existing HTTP or messaging conventions
joaopgrassi Jun 26, 2024
9a876ad
Add changelog
joaopgrassi Jun 26, 2024
eeca3ea
Change things around
joaopgrassi Jun 28, 2024
ad3506c
Remove .
joaopgrassi Jun 28, 2024
ef6ad5f
Simplify and only mention messaging conventions
joaopgrassi Jul 11, 2024
07605cc
Merge branch 'main' into cloud-events-restructure
joaopgrassi Jul 11, 2024
b311f45
Merge branch 'main' into cloud-events-restructure
joaopgrassi Jul 15, 2024
4e72946
Merge branch 'main' into cloud-events-restructure
joaopgrassi Jul 15, 2024
373f4be
Merge branch 'main' into cloud-events-restructure
joaopgrassi Jul 15, 2024
1ea1f4e
Merge branch 'main' into cloud-events-restructure
joaopgrassi Jul 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .chloggen/cloud-events-restructure.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
change_type: 'enhancement'
component: cloudevents
note: CloudEvents conventions to follow HTTP/Messaging Span conventions
issues: [654]
subtext:
174 changes: 14 additions & 160 deletions docs/cloudevents/cloudevents-spans.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,8 @@ linkTitle: CloudEvents Spans
<!-- toc -->

- [Definitions](#definitions)
- [Overview](#overview)
- [Conventions](#conventions)
- [Spans](#spans)
- [Creation](#creation)
- [Processing](#processing)
- [Attributes](#attributes)
- [Span attributes](#span-attributes)

<!-- tocstop -->

Expand All @@ -35,168 +31,26 @@ 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
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.
joaopgrassi marked this conversation as resolved.
Show resolved Hide resolved

#### Creation

Instrumentation SHOULD create a new span and populate the
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)
joaopgrassi marked this conversation as resolved.
Show resolved Hide resolved
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 <event_type>`

- 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 <event_type>`

- Span kind: CONSUMER
as means to propagate the trace context.

- Span attributes: Instrumentation MUST add the required attributes defined
in the [table below](#attributes).
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).
joaopgrassi marked this conversation as resolved.
Show resolved Hide resolved

### Attributes
The remainder of this section describes additional CloudEvents attributes
that can be recorded on spans.

The following attributes are applicable to creation and processing Spans.
### Span attributes

<!-- prettier-ignore-start -->
<!-- semconv cloudevents -->
Expand Down
Loading