estuary-task-health

estuary-task-health - Single Task Health Check

Run four checks against a single task and synthesize a verdict. Covers control-plane state, data flow, recent errors, and recent spec changes.

Applies to: captures, materializations, derivations

Step 0: Get the Task Name

If the user hasn't provided a full task name, find it:

flowctl catalog list --prefix <tenant>/ | grep -E "capture|materialize|derivation"

Step 1: Control-Plane Status

Is the task running at all?

flowctl catalog status <task> -o json | jq '{
  status:             .status.type,
  summary:            .status.summary,
  recent_failures:    .status.controller.activation.recentFailureCount,
  last_failure_error: (.status.controller.activation.lastFailure.fields.error // .status.controller.activation.lastFailure.message // null)
}'

Note: last_failure_error shows the raw error string, which is much more readable than the full lastFailure object. For schema validation failures the full object includes the entire failing document — use .fields.error to avoid walls of JSON.

Result	Meaning
status: "OK"	Controller considers task healthy — continue to Step 2
status: "WARNING"	Running but has recent failures — check last_failure_error and Step 3
status: "TASK_DISABLED"	Intentionally paused — use estuary-connector-restart to re-enable
status: "ERROR"	Not recovering — check last_failure_error, then Step 3 for full error

For full status field reference, see the estuary-catalog-status skill.

Step 2: Data Flow

Is data actually moving? (A task can show OK while stalled.)

For materializations:

flowctl raw stats --task <task> --since 24h | \
  jq -s '{
    total_gb:     ([.[] | select(.materialize != null) | .materialize | to_entries[] | .value.right.bytesTotal // 0] | add // 0 | . / 1073741824 * 10 | round / 10),
    total_docs:   ([.[] | select(.materialize != null) | .materialize | to_entries[] | .value.right.docsTotal  // 0] | add // 0),
    transactions: ([.[] | select(.materialize != null)] | length)
  }'