Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 36 ยท Results and Metrics

k6 End-of-Test Summary, handleSummary and Outputs

Customize the k6 end-of-test summary with handleSummary, export JSON and HTML reports, stream metrics with --out to JSON, CSV or Prometheus, and use the web dashboard live.

By default k6 prints a summary to the terminal and exits. That is perfect while you are developing a script, and useless once you want a report to attach to a pull request, numbers to compare across runs, or live graphs during a one-hour soak test. k6 offers two mechanisms: the summary (aggregated numbers at the end) and outputs (every individual data point, streamed while the test runs).

Honesty note. k6 cannot run on this site, so scripts and command lines here are read-only. The runnable blocks are Node stand-ins that process summary-shaped and JSON-lines-shaped data in the same way you would after a real run.

The summary object and handleSummary

If your script exports handleSummary(data), k6 calls it at the end and replaces the default terminal summary with whatever you return. The return value is an object whose keys are destinations and whose values are the content:

JavaScript
import { textSummary } from 'https://jslib.k6.io/k6-summary/0.1.0/index.js';

export function handleSummary(data) {
  return {
    stdout: textSummary(data, { indent: '  ', enableColors: true }), // keep the normal table
    'summary.json': JSON.stringify(data, null, 2),                   // full data for scripts
    'report.txt': `p95: ${data.metrics.http_req_duration.values['p(95)']} ms\n`,
  };
}
  • Key stdout or stderr writes to the terminal; any other key is a file path.
  • If you return only files and no stdout, the terminal summary disappears. Include stdout when you still want to see it.
  • data.metrics contains every metric with its type, contains (value type, e.g. time) and values. For trends the keys are avg, min, med, max, p(90), p(95); for rates rate, passes, fails; for counters count and rate.
  • data.root_group holds the group tree and checks; data.state holds run information such as the duration.

The exact data layout evolves between k6 releases. The reliable workflow is to run once with 'debug.json': JSON.stringify(data) and read the file before writing code against it.

The quickest alternative needs no code: k6 run --summary-export=summary.json script.js writes a machine-readable summary, and --summary-mode=full (or compact, legacy) controls how much the terminal prints.

Node.js Stand-in: a handleSummary that builds a text report and a pass/fail line

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Outputs: streaming every data point

An output receives each sample as it is produced. You select one with --out (repeat the flag for several):

Terminal
k6 run --out json=points.json script.js
k6 run --out csv=points.csv script.js
k6 run --out experimental-prometheus-rw script.js   # Prometheus remote write
k6 run --out opentelemetry script.js                # experimental, OTLP
k6 run --out cloud script.js                        # Grafana Cloud k6 (needs login)

The available outputs depend on your k6 version and extensions; k6 run --help lists them. Other backends such as InfluxDB or Kafka are provided by extensions built with xk6.

The JSON output writes one JSON object per line (JSON Lines):

JSON
{"type":"Metric","data":{"type":"trend","contains":"time","thresholds":[],"submetrics":null},"metric":"http_req_duration"}
{"type":"Point","data":{"time":"2024-03-04T10:00:01Z","value":112.4,"tags":{"name":"Search","status":"200"}},"metric":"http_req_duration"}

Metric lines declare metrics, Point lines are samples. A file for a long test can be gigabytes, so prefer an aggregating backend for big runs, and use --out json=points.json.gz to compress.

Node.js Stand-in: aggregating JSON Lines output yourself

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The web dashboard

Recent k6 versions include a built-in web dashboard that serves live charts while a test runs, and can export a standalone HTML report when it ends:

Terminal
K6_WEB_DASHBOARD=true K6_WEB_DASHBOARD_EXPORT=report.html k6 run script.js

Open http://localhost:5665 during the run for live graphs. The exported HTML file is a handy artifact for CI. See k6 in CI pipelines to attach it to a build.

Choosing a destination

Need Use
Quick look in the terminal Default summary
A file to parse in CI --summary-export or handleSummary JSON
A human-readable report HTML via the web dashboard export, or your own handleSummary
Time-series history and Grafana graphs An output such as Prometheus remote write or Grafana Cloud k6 (see Grafana Cloud k6)
Debugging individual requests --out json or --http-debug

Remember that the end-of-test summary is aggregated, so a 10-second spike inside a one-hour test is invisible in it. Only time-series outputs reveal when something happened.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens to the default terminal summary if handleSummary returns only a file key?

    handleSummary replaces the default output. Include stdout (for example via textSummary) to keep the terminal table.
  2. 2. In the JSON output, what does a line with type 'Point' represent?

    Each Point line is one measurement; Metric lines declare the metrics themselves.
  3. 3. Why can the end-of-test summary miss a short spike?

    Percentiles and averages over the whole run hide when something happened. Time-series outputs show it.
  4. 4. How do you enable the k6 web dashboard export to an HTML file?

    The two environment variables turn on the dashboard and write a standalone HTML report at the end.

Summary

  • handleSummary(data) replaces the default summary; keys are stdout, stderr or file paths.
  • --out streams every sample (JSON, CSV, Prometheus, cloud); the summary only has aggregates.
  • The web dashboard gives live charts and an HTML report.
  • Print data once to learn its exact shape for your k6 version.

Next: k6 in CI Pipelines