Skip to main content

CDC Sink: Monitoring

Task status and statistics​

Retrieve the current task info with GetOngoingTaskInfoOperation and cast the result to OngoingTaskCdcSink.
Two standard ongoing-task fields report the task's enabled state and current connection status:

  • TaskState - whether the task is enabled, disabled, or partially enabled.
  • TaskConnectionStatus - whether the task is active, reconnecting, inactive, or running on another node.

The following runtime fields report how a running task is progressing:

  • Progress and lag
    LastBatchTime and SecondsSinceLastBatch show when the task last completed a batch,
    while LastActivityTime and SecondsSinceLastActivity show the last activity from the source.
    Recent activity with an old LastBatchTime indicates that the source connection is alive but there are no changes to apply.
  • Health
    HealthIssue is null when healthy and carries a diagnostic message when the task detects a problem,
    such as fallback mode or a stale connection.
  • Position
    LastCheckpoint reports the last persisted CDC checkpoint (an LSN or GTID).

For the call syntax and the full list of returned fields with their possible values, see Get task info via Client API.
Task info is also available in the Ongoing Tasks view in the Management Studio - see Get task info via Studio.

Fallback mode​

When a CDC Sink task encounters a retryable failure, it enters fallback mode and retries after a backoff delay.
While the task is in fallback mode, TaskConnectionStatus is reported as Reconnect.

In fallback mode:

  • The task waits for the current backoff delay, then retries
  • No changes are applied while the task is waiting
  • If the next attempt succeeds, processing resumes automatically

The first fallback delay is 5 seconds. On subsequent failures, the base delay grows to twice the time elapsed since the last error, up to the cap set by CdcSink.MaxFallbackTimeInSec (default 15 minutes). RavenDB then adds up to 10% random jitter to avoid synchronized retries across processes. See Server Configuration.

Notifications​

CDC Sink raises RavenDB alerts for task-level failures and provider-specific warning conditions.
A retryable process failure also moves the task into fallback mode.

CDC Sink alerts are visible in the Notification Center in the Management Studio (bell icon).

The alert message identifies the affected task and describes the failure or warning. Depending on the case, it may also include provider-specific context, such as a table, publication, checkpoint, or exception details.

Error handling​

CDC Sink can tolerate deterministic per-document failures, such as mapping or patch-script errors, while the overall error ratio remains acceptable. The failed document is logged and recorded, and CDC Sink continues processing the remaining documents in the batch.

The CDC checkpoint advances only when the current batch execution completes without errors or successfully processes at least one document. If all documents in the execution fail, the checkpoint is not advanced.

Error threshold: When cumulative per-document processing errors reach 100 and also exceed the number of successful operations, CDC Sink stops the current batch. The failure is reported as an alert, and the task enters fallback mode.

Non-document-scoped process failures are not treated as tolerable per-document errors.
They fail the current attempt and move the task into fallback mode.

Patch errors: Patch-script errors, including scripts that exceed Patching.MaxStepsForScript, fail only the affected document while the script-error ratio remains acceptable. Other documents in the same batch can still be processed.

For fallback retry timing, see Fallback mode and Server Configuration.

Performance endpoints​

CDC Sink exposes detailed performance statistics through dedicated endpoints:

MethodEndpointAuthDescription
GET/databases/{databaseName}/cdc-sink/performanceValidUserGet the latest CDC Sink performance statistics
GET/databases/{databaseName}/cdc-sink/performance/liveValidUserOpen a WebSocket stream of live performance statistics

Both endpoints can be filtered with the optional name query parameter.

The response is grouped by CDC Sink task and process. Each performance entry includes timing information, read and processed message counts, script-processing and read-error counts, memory allocation, batch stop reason, processing status, and nested operation timings.