synth-check-status

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.