> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/grafana/k6/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
k6 login cloud
```

Or set the token directly:

```bash theme={null}
export K6_CLOUD_TOKEN=your_token_here
```

## Basic Usage

Run a test with cloud output:

```bash theme={null}
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:

```javascript theme={null}
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:

```bash theme={null}
export K6_CLOUD_NAME="My Test Run"
export K6_CLOUD_PROJECT_ID=12345
export K6_CLOUD_HOST="https://ingest.k6.io"
```

<Note>
  Environment variables take precedence over script options, allowing you to override settings without modifying test code.
</Note>

## 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)

<Warning>
  The `metricPushConcurrency` and `maxTimeSeriesInBatch` settings can significantly impact network usage and cloud ingest performance. Adjust carefully based on your test scale.
</Warning>

## Test Run Lifecycle

<Steps>
  ### Initialization

  When the output starts, it:

  1. Validates required system tags are enabled
  2. Creates a test run via the cloud API
  3. Receives a test run ID for metric correlation
  4. Optionally uploads the test archive

  ### Execution

  During the test:

  1. Metrics are buffered locally
  2. Samples are aggregated periodically
  3. Batches are sent to the ingest service
  4. Real-time results appear in the web UI

  ### Finalization

  When the test completes:

  1. Remaining metrics are flushed
  2. Final threshold results are sent
  3. Test run status is updated (finished, aborted, etc.)
  4. Summary is displayed with results URL
</Steps>

## 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

<Tip>
  These tags are enabled by default. Only disable them if you understand the impact on cloud result analysis.
</Tip>

## 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:

```bash theme={null}
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:

```bash theme={null}
k6 run --out cloud --no-archive-upload script.js
```

<Note>
  The archive is required for cloud execution but optional when only streaming results from local tests.
</Note>

## 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):

```javascript theme={null}
export const options = {
  cloud: {
    apiVersion: 2,
  },
};
```

<Warning>
  API version 1 is no longer supported. All tests must use version 2.
</Warning>

## Error Handling

The cloud output can stop the test if cloud API errors occur:

```javascript theme={null}
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

<Tip>
  Use `--verbose` flag to see detailed cloud output logs including API requests and metric batch information.
</Tip>