Skip to content

feat: add cursor attribution via comment stamping and tests for reactive and imperative streams - #70

Merged
cedricclausPro merged 2 commits into
mainfrom
52-stamp-change-streams-with-an-identifying-comment-for-cursor-attribution
Aug 20, 2026
Merged

feat: add cursor attribution via comment stamping and tests for reactive and imperative streams#70
cedricclausPro merged 2 commits into
mainfrom
52-stamp-change-streams-with-an-identifying-comment-for-cursor-attribution

Conversation

@cedricclausPro

Copy link
Copy Markdown
Contributor

Closes #52.

Every change stream cursor FlowWarden opens now carries an identifying
comment, visible in $currentOp (cursor.originatingCommand.comment, with
idleCursors: true), server logs and the profiler, and propagated to getMores
(server ≥ 4.4). A cursor on a deployment becomes attributable to its declaring
stream at a glance, and FlowWarden cursors are distinguishable from any other
change stream consumer.

Three comment families, all built from one internal helper and matchable via
the new public FlowWarden.CURSOR_COMMENT_PREFIX constant:

  • flowwarden:<streamName> — the stream's main cursor (both modes)
  • flowwarden:heartbeat:<streamName> — heartbeat probe cursors (pre-existing,
    now built from the same source of truth)
  • flowwarden:resume-validation:<streamName> — the ephemeral resume-token
    validation cursors of the startup/restart resume cascade

Ordinary query cursors (checkpoint, DLQ, lock reads) are not stamped — the
documented contract covers change stream cursors only.

The interesting part is the how: Spring Data (through 4.2.x) exposes no
comment option on ChangeStreamOptions, while the driver does. Both Spring
Data cursor-creation paths obtain their MongoDatabase from the template's
database factory and call watch(...) on it — so each stream's cursor is
created through a template whose factory is decorated with a reflective proxy
that stamps comment on watch(...) results, re-proxies getCollection/
withXxx so the stamp survives reconfiguration, and delegates everything else
untouched (driver exceptions surface unwrapped, converter unchanged so mapping
is untouched). Metadata only, no behavioral change; if Spring Data ever exposes
the option natively the decoration collapses into a builder call.

Tests:

  • unit coverage of the decoration (sync + reactive watch stamping, delegation,
    exception unwrapping) and of the three produced comment values;
  • wiring tests pinning that both isTokenValid implementations actually put
    the validation comment on the driver cursor (the reactive one exercises the
    real ReactiveMongoTemplate.changeStream through the stamping proxy);
  • an acceptance IT per mode asserting the real running cursor shows up stamped
    in $currentOp on the right namespace.

…ive and imperative streams

- Introduced `CursorCommentStamping` to add identifiable comments (e.g., `flowwarden:<streamName>`) on MongoDB change stream cursors for operational attribution.
- Enhanced `ReactiveStreamManager` and `ImperativeStreamManager` to use stamped cursors for main streams, heartbeats, and token validation.
- Added integration and unit tests to verify comment propagation in reactive and imperative stream modes.
- Updated test utilities with support for stamped cursor assertions.

Signed-off-by: cedricclausPro <62853718+cedricclausPro@users.noreply.github.com>
@cedricclausPro
cedricclausPro merged commit 6a76e26 into main Aug 20, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Stamp change streams with an identifying comment for cursor attribution

1 participant