Monitoring

Every running TwinCommit pipeline exposes its health in three ways: Prometheus metrics on /metrics, a JSON snapshot on /status, and structured JSON logs on stderr. All three are served by twincommit run on metrics_addr (default :9108).

Endpoints

Endpoint	Format	Use
/metrics	Prometheus text	Dashboards and alerting
/status	JSON	Scripts, health checks, the MCP server
/healthz	200 / 503	Liveness: the process is running
/readyz	200 / 503	Readiness: connected and applying

/status example

curl -s localhost:9108/status | jq

{
  "pipeline": "prod-db2",
  "state": "streaming",
  "caught_up": true,
  "lag_seconds": 0.31,
  "read_position": "0000000004F3E2C0",
  "applied_position": "0000000004F3E2A1",
  "open_transactions": 2,
  "broken_tables": [],
  "last_error": null
}

What to alert on

1. Lag above your freshness SLO for more than a few minutes.
2. Broken tables above 0.
3. Errors increasing steadily, a sign that retries are not succeeding.
4. Process down, when up == 0 for the scrape target.

Example rules are on the Prometheus metrics page, and a ready-made dashboard is on the Grafana dashboard page.