cap-js-community · soccermax · Mar 18, 2025 · Mar 13, 2025 · Mar 13, 2025 · Mar 13, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## v1.9.2 - 2025-03-XX
 
+### Added
+
+- propagate W3TraceContext from event creation to event-processing
+
 ### Changed
 
 - Updated cron-parser to major version ^5.0.0

diff --git a/db/Event.cds b/db/Event.cds
@@ -23,4 +23,6 @@ entity Event: cuid {
     lastAttemptTimestamp: Timestamp;
     createdAt: Timestamp @cds.on.insert : $now;
     startAfter: Timestamp;
+    context: LargeString;
+    error: String;
 }
diff --git a/docs/configure-event/index.md b/docs/configure-event/index.md
@@ -137,6 +137,7 @@ instance is overloaded.
 | 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          |
 | 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          |
 | keepAliveInterval             | Specifies the interval (in seconds) at which keep-alive signals are sent during event processing to monitor system health.                                                                                                                                    | 60            |
+| 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          |
 
 ## Configuration
 

diff --git a/docs/implement-event/index.md b/docs/implement-event/index.md
@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Implement Event
-nav_order: 8
+nav_order: 9
 ---
 
 <!-- prettier-ignore-start -->

diff --git a/docs/load-balancing/index.md b/docs/load-balancing/index.md
@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Load Balancing
-nav_order: 6
+nav_order: 7
 ---
 
 <!-- prettier-ignore-start -->

diff --git a/docs/publish-event/index.md b/docs/publish-event/index.md
@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Publishing of Events
-nav_order: 7
+nav_order: 8
 ---
 
 <!-- prettier-ignore-start -->

diff --git a/docs/setup/index.md b/docs/setup/index.md
@@ -14,7 +14,7 @@ nav_order: 3
 <!-- prettier-ignore -->
 
 - TOC
-{: toc}
+  {: toc}
 
 <!-- prettier-ignore-end -->
 
@@ -80,7 +80,7 @@ The table includes the parameter name, a description of its purpose, and the def
 | 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                        |
 | 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                        |
 | 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                       |
-| 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                       |
+| enableTelemetry                      | If enabled, OpenTelemetry traces for all event-queue activities are written. An OpenTelemetry exporter must be configured.                                                                                                                                                                                                                       | true           | yes                       |
 | 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                       |
 | 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                       |
 | crashOnRedisUnavailable              | If enabled, the application will crash if Redis is unavailable during the connection check.                                                                                                                                                                                                                                                      | false          | false                     |

diff --git a/docs/status-handling/index.md b/docs/status-handling/index.md
@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Event Status Handling
-nav_order: 10
+nav_order: 11
 ---
 
 <!-- prettier-ignore-start -->

diff --git a/docs/telemetry/img_1.png b/docs/telemetry/img_1.png
diff --git a/docs/telemetry/index.md b/docs/telemetry/index.md
@@ -0,0 +1,97 @@
+---
+layout: default
+title: Telemetry
+nav_order: 6
+---
+
+<!-- prettier-ignore-start -->
+
+{: .no_toc}
+
+# Telemetry Insights
+
+<!-- prettier-ignore -->
+
+- TOC
+{: toc}
+
+<!-- prettier-ignore-end -->
+
+The `@cap-js-community/event-queue` module comes with built-in support for OpenTelemetry, enabling seamless tracing and
+observability of event processing. With this integration, you can track events from publication to execution, ensuring
+full visibility into your system’s event flow.
+
+## Key Features
+
+- **Automatic Event Tracing** – Captures OpenTelemetry traces for event execution, helping you analyze processing times
+- and dependencies.
+- **Trace Context Propagation** – Preserves the OpenTelemetry tracing context when events are published and processed,
+- maintaining a clear linkage across distributed systems.
+- **End-to-End Monitoring** – Ensures that traceability is maintained from the moment an event is created until it is
+- fully processed.
+
+## How It Works
+
+1. **Publishing an Event**
+
+   - When an event is published, the current OpenTelemetry trace context is extracted.
+   - If no trace context is present, a new one is automatically created.
+   - The trace context is then attached to the event metadata.
+
+2. **Processing an Event**
+   - Upon processing, the previously stored trace context is retrieved.
+   - If no trace context exists, a new one is generated to ensure traceability.
+     - Periodic Events never have a existing trace context
+   - The trace context is injected back into the OpenTelemetry framework, maintaining continuity.
+
+## Benefits
+
+- **Comprehensive Observability** – Gain insight into event-driven workflows across different services.
+- **Easier Debugging** – Quickly pinpoint performance issues and failure points.
+- **Seamless Integration** – Compatible with OpenTelemetry-based monitoring tools with minimal setup.
+
+## Configuration
+
+By default, OpenTelemetry tracing is enabled if an OpenTelemetry exporter is set up or if Dynatrace OneAgent is
+configured to export traces. However, the OpenTelemetry API must always be installed in the project.
+
+### Trace Context Propagation
+
+The propagation of the trace context can be controlled on an event level using the parameter `inheritTraceContext`.
+By default, this is set to `true`, meaning the trace context will be inherited and propagated during event publishing
+and processing. If set to `false`, the trace context propagation will be disabled for that particular event.
+
+### Disabling Telemetry
+
+Complete telemetry support can be disabled globally with the initialization parameter `enableTelemetry`. The default
+value is `true`, meaning telemetry is enabled. If set to `false`, all telemetry features, including OpenTelemetry
+tracing, will be disabled for the event-queue.
+
+For more advanced configurations, refer to the OpenTelemetry documentation on context propagation and trace exporters.
+This integration also works smoothly with `@cap-js/telemetry`, meaning that if `@cap-js/telemetry` is configured, trace
+exporting works out of the box with no additional setup.
+
+## Pitfalls with OpenTelemetry Tracing and Dynatrace OneAgent
+
+When using Dynatrace OneAgent for trace exporting without a separate OpenTelemetry exporter, there are some important
+limitations to be aware of:
+
+- **Dependency on Dynatrace Trace Context**  
+  Dynatrace OneAgent only exports traces to Dynatrace if they contain a valid Dynatrace trace context. This context is
+  automatically created when an event is published within the scope of an HTTP request or another operation captured by
+  Dynatrace OneAgent.
+
+- **Issues with Periodic and Standalone Events**  
+  Events that are triggered periodically (e.g., scheduled jobs) or published without an existing Dynatrace trace context
+  may not be visible in Dynatrace. Since these events lack the necessary Dynatrace trace context, OneAgent does not
+  export them unless a separate OpenTelemetry exporter is configured.
+
+### Recommendation
+
+To ensure visibility of all traces—including periodic events or events outside of a Dynatrace-traced request—configure
+a dedicated OpenTelemetry exporter alongside Dynatrace OneAgent. This guarantees that traces are properly exported even
+when a Dynatrace trace context is missing.
+
+## Example Trace
+
+![Example Trace](img_1.png)
diff --git a/docs/transaction-handling/index.md b/docs/transaction-handling/index.md
@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Transactional Handling
-nav_order: 9
+nav_order: 10
 ---
 
 <!-- prettier-ignore-start -->

diff --git a/docs/unit-testing/index.md b/docs/unit-testing/index.md
@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Unit Testing
-nav_order: 11
+nav_order: 12
 ---
 
 <!-- prettier-ignore-start -->