/synth-check-status

name: synth-check-status
description: Shows Synthetic Monitoring check health - check inventory, per-check pass/fail status with success rates, and success-rate timelines as terminal graphs. Use when the user asks about Synthetic Monitoring check health, status, or trends. Trigger on phrases like "are my checks healthy", "check status", "synth check", "probe status", or when users mention specific check names or IDs. For investigating failing checks use synth-investigate-check. For creating or managing 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, 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` - success rate at or above the threshold; check is healthy
• `FAILING` - success rate below the threshold; route to synth-investigate-check for deeper analysis
• `NODATA` - no Prometheus data; check may be disabled or datasource misconfigured

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 Prometheus data is available; suggest checking if the check is enabled and verifying datasource configuration. 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 Prometheus 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 been created recently.
• **Context not set**: Run `gcx config view` to verify the active context. If multiple contexts exist and none specified, ask the user which to use.