feat: Add OpenTelemetry instrumentation for event handlers

[yordis]

Signed-off-by: Yordis Prieto yordis.prieto@gmail.com

[cursor]

PR Summary

Adds first-class OpenTelemetry tracing integration for Commanded event processing.

• New Commanded.OpenTelemetry module to attach telemetry handlers and create spans for event.handle and event.batch with configurable :span_relationship (:link, :child, :none) and tracer name
• Implements Commanded.OpenTelemetry.EventHandler, ...Helper, and ...CommandedAttributes to generate spans, set attributes (OTel SemConv + commanded.*), handle errors/exceptions, and support span links/parenting
• Enhances Commanded.Middleware.TraceContextPropagator with docs/specs to inject W3C traceparent/tracestate into command metadata
• Adds required deps: opentelemetry_api, opentelemetry_telemetry, opentelemetry_semantic_conventions, and nimble_options; updates docs grouping and dialyzer config
• Documentation: explanation and a new how-to guide for setup and span relationship configuration
• Tests: comprehensive OTel setup, helper, and event handler coverage; adds OTel test case harness

^{Written by Cursor Bugbot for commit 3c15139. This will update automatically on new commits. Configure here.}

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cursor]

Test cleanup uses wrong telemetry handler query

The on_exit callback uses :telemetry.list_handlers([]) which lists handlers for the event named [] (an empty list), not all handlers. This cleanup is ineffective. The individual test files correctly use explicit event names like [:commanded, :event, :handle, :start] in their detach_handlers/0 functions. The same pattern should be used here.

 

[cursor]

Context leakage in child span relationship mode

The safe_context_propagation function uses :otel_propagator_text_map.extract/1 which modifies the current process context as a side effect. When an event with a traceparent is processed, that trace context persists in the process dictionary. If a subsequent event has no traceparent, safe_context_propagation returns nil without clearing the old context, causing the new event's span to incorrectly become a child of the previous event's trace. This results in incorrect trace relationships in the tracing backend. The fix would be to use extract_to/2 like extract_span_context_for_link does, extracting into a fresh context without modifying the process dictionary.

Additional Locations (1)

• lib/commanded/opentelemetry/event_handler.ex#L88-L92

 

[cursor]

Setup ignores first telemetry attach result

The setup/1 function's spec declares it returns :ok | {:error, :already_exists}, but the implementation ignores the return value of the first :telemetry.attach_many call for single event handlers (line 29-38). Only the second attach_many result (for batch handlers) is returned. If the first attach_many fails with {:error, :already_exists} but the second succeeds, the function incorrectly returns :ok. Conversely, if the first succeeds but the second fails, the function returns an error while leaving single event handlers attached, creating inconsistent state. The function should use a with construct to properly check both results.