Terminal
Terminal/Skill
Creates, updates, pulls, pushes, and deletes Grafana SLO definitions with gcx, running dry-run checks before any push.
By Grafana Labs
Works with
npx skills add grafana/gcx --skill slo-manageCreate, update, sync, and delete SLO definitions using gcx.
--dry-run before any push operation; proceed only if dry-run succeeds-o json for agent processing; default table/yaml for user displaySelect query type based on what the user describes:
| User describes | Query type |
|---|---|
| "percentage of successful requests", "success rate", "error rate" | ratio |
| "raw PromQL expression", "custom metric formula" | freeform |
| "metric above/below threshold", "latency under X ms", "availability percentage" | threshold |
Use the metric name suffix to pick the query type when the user provides a metric name:
| Metric suffix / type | Query type | Rationale |
|---|---|---|
_total counter | ratio | success_total / all_total |
_bucket histogram | threshold | use le-bound threshold on quantile |
_gauge or up metric | threshold | compare to fixed threshold |
| None of the above | freeform | last resort only |
Guardrail: Freeform is a last resort. Before choosing freeform, verify the SLI cannot be expressed as ratio or threshold.
Hard requirement: Freeform queries MUST use $__rate_interval in all rate()/increase() calls. Literal ranges like [5m] are rejected by the SLO API.
gcx datasources list --type prometheus
Use the UID from the output. Some stacks do not populate type in the list
response, so the filter can come back empty even though Prometheus datasources
exist — in that case list everything and pick the canonical Grafana Cloud
Prometheus entry (name like grafanacloud-<stack>-prom):
gcx datasources list
If that leaves zero or multiple plausible Prometheus candidates, ask the user
which UID to use rather than guessing (the stack's default: true datasource
is not necessarily Prometheus).
For complete ratio, freeform, and threshold templates (including alerting, labels, and folder fields), see references/slo-templates.md. Key structure:
apiVersion: slo.ext.grafana.app/v1alpha1
kind: SLO
metadata:
name: "" # leave empty for new SLO (server assigns UUID on create)
spec:
name: "my-api-availability"
description: "API availability over 28 days"
query:
type: ratio # freeform | ratio | threshold
ratio: # field matches type
successMetric:
prometheusMetric: http_requests_total{status!~"5.."}
totalMetric:
prometheusMetric: http_requests_total
groupByLabels: [cluster, service]
objectives:
- value: 0.999 # 0.9 to 0.9999 typical range
window: 28d # 7d | 14d | 28d | 30d
destinationDatasource:
uid: <prometheus-uid>
gcx resources push slos -p slo.yaml --dry-run
gcx resources push slos -p slo.yaml
Push semantics:
metadata.name set to UUID → update if it exists; otherwise match by the SLO name before creating.metadata.name → match by the SLO name before creating; the server assigns a UUID only when creating.Run gcx slo definitions list to confirm.
gcx slo definitions get <UUID> -o yaml > slo.yaml
Edit the relevant fields (objective value, query, alerting, etc.).
Do not modify metadata.name (UUID) or readOnly fields.
gcx resources push slos -p slo.yaml --dry-run
gcx resources push slos -p slo.yaml
gcx resources pull slos -p ./slos -o yaml
# Writes to ./slos/slos.v1alpha1.slo.ext.grafana.app/<uuid>.yaml
gcx resources push slos -p ./slos --dry-run
gcx resources push slos -p ./slos
gcx slo definitions list
gcx slo definitions get <UUID>
Confirm the UUID and name with the user before deletion.
gcx slo definitions delete <UUID> --force
Use --force to skip the confirmation prompt when running in agent mode
(there is no -f shorthand on delete).
Objective values (stored as 0–1, displayed as percentage):
Window options: 7d, 14d, 28d, 30d
Alerting best practices:
fastBurn: Pages on-call (high burn rate, short window — catches rapid budget consumption)slowBurn: Creates tickets (low burn rate, long window — catches gradual degradation)Labels: Use consistent label keys (team, service, environment, tier) for filtering and grouping.
GroupByLabels (ratio/threshold queries): Add labels like cluster, service, endpoint for dimensional breakdown in status and investigation.
After create/update:
SLO: <name>
UUID: <uuid>
Status: Created | Updated
Objective: <value>% over <window>
Datasource: <uid>
After pull:
Pulled <N> SLO definitions to <dir>/SLO/
After delete:
Deleted: <uuid> (<name>)
destinationDatasource.uid is validmetadata.name not found; check with gcx slo definitions listgcx config view for active context--type prometheus filter returns empty: the list API may not populate type on this stack; run gcx datasources list without the filter and match the Cloud Prometheus name pattern before concluding none existgcx slo definitions list