/synth-manage-checks

name: synth-manage-checks
description: >-
  Creates, updates, pulls, pushes, and deletes Synthetic Monitoring checks from
  YAML via gcx. Use also when the user gives a URL or hostname to monitor. For
  check health use synth-check-status. For a failing check use
  synth-investigate-check.
allowed-tools: Bash, Read, Write, Edit

Synthetic Monitoring Check Manager

Manage Synthetic Monitoring checks using gcx.

Core Principles

1. Use gcx commands; never call Grafana APIs directly (no curl, no HTTP calls) 2. Trust the user's expertise — no explanations of what SM or gcx is 3. Use `-o json` for agent processing; default table format for user display 4. gcx validates specs client-side before calling the API (probe names, check type, target format); `--dry-run` on `checks create`/`checks update` additionally validates against the SM API without writing anything 5. Probe names are case-sensitive — always copy-paste from `gcx synthetic-monitoring probes list`

Workflow 1: Create New Check

Step 1: Determine Check Type

Pick the type from the target format (full decision tree and per-type templates: [check-types.md](references/check-types.md)):

| Target | Check Type | |--------|------------| | URL (`https://...`, `http://...`) | HTTP | | Hostname or IP (no port) | Ping | | Domain name (DNS lookup) | DNS | | `host:port` | TCP | | URL with routing path analysis | Traceroute |

If unsure, ask the user what they want to test (availability, DNS, port connectivity, routing).

Step 2: List and Select Probes

gcx synthetic-monitoring probes list

Recommend at least 3 geographically distributed probes. Copy names exactly as shown — case-sensitive. Suggest probes across different continents or regions to provide meaningful coverage (e.g., one each from North America, Europe, Asia-Pacific).

Step 3: Build YAML Definition

Use the template from [check-types.md](references/check-types.md) for the chosen type, filling the type-specific `settings` block. Common fields:

apiVersion: syntheticmonitoring.ext.grafana.app/v1alpha1
kind: Check
metadata:
  name: <job-name>   # gcx rewrites this to <job>-<id> after create
spec:
  job: <job-name>
  target: <target>
  frequency: 60000    # milliseconds; 10000-120000 typical
  timeout: 10000      # milliseconds; must be < frequency
  enabled: true
  labels:
    - name: environment
      value: production
    - name: team
      value: platform
  probes:
    - Atlanta
    - Frankfurt
    - Singapore
  alertSensitivity: none    # none unless the stack uses legacy sensitivity alerts
  basicMetricsOnly: false   # true = fewer metrics, lower cardinality
  # folderUid: production-folder-uid  # Optional: UID of an existing Grafana folder
  settings:
    http: {}   # Replace with type-specific settings

Configuration guidance:

• **frequency**: critical checks 10,000–60,000ms; standard checks 60,000–300,000ms
• **timeout**: must be strictly less than `frequency`; typically 5,000–30,000ms
• **alertSensitivity**: default to `none` — see "Alert Sensitivity" in

[references/check-types.md](references/check-types.md) for why non-`none` values can 403 on some stacks.

• **basicMetricsOnly**: `true` reduces metric cardinality (fewer label dimensions); `false` emits full metrics
• **folderUid**: optional Grafana folder UID, not its title; does not create a folder.

On create, omission or `""` leaves no explicit assignment (the SM app uses the default folder). On update, omission preserves the existing assignment; `folderUid: ""` clears it. This also applies to `gcx resources push`: removing the line from a pulled manifest does not clear the assignment. Cross-stack pushes preserve the UID literally; gcx does not remap it by folder title. Verify that it identifies the intended folder in the destination stack and change it before pushing if necessary.

Step 4: Create the Check

# Validate against the SM API without creating anything
gcx synthetic-monitoring checks create -f <file.yaml> --dry-run

# Create from file
gcx synthetic-monitoring checks create -f <file.yaml>

For HTTP checks, `--validate-targets` pre-flights the target with a HEAD request (warning only). If client-side validation fails, fix the field named in the error and re-run.

After creation, verify with:

gcx synthetic-monitoring checks list
gcx synthetic-monitoring checks status <ID>

Workflow 2: Update Existing Check

Step 1: Pull Current Definition

Fetch the specific check:

# Get single check as YAML (use ID from list output)
gcx synthetic-monitoring checks get <ID> -o yaml > check-<ID>.yaml

Step 2: Edit and Update

Edit the YAML file, keeping `metadata.name` unchanged (it is the `<job>-<id>` composite that targets the right check). Modify only the fields that need changing.

# Validate the update against the SM API without applying it
gcx synthetic-monitoring checks update <ID> -f check-<ID>.yaml --dry-run

# Update the check from file
gcx synthetic-monitoring checks update <ID> -f check-<ID>.yaml

To run a check once without saving or scheduling it, pass either a saved check or a manifest. Ad-hoc runs are billed like scheduled executions, so confirm before running them repeatedly:

# Run a saved check once (resource name or numeric ID)
gcx synthetic-monitoring checks test <ID>

# Run an edited manifest once, before updating
gcx synthetic-monitoring checks test -f check-<ID>.yaml

Workflow 3: GitOps Sync (Pull/Push)

When users say "pull" they mean export with `checks get -o yaml`; "push" means apply with `checks create`/`checks update -f`. Export to files, edit in source control, then update to apply:

# List all checks and export each to YAML
gcx synthetic-monitoring checks list -o yaml

# Get a specific check as YAML
gcx synthetic-monitoring checks get <ID> -o yaml > ./sm-checks/check-<ID>.yaml

# Edit files as needed, then update each changed file
gcx synthetic-mon