Skip to content

Commit 2e0c423

Browse files
yordisyordis
committed
feat(extensions): add event tracing extension with correlationid and causationid
closes #25 Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
1 parent 94c622d commit 2e0c423

File tree

3 files changed

+241
-0
lines changed

3 files changed

+241
-0
lines changed

‎cloudevents/extensions/correlation.md‎

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
# Event Correlation
2+
3+
This extension defines attributes for tracking occurrence relationships and
4+
causality in distributed systems, enabling comprehensive traceability through
5+
correlation and causation identifiers.
6+
7+
## Notational Conventions
8+
9+
As with the main [CloudEvents specification](../spec.md), the key words "MUST",
10+
"MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
11+
"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as
12+
described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
13+
14+
## Attributes
15+
16+
### correlationid
17+
18+
- Type: `String`
19+
- Description: An identifier that groups related events within the same logical
20+
flow or business transaction. All events sharing the same correlation ID are
21+
part of the same workflow.
22+
- Constraints
23+
- OPTIONAL
24+
- If present, MUST be a non-empty string
25+
26+
### causationid
27+
28+
- Type: `String`
29+
- Description: The unique identifier of the event that directly caused this
30+
event to be generated. This SHOULD be the `id` value of the causing event.
31+
- Constraints
32+
- OPTIONAL
33+
- If present, MUST be a non-empty string
34+
35+
## Usage
36+
37+
The Event Tracing extension provides two complementary mechanisms for tracking
38+
event relationships:
39+
40+
1. **Correlation ID**: Groups all events that are part of the same logical flow,
41+
regardless of their causal relationships
42+
2. **Causation ID**: Tracks the direct parent-child relationships between events
43+
in a causal chain
44+
45+
These attributes can be used independently or together, depending on the tracing
46+
requirements of your system.
47+
48+
### Correlation vs Causation
49+
50+
Understanding the distinction between these two concepts is crucial:
51+
52+
- **Correlation ID** answers: "Which events are part of the same business
53+
transaction?"
54+
- **Causation ID** answers: "Which specific event directly triggered this
55+
event?"
56+
57+
### Example Scenario
58+
59+
Consider an e-commerce order processing flow:
60+
61+
1. User initiates checkout (correlation ID: "txn-abc-123" is created)
62+
2. Order is placed (Event A)
63+
3. Payment is processed (Event B, caused by A)
64+
4. Inventory is checked (Event C, caused by A)
65+
5. Shipping is scheduled (Event D, caused by C)
66+
6. Notification is sent (Event E, caused by D)
67+
68+
In this scenario:
69+
70+
- All events share the same `correlationid`: "txn-abc-123"
71+
- Each event has a `causationid` pointing to its direct trigger:
72+
- Event B and C have `causationid`: "order-123" (Event A's ID)
73+
- Event D has `causationid`: "inventory-456" (Event C's ID)
74+
- Event E has `causationid`: "shipping-789" (Event D's ID)
75+
76+
## Examples
77+
78+
### Example 1: Complete Tracing Chain
79+
80+
Initial Order Event:
81+
82+
```json
83+
{
84+
"specversion": "1.0",
85+
"type": "com.example.order.placed",
86+
"source": "https://example.com/orders",
87+
"id": "order-123",
88+
"correlationid": "txn-abc-123",
89+
"data": {
90+
"orderId": "123",
91+
"customerId": "456"
92+
}
93+
}
94+
```
95+
96+
Payment Processing (triggered by order):
97+
98+
```json
99+
{
100+
"specversion": "1.0",
101+
"type": "com.example.payment.processed",
102+
"source": "https://example.com/payments",
103+
"id": "payment-789",
104+
"correlationid": "txn-abc-123",
105+
"causationid": "order-123",
106+
"data": {
107+
"amount": 150.0,
108+
"currency": "USD"
109+
}
110+
}
111+
```
112+
113+
Inventory Check (also triggered by order):
114+
115+
```json
116+
{
117+
"specversion": "1.0",
118+
"type": "com.example.inventory.checked",
119+
"source": "https://example.com/inventory",
120+
"id": "inventory-456",
121+
"correlationid": "txn-abc-123",
122+
"causationid": "order-123",
123+
"data": {
124+
"items": ["sku-001", "sku-002"],
125+
"available": true
126+
}
127+
}
128+
```
129+
130+
Shipping Scheduled (triggered by inventory check):
131+
132+
```json
133+
{
134+
"specversion": "1.0",
135+
"type": "com.example.shipping.scheduled",
136+
"source": "https://example.com/shipping",
137+
"id": "shipping-012",
138+
"correlationid": "txn-abc-123",
139+
"causationid": "inventory-456",
140+
"data": {
141+
"carrier": "FastShip",
142+
"estimatedDelivery": "2024-01-15"
143+
}
144+
}
145+
```
146+
147+
### Example 2: Error Handling with Tracing
148+
149+
When an error occurs, the tracing attributes help identify both the affected
150+
transaction and the specific trigger:
151+
152+
```json
153+
{
154+
"specversion": "1.0",
155+
"type": "com.example.payment.failed",
156+
"source": "https://example.com/payments",
157+
"id": "error-345",
158+
"correlationid": "txn-abc-123",
159+
"causationid": "payment-789",
160+
"data": {
161+
"error": "Insufficient funds",
162+
"retryable": true
163+
}
164+
}
165+
```
166+
167+
### Example 3: Fan-out Pattern
168+
169+
A single event can cause multiple downstream events:
170+
171+
```json
172+
{
173+
"specversion": "1.0",
174+
"type": "com.example.order.fulfilled",
175+
"source": "https://example.com/fulfillment",
176+
"id": "fulfillment-567",
177+
"correlationid": "txn-abc-123",
178+
"causationid": "shipping-012",
179+
"data": {
180+
"completedAt": "2024-01-14T10:30:00Z"
181+
}
182+
}
183+
```
184+
185+
This might trigger multiple notification events, all with the same causationid:
186+
187+
```json
188+
{
189+
"specversion": "1.0",
190+
"type": "com.example.notification.email",
191+
"source": "https://example.com/notifications",
192+
"id": "notify-email-890",
193+
"correlationid": "txn-abc-123",
194+
"causationid": "fulfillment-567",
195+
"data": {
196+
"recipient": "customer@example.com",
197+
"template": "order-fulfilled"
198+
}
199+
}
200+
```
201+
202+
```json
203+
{
204+
"specversion": "1.0",
205+
"type": "com.example.notification.sms",
206+
"source": "https://example.com/notifications",
207+
"id": "notify-sms-891",
208+
"correlationid": "txn-abc-123",
209+
"causationid": "fulfillment-567",
210+
"data": {
211+
"recipient": "+1234567890",
212+
"message": "Your order has been fulfilled!"
213+
}
214+
}
215+
```
216+
217+
## Best Practices
218+
219+
1. **Correlation ID Generation**: Generate correlation IDs at the entry point of
220+
your system (e.g., API gateway, UI interaction)
221+
2. **Causation ID Propagation**: Always set the causation ID to the `id` of the
222+
event that directly triggered the current event
223+
3. **Consistent Usage**: If you start using these attributes in a flow, use them
224+
consistently throughout
225+
4. **ID Format**: Use globally unique identifiers (e.g., UUIDs) to avoid
226+
collisions across distributed systems
227+
5. **Retention**: Consider the retention implications when designing queries
228+
based on these attributes

‎cloudevents/languages/he/extensions/correlation.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Dataref (Claim Check Pattern)
2+
3+
מסמך זה טרם תורגם. בבקשה תשתמשו [בגרסה האנגלית של המסמך](../../../extensions/correlation.md) לבינתיים.
4+
5+
אם ברצונכם להציע תרגום לעברית, ניתן לעשות זאת באמצעות [פתיחת issue](https://github.com/cloudevents/spec/issues) בגיטהאב.
6+
7+
אנו מבקשים מכם להציע תרגום לעברית בלבד, ולא להציע תרגום לאנגלית.

‎cloudevents/languages/zh-CN/extensions/correlation.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Event Correlation
2+
3+
本文档尚未被翻译，请先阅读英文[原版文档](../../../extensions/correlation.md) 。
4+
5+
如果您迫切地需要此文档的中文翻译，请[提交一个 issue](https://github.com/cloudevents/spec/issues) ，
6+
我们会尽快安排专人进行翻译。

0 commit comments

Comments
 (0)