Grafana Cloud k6 Integration

Stream k6 test results to Grafana Cloud k6 for real-time monitoring and analysis

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

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.