/synth-check-status

name: synth-check-status
description: >-
  Shows Synthetic Monitoring check health via gcx: inventory, pass/fail and
  success rate per check, success-rate timelines. Use for "are my checks
  healthy" or a named check. For a failing check use synth-investigate-check. To
  create or change checks use synth-manage-checks.
allowed-tools: Bash

Synthetic Monitoring Check Status

View check health, status, and timelines.

Core Principles

1. Use gcx commands exclusively — do not call APIs directly 2. Trust the user's expertise — no excessive explanation 3. Use `-o json` for agent processing, default format for user display 4. Show graph visualizations for time-series data

Workflow

Step 1: List All Checks

Always start with the full check inventory:

gcx synthetic-monitoring checks list

Output columns: NAME, JOB, TARGET, TYPE. The NAME suffix is the numeric check ID (e.g. `web-check-1001` is ID `1001`) - use that ID in the commands below. Identify the check(s) the user is asking about.

If the user specifies a check name, filter with a job glob:

gcx synthetic-monitoring checks list --job 'my-check*'

Step 2: Show Status

For all checks (overview):

gcx synthetic-monitoring checks status

For a specific check:

gcx synthetic-monitoring checks status <ID>

Only failing checks:

gcx synthetic-monitoring checks status --status FAILING

Output columns: NAME, JOB, TARGET, SUCCESS (reachability, as shown on the app's check list card, over the last 3 hours), LATENCY, STATUS. Use `-o wide` for PROBES_UP/PROBES_TOTAL, or `-o json` for all fields.

**Status interpretation** (threshold depends on the check's `alertSensitivity`: high = 95%, medium/default = 90%, low = 75%):

• `OK` - reachability at or above the threshold; check is healthy
• `FAILING` - reachability below the threshold; route to synth-investigate-check for deeper analysis
• `NODATA` - the backend answered but has no reachability data for the check; it may be disabled or newly created

If the command exits non-zero with an error naming `checks_reachability`, the stack's Synthetic Monitoring app cannot serve the status queries (it is too old, or the query failed); no rows are printed, so this is not a NODATA result. A warning on stderr naming `checks_probe_count` or `checks_latency` means only that column is empty; statuses are still valid.

Step 3: Conditional Timeline

Show timeline when:

• User asks about trends or history
• Any check shows `FAILING` status

With a duration shorthand:

gcx synthetic-monitoring checks timeline <ID> --since <duration>

With an explicit time range:

gcx synthetic-monitoring checks timeline <ID> --from <start> --to <end>

Examples:

gcx synthetic-monitoring checks timeline 42 --since 6h
gcx synthetic-monitoring checks timeline 42 --from now-24h --to now

Note: `--since` and `--from`/`--to` are mutually exclusive. Use one or the other.

**Timeline pattern interpretation:**

• Flat line at 1.0 — healthy; all probes succeeding consistently
• Drops to 0.0 — probe-level failures; investigate with synth-investigate-check
• Intermittent spikes to 0 — flapping; transient failures or timeout issues
• Gradual decline — degrading target or increasing probe timeouts

Step 4: Routing and Next Actions

After presenting status:

• If any check is `FAILING`: suggest `synth-investigate-check` for per-probe breakdown, failure mode classification, and PromQL deep-dive
• If any check is `NODATA`: note that no metrics are available; suggest checking if the check is enabled and has had time to run. A diagnosis alone leaves the user without a path forward — always close with the remediation step: rule out intentional disablement, then recommend re-enabling (route to `synth-manage-checks`) and confirming data resumes
• If user wants to create, update, or delete checks: route to `synth-manage-checks`

Output Format

For status overview (all checks healthy):

Checks: <N> total, <N> OK, <N> FAILING, <N> NODATA

[Table from gcx synthetic-monitoring checks status]

All checks healthy.

For status with FAILING checks:

Checks: <N> total, <N> OK, <N> FAILING, <N> NODATA

[Table from gcx synthetic-monitoring checks status]

FAILING checks:
- <ID> <JOB> (<TARGET>) — <SUCCESS%> success, <PROBES_UP> probes up

[Timeline graph if shown]

For per-probe breakdown and failure diagnosis, use synth-investigate-check.

For a specific check with timeline:

Check: <ID> <JOB> (<TARGET>) [<TYPE>]
Status: <OK|FAILING|NODATA>
Success: <SUCCESS%>
Probes up: <PROBES_UP>

[Timeline graph]

Timeline pattern: <flat/drops/intermittent/declining>

For NODATA checks:

Check: <ID> <JOB> (<TARGET>)
Status: NODATA — no metrics available.

Possible causes:
- Check is disabled (spec.enabled: false)
- Synthetic Monitoring datasource not configured
- Metrics not yet available (newly created check)

Verify: gcx synthetic-monitoring checks get <ID> -o json | jq '.spec.enabled'

Next step:
- If the check was disabled intentionally, note that and stop.
- Otherwise, re-enable it (route to synth-manage-checks), then re-run status
  after a few minutes to confirm data resumes.

Error Handling

• **`gcx synthetic-monitoring checks list` returns empty**: No checks configured in this context. Verify the gcx context with `gcx config view`.
• **`gcx synthetic-monitoring checks status <ID>` fails with "not found"**: Confirm the ID from `gcx synthetic-monitoring checks list` (the numeric suffix of NAME).
• **`gcx synthetic-monitoring checks timeline <ID>` fails**: Verify the ID exists and that the check has been running long enough to have data. New checks may show no timeline data.
• **`--since` and `--from`/`--to` both provided**: These flags are mutually exclusive. Use one or the other.
• **Timeline shows no data for the selected range**: Try a longer duration (e.g., `--since 24h` instead of `--since 1h`). The check may have be