feat(telemetry): add and surface processing_latency_ms in event handler spans

[yordis]

• Adds commanded.handler.lag span attribute to [:commanded, :event, :handle, :stop] and [:commanded, :event, :batch, :stop] OTel spans — elapsed milliseconds from RecordedEvent.created_at to handler completion, representing how far behind the handler is relative to when events were written
• For batch handlers, reflects the oldest event in the batch (worst-case lag)

[cursor]

PR Summary

Low Risk
Low risk: adds a new optional span attribute derived from existing telemetry measurements and updates tests, without changing event handling behavior.

Overview
Adds a new Commanded OpenTelemetry attribute, commanded.handler.lag, representing processing_latency_ms (event creation → handler completion).

Event handler and batch handler :stop telemetry callbacks now read processing_latency_ms from measurements and attach it to the span when present; tests are updated to emit the measurement and assert the new attribute is included.

^{Reviewed by Cursor Bugbot for commit ecb6a0c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Walkthrough

Added a new OpenTelemetry span attribute constant representing event processing latency. Modified event handler telemetry callbacks to conditionally set this attribute on span completion when processing latency measurements are available. Updated corresponding tests to verify the attribute is captured.

Changes

Cohort / File(s)	Summary
Span Attribute Constant lib/commanded/opentelemetry/commanded_attributes.ex	Added new public function commanded_processing_latency_ms/0 that returns the atom :"commanded.processing_latency_ms" for identifying the processing latency span attribute.
Event Handler Telemetry lib/commanded/opentelemetry/event_handler.ex	Modified handle_telemetry_event/4 and batch_telemetry_event/4 to accept and process the measurements argument, conditionally setting the processing latency span attribute when the measurement is present as an integer.
Event Handler Tests test/opentelemetry/event_handler_test.exs	Updated telemetry span callbacks to return processing_latency_ms in measurements (250 for single events, 500 for batch events) and extended assertions to verify the new span attribute is captured with expected values.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• feat(telemetry): add processing_latency_ms to event handler stop measurements #66: Introduces the processing_latency_ms measurement in event handler telemetry, which is directly consumed by these changes to set the corresponding OpenTelemetry span attribute.

Poem

🐰 A latency watcher hops with glee,
Measuring time from start to end decree,
Each span now knows the journey's pace,
Processing moments, captured with grace! ⏱️✨

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 57.14% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	⚠️ Warning	The PR description mentions 'commanded.handler.lag' but the actual implementation adds 'commanded.processing_latency_ms'; terminology differs from implementation.	Update the PR description to accurately reflect that the span attribute is named 'commanded.processing_latency_ms' rather than 'commanded.handler.lag'.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding a new OpenTelemetry span attribute for processing_latency_ms in event handler spans.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch improve-otel

---

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.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@lib/commanded/opentelemetry/event_handler.ex`:
- Around line 261-267: The helper put_commanded_processing_latency_ms currently
only matches measurements with the key :processing_latency_ms so spans never get
the attribute when measurements use %{n: ...}; update
put_commanded_processing_latency_ms to handle either key (e.g., pattern-match
%{processing_latency_ms: latency} or %{n: latency}) and accept numeric values
(use is_number/1 or convert to integer) before calling Span.set_attribute(ctx,
CommandedAttributes.commanded_processing_latency_ms(), latency) so the attribute
is set regardless of which producer key is used.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 947ba220-9131-45dd-a332-3a2279124738

📥 Commits

Reviewing files that changed from the base of the PR and between edbe23e and 3b3156f.

📒 Files selected for processing (3)

• lib/commanded/opentelemetry/commanded_attributes.ex
• lib/commanded/opentelemetry/event_handler.ex
• test/opentelemetry/event_handler_test.exs

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 19dfe61. Configure here.}