# grafana/k6 architecture

> Architecture diagram of the GitHub repository grafana/k6, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/grafana/k6
- Repository: https://github.com/grafana/k6

## Overview

Grafana k6 is a developer-facing, scriptable load-testing runtime. A user invokes its CLI with a JavaScript test; k6 resolves and runs the script with virtual users and protocol APIs, aggregates metrics and evaluates thresholds, then presents or exports results. The map preserves documented protocol, browser, extensibility, and Grafana Cloud capabilities, with metrics processing as an internal layer. Relationships for unsampled subsystems are documented at capability level only; source-level call paths are included only where the excerpts or SOURCE INDEX support them.

Main entry points: [`lib/executor/ramping_vus.go`](https://github.com/grafana/k6/blob/master/lib/executor/ramping_vus.go) (Load scheduling), [`internal/js/runner.go`](https://github.com/grafana/k6/blob/master/internal/js/runner.go) (JS runner), [`internal/metrics/engine/engine.go`](https://github.com/grafana/k6/blob/master/internal/metrics/engine/engine.go) (Metrics engine), [`js/modules/resolution.go`](https://github.com/grafana/k6/blob/master/js/modules/resolution.go) (Module resolution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and scripting"]
  node_cli_entry["CLI entry<br/>[main.go]"]
  node_commands["CLI commands<br/>[root.go]"]
  node_module_resolution["Module resolution<br/>[resolution.go]"]
  node_extensions["Extensions<br/>[ext.go]"]
end

subgraph group_runtime["Execution runtime"]
  node_runner["JS runner<br/>[runner.go]"]
  node_load_generator["Load scheduling<br/>[ramping_vus.go]"]
end

subgraph group_protocols["Protocol APIs"]
  node_http_module["HTTP API<br/>[http.go]"]
  node_browser["Browser automation<br/>[frame_manager.go]"]
  node_browser_network["Browser networking<br/>[network_manager.go]"]
  node_grpc["gRPC API<br/>[client.go]"]
  node_websockets["WebSockets API<br/>[websockets.go]"]
  node_streams["Streams API"]
end

subgraph group_results["Metrics and results"]
  node_metrics_registry["Metric registry<br/>[registry.go]"]
  node_metrics_engine["Metrics engine<br/>[engine.go]"]
  node_output_manager["Output manager<br/>[manager.go]"]
  node_summary["Test summary<br/>[summary.go]"]
  node_http_api["HTTP API<br/>[server.go]"]
  node_loki["Loki logging<br/>[loki.go]"]
  node_prometheus_output["Prometheus output<br/>[client.go]"]
end

subgraph group_cloud["Cloud services"]
  node_cloud_cli["Cloud commands<br/>[cloud_run.go]"]
  node_cloud_api["Cloud API client<br/>[client.go]"]
  node_cloud_insights["Cloud insights<br/>[client.go]"]
  node_cloud_output["Cloud metrics output<br/>[output.go]"]
end

node_user(("Test author"))
node_cloud_service(("Grafana Cloud"))
node_test_script["JavaScript test"]

node_user -->|"runs"| node_cli_entry
node_cli_entry -->|"dispatches"| node_commands
node_commands -.->|"loads scripts"| node_module_resolution
node_module_resolution -->|"resolves extensions"| node_extensions
node_module_resolution -.->|"prepares modules"| node_runner
node_test_script -->|"executes as"| node_runner
node_runner -.->|"runs virtual users"| node_load_generator
node_load_generator -->|"generates traffic"| node_http_module
node_load_generator -->|"runs browser workloads"| node_browser
node_load_generator -->|"generates traffic"| node_grpc
node_load_generator -->|"generates traffic"| node_websockets
node_browser -.->|"manages requests"| node_browser_network
node_runner -->|"exposes API"| node_streams
node_runner -.->|"defines metrics"| node_metrics_registry
node_metrics_registry -->|"provides metrics"| node_metrics_engine
node_metrics_engine -.->|"aggregates samples"| node_output_manager
node_output_manager -->|"dispatches samples"| node_prometheus_output
node_output_manager -.->|"dispatches samples"| node_cloud_output
node_metrics_engine -.->|"supports results"| node_summary
node_metrics_engine -->|"serves test state"| node_http_api
node_user -->|"manages cloud tests"| node_cloud_cli
node_cloud_cli -.->|"calls lifecycle API"| node_cloud_api
node_cloud_output -.->|"sends insights"| node_cloud_insights
node_cloud_output -->|"uploads metrics"| node_cloud_service
node_cloud_api -->|"manages test runs"| node_cloud_service
node_loki -.->|"ships logs"| node_cloud_service

click node_cli_entry "https://github.com/grafana/k6/blob/master/main.go"
click node_commands "https://github.com/grafana/k6/blob/master/internal/cmd/root.go"
click node_module_resolution "https://github.com/grafana/k6/blob/master/js/modules/resolution.go"
click node_extensions "https://github.com/grafana/k6/blob/master/ext/ext.go"
click node_runner "https://github.com/grafana/k6/blob/master/internal/js/runner.go"
click node_load_generator "https://github.com/grafana/k6/blob/master/lib/executor/ramping_vus.go"
click node_metrics_registry "https://github.com/grafana/k6/blob/master/metrics/registry.go"
click node_metrics_engine "https://github.com/grafana/k6/blob/master/internal/metrics/engine/engine.go"
click node_output_manager "https://github.com/grafana/k6/blob/master/output/manager.go"
click node_summary "https://github.com/grafana/k6/blob/master/internal/output/summary/summary.go"
click node_http_api "https://github.com/grafana/k6/blob/master/internal/api/server.go"
click node_http_module "https://github.com/grafana/k6/blob/master/js/modules/k6/http/http.go"
click node_browser "https://github.com/grafana/k6/blob/master/internal/js/modules/k6/browser/common/frame_manager.go"
click node_browser_network "https://github.com/grafana/k6/blob/master/internal/js/modules/k6/browser/common/network_manager.go"
click node_grpc "https://github.com/grafana/k6/blob/master/internal/js/modules/k6/grpc/client.go"
click node_websockets "https://github.com/grafana/k6/blob/master/internal/js/modules/k6/websockets/websockets.go"
click node_streams "https://github.com/grafana/k6/blob/master/internal/js/modules/k6/experimental/streams/readable_stream_default_controller.go"
click node_loki "https://github.com/grafana/k6/blob/master/internal/log/loki.go"
click node_cloud_cli "https://github.com/grafana/k6/blob/master/internal/cmd/cloud_run.go"
click node_cloud_api "https://github.com/grafana/k6/blob/master/internal/cloudapi/v6/client.go"
click node_cloud_insights "https://github.com/grafana/k6/blob/master/internal/cloudapi/insights/client.go"
click node_cloud_output "https://github.com/grafana/k6/blob/master/internal/output/cloud/output.go"
click node_prometheus_output "https://github.com/grafana/k6/blob/master/internal/output/prometheusrw/remote/client.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_entry,node_commands,node_module_resolution,node_extensions toneBlue
class node_runner,node_load_generator toneAmber
class node_http_module,node_browser,node_browser_network,node_grpc,node_websockets,node_streams toneMint
class node_metrics_registry,node_metrics_engine,node_output_manager,node_summary,node_http_api,node_loki,node_prometheus_output toneRose
class node_cloud_cli,node_cloud_api,node_cloud_insights,node_cloud_output,node_user,node_cloud_service,node_test_script toneIndigo
```

## Components

### CLI and scripting

- [CLI entry](https://github.com/grafana/k6/blob/master/main.go): `main.go`
- [CLI commands](https://github.com/grafana/k6/blob/master/internal/cmd/root.go): `internal/cmd/root.go`
- [Module resolution](https://github.com/grafana/k6/blob/master/js/modules/resolution.go): `js/modules/resolution.go`
- [Extensions](https://github.com/grafana/k6/blob/master/ext/ext.go): `ext/ext.go`

### Execution runtime

- [JS runner](https://github.com/grafana/k6/blob/master/internal/js/runner.go): `internal/js/runner.go`
- [Load scheduling](https://github.com/grafana/k6/blob/master/lib/executor/ramping_vus.go): `lib/executor/ramping_vus.go`

### Protocol APIs

- [HTTP API](https://github.com/grafana/k6/blob/master/js/modules/k6/http/http.go): `js/modules/k6/http/http.go`
- [Browser automation](https://github.com/grafana/k6/blob/master/internal/js/modules/k6/browser/common/frame_manager.go): `internal/js/modules/k6/browser/common/frame_manager.go`
- [Browser networking](https://github.com/grafana/k6/blob/master/internal/js/modules/k6/browser/common/network_manager.go): `internal/js/modules/k6/browser/common/network_manager.go`
- [gRPC API](https://github.com/grafana/k6/blob/master/internal/js/modules/k6/grpc/client.go): `internal/js/modules/k6/grpc/client.go`
- [WebSockets API](https://github.com/grafana/k6/blob/master/internal/js/modules/k6/websockets/websockets.go): `internal/js/modules/k6/websockets/websockets.go`
- [Streams API](https://github.com/grafana/k6/blob/master/internal/js/modules/k6/experimental/streams/readable_stream_default_controller.go): `internal/js/modules/k6/experimental/streams/readable_stream_default_controller.go`

### Metrics and results

- [Metric registry](https://github.com/grafana/k6/blob/master/metrics/registry.go): `metrics/registry.go`
- [Metrics engine](https://github.com/grafana/k6/blob/master/internal/metrics/engine/engine.go): `internal/metrics/engine/engine.go`
- [Output manager](https://github.com/grafana/k6/blob/master/output/manager.go): `output/manager.go`
- [Test summary](https://github.com/grafana/k6/blob/master/internal/output/summary/summary.go): `internal/output/summary/summary.go`
- [HTTP API](https://github.com/grafana/k6/blob/master/internal/api/server.go): `internal/api/server.go`
- [Loki logging](https://github.com/grafana/k6/blob/master/internal/log/loki.go): `internal/log/loki.go`
- [Prometheus output](https://github.com/grafana/k6/blob/master/internal/output/prometheusrw/remote/client.go): `internal/output/prometheusrw/remote/client.go`

### Cloud services

- [Cloud commands](https://github.com/grafana/k6/blob/master/internal/cmd/cloud_run.go): `internal/cmd/cloud_run.go`
- [Cloud API client](https://github.com/grafana/k6/blob/master/internal/cloudapi/v6/client.go): `internal/cloudapi/v6/client.go`
- [Cloud insights](https://github.com/grafana/k6/blob/master/internal/cloudapi/insights/client.go): `internal/cloudapi/insights/client.go`
- [Cloud metrics output](https://github.com/grafana/k6/blob/master/internal/output/cloud/output.go): `internal/output/cloud/output.go`

### Other components

- **Test author**
- **Grafana Cloud**
- **JavaScript test**

## Connections

- Test author → CLI entry: runs
- CLI entry → CLI commands: dispatches (evidence: `main.go`)
- CLI commands → Module resolution: loads scripts
- Module resolution → Extensions: resolves extensions (evidence: `js/modules/resolution.go`)
- Module resolution → JS runner: prepares modules
- JavaScript test → JS runner: executes as
- JS runner → Load scheduling: runs virtual users
- Load scheduling → HTTP API: generates traffic
- Load scheduling → Browser automation: runs browser workloads
- Load scheduling → gRPC API: generates traffic
- Load scheduling → WebSockets API: generates traffic
- Browser automation → Browser networking: manages requests
- JS runner → Streams API: exposes API
- JS runner → Metric registry: defines metrics
- Metric registry → Metrics engine: provides metrics (evidence: `internal/metrics/engine/engine.go`)
- Metrics engine → Output manager: aggregates samples
- Output manager → Prometheus output: dispatches samples (evidence: `output/manager.go`)
- Output manager → Cloud metrics output: dispatches samples
- Metrics engine → Test summary: supports results
- Metrics engine → HTTP API: serves test state (evidence: `internal/api/server.go`)
- Test author → Cloud commands: manages cloud tests
- Cloud commands → Cloud API client: calls lifecycle API
- Cloud metrics output → Cloud insights: sends insights
- Cloud metrics output → Grafana Cloud: uploads metrics
- Cloud API client → Grafana Cloud: manages test runs
- Loki logging → Grafana Cloud: ships logs
