Terminal
Terminal/Skill
Creates, updates, exports, and deletes Synthetic Monitoring checks from YAML definitions using gcx.
By Grafana Labs
Works with
npx skills add grafana/gcx --skill synth-manage-checksManage Synthetic Monitoring checks using gcx.
-o json for agent processing; default table format for user displaygcx synthetic-monitoring probes listPick the type from the target format (full decision tree and per-type templates: 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).
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).
Use the template from 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
settings:
http: {} # Replace with type-specific settings
Configuration guidance:
frequency; typically 5,000–30,000msnone — see "Alert Sensitivity" in
references/check-types.md for why non-none
values can 403 on some stacks.true reduces metric cardinality (fewer label dimensions); false emits full metrics# 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>
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
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.
# Update the check from file
gcx synthetic-monitoring checks update <ID> -f check-<ID>.yaml
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-monitoring checks update <ID> -f ./sm-checks/check-<ID>.yaml
For bulk updates, update files individually to control which checks are changed.
# List checks to confirm IDs
gcx synthetic-monitoring checks list
# Delete one or more checks (by numeric ID)
gcx synthetic-monitoring checks delete <ID>
# Skip confirmation prompt
gcx synthetic-monitoring checks delete <ID> --force
# Delete multiple checks
gcx synthetic-monitoring checks delete <ID1> <ID2> <ID3>
Confirm the check identity (job name and target) before deleting — use gcx synthetic-monitoring checks get <ID> to review.
After creating or updating:
Check: <job-name>
Target: <target>
Type: <HTTP|Ping|DNS|TCP|Traceroute>
Probes: <count> selected (<list>)
Result: <created (id=<ID>) | updated>
Verify status:
gcx synthetic-monitoring checks status <ID>
After export:
Exported <N> checks to <dir>/
Files: <list of filenames>
After delete:
Deleted check <ID> (<job-name> -> <target>)
gcx synthetic-monitoring probes list and copy names exactly.timeout value or increase frequency.frequency range depends on check type (e.g. traceroute allows longer intervals); the API error states the valid range.gcx synthetic-monitoring checks list to find it and update instead of create.gcx synthetic-monitoring probes list; if empty, verify gcx context and SM API access.gcx synthetic-monitoring checks get <ID> -o yaml.