Introduce a mechanism to detect whether the CDC engine is running

[ayeshLK]

Area

Area/EventIntegration

Current Limitation

Currently, when a CDC service is running and the underlying CDC engine terminates due to an unexpected error, there is no clear way for the user to determine what happened or whether the engine is still running.

Suggested Improvement

Introduce a utility method that allows users to check the runtime status of the underlying CDC engine.

Version

Ballerina CDC v1.0.3

[ayeshLK]

[Meeting notes on 29th Jan 2026]

Attendees: @shafreenAnfar @niveathika @gayaldassanayake @ayeshLK

Notes:

• Validate the behavior of Debezium callback methods to reliably detect CDC engine start and stop events.
• Introduce a shared, reusable setup for liveness checks that can be used across all event-driven integrations to ensure consistency and reduce duplication.

[ayeshLK]

[Update on 5th Feb 2026]

The original requirement here is to define an approach for introducing health checks (liveness/readiness probes) when running Ballerina CDC-based services in a containerized environment. Unlike traditional REST services, health checks in an event-driven architecture (EDA) need to be evaluated differently.

In this context, liveness can be determined by verifying whether the underlying consumer is actively consuming events and whether its offset/pointer (in a message broker topic or CDC log) is progressing forward within a defined time window. Based on this understanding, the following approach would be more suitable for implementing a liveness check for a CDC listener.

Approach

Introduce a new utility function in the ballerina/cdc module to determine whether a given CDC listener is live.

Proposed API definition:

# Checks whether the given CDC listener is live.
#
# + cdc - The CDC listener instance to be checked
# + return - `true` if the listener is considered live, `false` otherwise
public function isLive(cdc:Listener cdc) returns boolean;

Add a new defaultable configuration field to the cdc:ListenerConfiguration record to define the liveness evaluation interval.

public type ListenerConfiguration record {|
     ...

    # Time interval (in seconds) used to evaluate the liveness of the CDC listener
    decimal livenessInterval = 60.0;
|};

Sample usage:

listener mssql:Listener mssqlCdc = ...;

// HTTP-based liveness probe
service on new http:Listener(...) {

    resource function get liveness() returns http:Ok|http:ServiceUnavailable {
        boolean isLive = cdc:isLive(mssqlCdc);
        if isLive {
            return http:OK;
        }
        return http:SERVICE_UNAVAILABLE;
    }
}

---

Implementation

Within the underlying Debezium engine, introduce a mechanism to track and update a timestamp based on the last event received time whenever a new CDC event is processed. Additionally, register a DebeziumEngine.CompletionCallback with the engine to detect termination scenarios.

Pseudo code:

if completionCallbackInvoked {
    return false;
}

if diff(currentTime, lastEventReceivedTime) > livenessInterval {
    return false;
}

return true;

Reference

• https://blog.cloudflare.com/intelligent-automatic-restarts-for-unhealthy-kafka-consumers/

[daneshk]

@niveathika Can we have your thoughts on the design please

[gayaldassanayake]

The proposal is great!

For the isLive check, we can use Debezium heartbeats[1]. This will prevent isLive from failing when there are no events created due to not having actual changes in the DB.

Heartbeats, when configured, are special events triggered by the Debezium engine periodically. We can directly map livenessInterval from your proposal to the Debezium property heartbeat.interval.ms.

Heartbeats are supported for all types of DBs by Debezium, hence avoiding future compatibility issues.

Here is how we would update lastEventReceivedTime from the heartbeats received.

// BalChangeListener
public void handleBatch(List<ChangeEvent<String, String>> records,
                           DebeziumEngine.RecordCommitter<ChangeEvent<String, String>> committer) {
        ....
        for (ChangeEvent<String, String> record : records) {
            if (isHeartbeatEvent(record)) {
                lastEventReceivedTime = currentTimeMillis
                continue;
            }
        }
        ....
}

[1] https://debezium.io/documentation/reference/stable/connectors/postgresql.html#postgresql-property-heartbeat-interval-ms

[daneshk]

The proposal looks good.

One comment on the Listener configuration exposed.

Shall we expose heartbeatInterval as a separate config? So we have both heartbeatInterval and livenessInterval in the listener config.

heartbeatInterval (Debezium's heartbeat.interval.ms)

• What it does: Controls how often Debezium generates heartbeat events when there are no actual database changes
• Purpose: Keeps the connection alive and provides proof that the engine is running

livenessInterval

• What it does: The threshold used to determine if the listener is considered live
• Purpose: Decision-making timeout - if no event/heartbeat received within this window, report as not live

livenessInterval should be greater than heartbeatInterval

WDYT?

[ayeshLK]

Shall we expose heartbeatInterval as a separate config? So we have both heartbeatInterval and livenessInterval in the listener config.

+1 to the suggestion

For the isLive check, we can use Debezium heartbeats[1]. This will prevent isLive from failing when there are no events created due to not having actual changes in the DB.

@gayaldassanayake if heartbeat is another event, that means there is no need to treat it as a special event and update the liveness-timestamp. IMO event-received should be the trigger for liveness timestamp update. The event can be a CDC or DB heartbeat. What do you think ?

[niveathika]

@ayeshLK Shall we expose the http server within the CDC listener itself? This reduces boilerplate code and improves usability.

[ayeshLK]

@niveathika Good catch — that would significantly reduce boilerplate. Since liveness support for event-driven integrations is a common requirement, I’m thinking of addressing this in a follow-up phase. We also need to consider liveness probes for other types of integrations, so it might be better to design a generic solution that can be extended across multiple use cases.