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
• 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'

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.