Skip to main content
The Grafana Cloud k6 integration allows you to stream test results in real-time to the k6 Cloud platform for advanced analysis, collaboration, and test result storage.

​
Overview

The cloud output (internal/output/cloud/output.go:55) sends metrics, traces, and test metadata to Grafana Cloud k6, providing:
  • Real-time test monitoring
  • Performance trend analysis
  • Collaborative result sharing
  • Threshold evaluation tracking
  • Test run comparison
  • Distributed test execution

​
Authentication

Before using the cloud output, authenticate with your k6 Cloud token: 
k6 login cloud
Or set the token directly: 
export K6_CLOUD_TOKEN=your_token_here

​
Basic Usage

Run a test with cloud output: 
k6 run --out cloud script.js
The cloud output will:
  1. Create a test run in k6 Cloud
  2. Stream metrics during execution
  3. Display a URL to view results in real-time
  4. Finalize the test run on completion

​
Configuration

​
Via Script Options

Configure cloud settings in your test script: 
export const options = {
  cloud: {
    name: 'My Test Run',
    projectID: 12345,
    distribution: {
      'us-east-1': { loadZone: 'amazon:us:ashburn', percent: 50 },
      'eu-west-1': { loadZone: 'amazon:ie:dublin', percent: 50 },
    },
  },
};

​
Via Environment Variables

All cloud configuration options can be set via environment variables: 
export K6_CLOUD_NAME="My Test Run"
export K6_CLOUD_PROJECT_ID=12345
export K6_CLOUD_HOST="https://ingest.k6.io"
Environment variables take precedence over script options, allowing you to override settings without modifying test code.

​
Configuration Options

The cloud configuration (cloudapi/config.go:20) supports extensive options:

​
Basic Settings

  • name: Test run name (default: script filename)
  • projectID: k6 Cloud project ID
  • token: Authentication token

​
Advanced Settings

  • host: Ingest endpoint URL (default: https://ingest.k6.io)
  • webAppURL: Web application URL for viewing results
  • timeout: API request timeout (default: 1 minute)
  • noCompress: Disable metric compression
  • stopOnError: Stop test on cloud API errors

​
Metrics Streaming

  • metricPushInterval: How often to send metrics (default: 1 second)
  • metricPushConcurrency: Concurrent push connections (default: 1)
  • maxTimeSeriesInBatch: Max time series per batch (default: 1000)
  • aggregationPeriod: Metric aggregation window (default: 3 seconds)
  • aggregationWaitPeriod: Wait time before aggregation (default: 8 seconds)

​
Traces

  • tracesEnabled: Enable trace collection (default: true)
  • tracesHost: Traces backend endpoint
  • tracesPushInterval: Trace push interval (default: 1 second)
  • tracesPushConcurrency: Concurrent trace pushes (default: 1)
The metricPushConcurrency and maxTimeSeriesInBatch settings can significantly impact network usage and cloud ingest performance. Adjust carefully based on your test scale.

​
Test Run Lifecycle

1
Initialization
2
When the output starts, it:
3
  • Validates required system tags are enabled
  • Creates a test run via the cloud API
  • Receives a test run ID for metric correlation
  • Optionally uploads the test archive
    • 4
    Execution
    5
    During the test:
    6
  • Metrics are buffered locally
  • Samples are aggregated periodically
  • Batches are sent to the ingest service
  • Real-time results appear in the web UI
    • 7
    Finalization
    8
    When the test completes:
    9
  • Remaining metrics are flushed
  • Final threshold results are sent
  • Test run status is updated (finished, aborted, etc.)
  • Summary is displayed with results URL

    • ​
    Required System Tags

    The cloud output requires these system tags to be enabled (internal/output/cloud/output.go:158):
    • name: Request/metric name
    • method: HTTP method
    • status: HTTP status code
    • error: Error information
    • check: Check name
    • group: Group hierarchy
    These tags are enabled by default. Only disable them if you understand the impact on cloud result analysis.

    ​
    Test Run Status

    The cloud output reports detailed test run status (cloudapi/run_status.go):
    • Finished: Test completed normally
    • Aborted by user: User interrupted (Ctrl+C)
    • Aborted by threshold: Threshold failure triggered abort
    • Aborted by script error: Script error caused early termination
    • Aborted by timeout: Test exceeded time limit
    • Aborted by system: Infrastructure or cloud service issue

    ​
    Direct Metric Pushing

    You can push metrics directly to an existing test run without creating a new one: 
    export K6_CLOUD_PUSH_REF_ID=existing_test_run_id
k6 run --out cloud script.js
    This is useful for:
    • Resuming interrupted tests
    • Multiple k6 instances pushing to the same test run
    • Custom test orchestration

    ​
    Archive Upload

    By default, k6 uploads the test archive (script + dependencies) to the cloud. Disable this with: 
    k6 run --out cloud --no-archive-upload script.js
    The archive is required for cloud execution but optional when only streaming results from local tests.

    ​
    Cloud vs Local Testing

    The same cloud output is used for:
    1. Local tests with cloud results: Run locally, stream results to cloud
    2. Cloud execution: Run tests on k6 Cloud infrastructure
    Configuration is largely identical, but cloud execution provides:
    • Distributed load generation
    • Geographic load zones
    • Larger scale capabilities
    • No local resource constraints

    ​
    API Versioning

    The cloud output supports API version 2 (default): 
    export const options = {
  cloud: {
    apiVersion: 2,
  },
};
    API version 1 is no longer supported. All tests must use version 2.

    ​
    Error Handling

    The cloud output can stop the test if cloud API errors occur: 
    export const options = {
  cloud: {
    stopOnError: true,
  },
};
    This ensures test runs don’t continue if metrics can’t be streamed.

    ​
    Troubleshooting

    ​
    Authentication Failures

    If you see authentication errors:
    1. Verify your token is valid: k6 login cloud
    2. Check token environment variable: echo $K6_CLOUD_TOKEN
    3. Ensure project ID is correct

    ​
    Connectivity Issues

    For connection problems:
    1. Verify you can reach the ingest endpoint
    2. Check firewall/proxy settings
    3. Try increasing the timeout value
    4. Enable debug logging: k6 run --verbose --out cloud script.js

    ​
    Missing Metrics

    If metrics aren’t appearing:
    1. Confirm required system tags are enabled
    2. Check test run URL for errors
    3. Verify metric names are valid
    4. Review aggregation settings
    Use --verbose flag to see detailed cloud output logs including API requests and metric batch information.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us