Skip to content

Commit 23d2782

Browse files
soccermaxMax Gruenfelder
soccermax
and
Max Gruenfelder
authoredMar 18, 2025··
Propagate Trace Context between publish and processing of events (#306)
* trace context * trace context * trace context * trace context * trace context * trace context * trace context * trace context * trace context * trace context * trace context * trace context * trace context * wip * wip * docu * docu * docu * docu * docu * rename telemetry parameter * wip * wip * wip --------- Co-authored-by: Max Gruenfelder <maximilian.gruenfelder@sap.com>
·
v1.10.0-beta.51.10.0-beta.0
1 parent f258f92 commit 23d2782

28 files changed

+509
-167
lines changed
 

‎CHANGELOG.md

+4
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
77

88
## v1.9.2 - 2025-03-XX
99

10+
### Added
11+
12+
- propagate W3TraceContext from event creation to event-processing
13+
1014
### Changed
1115

1216
- Updated cron-parser to major version ^5.0.0

‎db/Event.cds

+2
Original file line numberDiff line numberDiff line change
@@ -23,4 +23,6 @@ entity Event: cuid {
2323
lastAttemptTimestamp: Timestamp;
2424
createdAt: Timestamp @cds.on.insert : $now;
2525
startAfter: Timestamp;
26+
context: LargeString;
27+
error: String;
2628
}

‎docs/configure-event/index.md

+1
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,7 @@ instance is overloaded.
137137
| appNames | Specifies the application names on which the event should be processed. The application name is extracted from the environment variable `VCAP_APPLICATION`. If not defined, the event is processed on all connected applications. | null |
138138
| appInstances | Specifies the application instance numbers on which the event should be processed. The instance number is extracted from the environment variable `CF_INSTANCE_INDEX`. If not defined, the event is processed on all instances of the connected applications. | null |
139139
| keepAliveInterval | Specifies the interval (in seconds) at which keep-alive signals are sent during event processing to monitor system health. | 60 |
140+
| inheritTraceContext | Determines whether the trace context is propagated during event publishing and processing. If set to `false`, trace context propagation is disabled for the event. | true |
140141

141142
## Configuration
142143

‎docs/implement-event/index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: Implement Event
4-
nav_order: 8
4+
nav_order: 9
55
---
66

77
<!-- prettier-ignore-start -->

‎docs/load-balancing/index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: Load Balancing
4-
nav_order: 6
4+
nav_order: 7
55
---
66

77
<!-- prettier-ignore-start -->

‎docs/publish-event/index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: Publishing of Events
4-
nav_order: 7
4+
nav_order: 8
55
---
66

77
<!-- prettier-ignore-start -->

‎docs/setup/index.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ nav_order: 3
1414
<!-- prettier-ignore -->
1515

1616
- TOC
17-
{: toc}
17+
{: toc}
1818

1919
<!-- prettier-ignore-end -->
2020

@@ -80,7 +80,7 @@ The table includes the parameter name, a description of its purpose, and the def
8080
| cleanupLocksAndEventsForDev | Deletes all semantic locks and sets all events that are in progress to error during server start. This is used to clean up leftovers from server crashes or restarts during processing. | false | no |
8181
| redisOptions | The option is provided to customize settings when creating Redis clients. The object is spread at the root level for creating a client and within the `default` options for cluster clients. | {} | no |
8282
| insertEventsBeforeCommit | If enabled, this feature allows events (including those for outboxed services) to be inserted in bulk using the before commit handler. This is performed to improve performance by mass inserting events instead of single insert operations. This can be disabled by the parameter `skipInsertEventsBeforeCommit` in the function publishEvent. | false | yes |
83-
| enableCAPTelemetry | If enabled in combination with `cap-js/telemetry`, OpenTelemetry traces about all event-queue activities are written using the `cap-js/telemetry` tracer. | false | yes |
83+
| enableTelemetry | If enabled, OpenTelemetry traces for all event-queue activities are written. An OpenTelemetry exporter must be configured. | true | yes |
8484
| cronTimezone | Determines whether to apply the central `cronTimezone` setting for scheduling events. If set to `true` and the property `utc` is not enabled for the given event, it will use the defined `cronTimezone`. If set to `false`, the event will use UTC or the server's local time, based on the `utc` setting. | null | yes |
8585
| publishEventBlockList | Determines whether the publication of events to all app instances is enabled when Redis is active. If set to true, events can be published; if set to false, the publication is disabled. | true | yes |
8686
| crashOnRedisUnavailable | If enabled, the application will crash if Redis is unavailable during the connection check. | false | false |

‎docs/status-handling/index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: Event Status Handling
4-
nav_order: 10
4+
nav_order: 11
55
---
66

77
<!-- prettier-ignore-start -->

‎docs/telemetry/img_1.png

80.9 KB
Loading

‎docs/telemetry/index.md

+97
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
layout: default
3+
title: Telemetry
4+
nav_order: 6
5+
---
6+
7+
<!-- prettier-ignore-start -->
8+
9+
{: .no_toc}
10+
11+
# Telemetry Insights
12+
13+
<!-- prettier-ignore -->
14+
15+
- TOC
16+
{: toc}
17+
18+
<!-- prettier-ignore-end -->
19+
20+
The `@cap-js-community/event-queue` module comes with built-in support for OpenTelemetry, enabling seamless tracing and
21+
observability of event processing. With this integration, you can track events from publication to execution, ensuring
22+
full visibility into your system’s event flow.
23+
24+
## Key Features
25+
26+
- **Automatic Event Tracing** – Captures OpenTelemetry traces for event execution, helping you analyze processing times
27+
- and dependencies.
28+
- **Trace Context Propagation** – Preserves the OpenTelemetry tracing context when events are published and processed,
29+
- maintaining a clear linkage across distributed systems.
30+
- **End-to-End Monitoring** – Ensures that traceability is maintained from the moment an event is created until it is
31+
- fully processed.
32+
33+
## How It Works
34+
35+
1. **Publishing an Event**
36+
37+
- When an event is published, the current OpenTelemetry trace context is extracted.
38+
- If no trace context is present, a new one is automatically created.
39+
- The trace context is then attached to the event metadata.
40+
41+
2. **Processing an Event**
42+
- Upon processing, the previously stored trace context is retrieved.
43+
- If no trace context exists, a new one is generated to ensure traceability.
44+
- Periodic Events never have a existing trace context
45+
- The trace context is injected back into the OpenTelemetry framework, maintaining continuity.
46+
47+
## Benefits
48+
49+
- **Comprehensive Observability** – Gain insight into event-driven workflows across different services.
50+
- **Easier Debugging** – Quickly pinpoint performance issues and failure points.
51+
- **Seamless Integration** – Compatible with OpenTelemetry-based monitoring tools with minimal setup.
52+
53+
## Configuration
54+
55+
By default, OpenTelemetry tracing is enabled if an OpenTelemetry exporter is set up or if Dynatrace OneAgent is
56+
configured to export traces. However, the OpenTelemetry API must always be installed in the project.
57+
58+
### Trace Context Propagation
59+
60+
The propagation of the trace context can be controlled on an event level using the parameter `inheritTraceContext`.
61+
By default, this is set to `true`, meaning the trace context will be inherited and propagated during event publishing
62+
and processing. If set to `false`, the trace context propagation will be disabled for that particular event.
63+
64+
### Disabling Telemetry
65+
66+
Complete telemetry support can be disabled globally with the initialization parameter `enableTelemetry`. The default
67+
value is `true`, meaning telemetry is enabled. If set to `false`, all telemetry features, including OpenTelemetry
68+
tracing, will be disabled for the event-queue.
69+
70+
For more advanced configurations, refer to the OpenTelemetry documentation on context propagation and trace exporters.
71+
This integration also works smoothly with `@cap-js/telemetry`, meaning that if `@cap-js/telemetry` is configured, trace
72+
exporting works out of the box with no additional setup.
73+
74+
## Pitfalls with OpenTelemetry Tracing and Dynatrace OneAgent
75+
76+
When using Dynatrace OneAgent for trace exporting without a separate OpenTelemetry exporter, there are some important
77+
limitations to be aware of:
78+
79+
- **Dependency on Dynatrace Trace Context**
80+
Dynatrace OneAgent only exports traces to Dynatrace if they contain a valid Dynatrace trace context. This context is
81+
automatically created when an event is published within the scope of an HTTP request or another operation captured by
82+
Dynatrace OneAgent.
83+
84+
- **Issues with Periodic and Standalone Events**
85+
Events that are triggered periodically (e.g., scheduled jobs) or published without an existing Dynatrace trace context
86+
may not be visible in Dynatrace. Since these events lack the necessary Dynatrace trace context, OneAgent does not
87+
export them unless a separate OpenTelemetry exporter is configured.
88+
89+
### Recommendation
90+
91+
To ensure visibility of all traces—including periodic events or events outside of a Dynatrace-traced request—configure
92+
a dedicated OpenTelemetry exporter alongside Dynatrace OneAgent. This guarantees that traces are properly exported even
93+
when a Dynatrace trace context is missing.
94+
95+
## Example Trace
96+
97+
![Example Trace](img_1.png)

‎docs/transaction-handling/index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: Transactional Handling
4-
nav_order: 9
4+
nav_order: 10
55
---
66

77
<!-- prettier-ignore-start -->

‎docs/unit-testing/index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: Unit Testing
4-
nav_order: 11
4+
nav_order: 12
55
---
66

77
<!-- prettier-ignore-start -->

0 commit comments

Comments
 (0)
Please sign in to comment.