| name | grafana-k6-load-testing |
| description | Run and analyze Grafana Cloud k6 tests through the k6 CLI and read-only REST API. Use for k6 Cloud run status, processed results, thresholds, metrics, multi-zone tests, or load-test monitoring. |
| compatibility | Requires k6, Ruby, fnox, network access, and a K6_CLOUD_TOKEN injected by fnox. |
Grafana Cloud k6 load testing
Run cloud tests with the k6 CLI. Query completed runs and metric metadata through Grafana Cloud k6's read-only REST API.
Credentials
Use a Grafana Cloud k6 Personal token or Stack token, stored outside the repository. Never print, read, or paste its value.
Expected local setup:
fnox set --global --profile grafana-k6 K6_CLOUD_TOKEN
The command prompts with hidden input. Verify only the key name:
fnox --profile grafana-k6 list
Do not use k6 cloud login --show: it prints the locally stored token.
CLI
Check that fnox-injected authentication works:
fnox exec --profile grafana-k6 -- k6 cloud project list
A cloud run normally returns after it reaches Grafana's running state only when passed --exit-on-running. Omit that flag to keep the terminal attached until completion:
fnox exec --profile grafana-k6 -- k6 cloud run script.js
A single Grafana Cloud Free run can use one load zone. Use sequential single-zone smokes, or an eligible paid plan for a distributed multi-zone run.
Read-only REST API
Use scripts/k6-api through fnox. It reads K6_CLOUD_TOKEN only in-process and never prints it.
fnox exec --profile grafana-k6 -- scripts/k6-api run 8320401
fnox exec --profile grafana-k6 -- scripts/k6-api metrics 8320401
fnox exec --profile grafana-k6 -- \
scripts/k6-api series 8320401 'http_req_duration{expected_response="true"}'
API endpoints:
GET https://api.k6.io/cloud/v5/test_runs/:idGET https://api.k6.io/cloud/v5/test_runs/:id/metricsGET https://api.k6.io/cloud/v5/test_runs/:id/series?match[]=...
Run status 3 means finished. Result status 0 means thresholds passed. Processing status 2 means metrics are fully processed.
Use only GET endpoints unless the user explicitly approves an operation that creates, changes, or stops a cloud test.
Result analysis
For each run, report:
- request count/rate, status failures, checks, and threshold results
- global p95 and p99 plus the slowest route groups
- load zone(s), cache behavior when the script records it, and auth/cache-bust mode
- origin health alongside k6: app/DB CPU, load, iowait, memory, swap, queue depth, and errors
Do not call a run healthy merely because it has no HTTP failures: a breached latency threshold, rising p95/p99, DB iowait, or queue growth needs investigation.
Multi-region smoke tests
Geographic smokes validate Cloudflare edge behavior, cache warmth, and country-specific variants; they do not replace an origin-capacity run. Use current production traffic geography to choose zones and weights. On a single-zone plan, run low-RPS smokes sequentially from representative regions before comparing a higher-RPS capacity run.
References
