Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 36 ยท Concepts and Scripts

Groups and Tags

Organize k6 results with group() and tags, tag requests and whole tests, keep URL cardinality low with the name tag, and create sub-metrics that thresholds and dashboards can filter on.

A busy load test sends thousands of requests to dozens of URLs. A single "average response time" for all of them is useless: the home page and the report-generation endpoint have very different expectations. Tags and groups let you slice the data. Tags attach labels to data points, so you can ask "what was p(95) for endpoint:search?". Groups wrap related steps into a named block, such as a checkout flow, and k6 records how long the block took.

Built-in tags

Every metric data point already carries tags that k6 adds automatically. The most useful ones for HTTP are:

Tag Example value
method GET
url http://localhost:3000/products/42
name by default the same as url
status 200
scenario default
group ::checkout
expected_response true
proto HTTP/1.1

You can filter any of these in thresholds, in Grafana dashboards and in the JSON output.

Custom tags on a request

Add your own labels in the tags field of a request's params:

JavaScript
http.get(`${BASE}/search?q=shoes`, { tags: { endpoint: 'search', team: 'discovery' } });

Now http_req_duration{endpoint:search} is a sub-metric you can use in a threshold:

JavaScript
export const options = {
  thresholds: {
    'http_req_duration{endpoint:search}': ['p(95)<400'],
    'http_req_duration{endpoint:checkout}': ['p(95)<900'],
  },
};

You can tag a whole test with options.tags, which is how you label runs by environment or build number:

JavaScript
export const options = {
  tags: { env: 'staging', build: __ENV.BUILD_ID || 'local' },
};

The name tag: avoiding a metric explosion

If your script requests /products/1, /products/2, ... /products/10000, every URL becomes its own url tag value, and output systems create one time series per URL. This is called high cardinality; it bloats memory, slows your dashboards and can even crash backends. The fix is to give all of them the same name tag:

JavaScript
const id = Math.ceil(Math.random() * 10000);
http.get(`${BASE}/products/${id}`, { tags: { name: 'ProductDetail' } });

Now results group under name:ProductDetail. k6 offers a template-literal helper too, http.url, which does the same thing:

JavaScript
http.get(http.url`${BASE}/products/${id}`); // name tag becomes .../products/${}

As a rule: never put unbounded values (ids, timestamps, random tokens) in a tag. Use name for dynamic URLs and keep custom tag values to a small, fixed set.

group()

group(name, fn) wraps a block of code. k6 tags every request inside with group and records a group_duration trend metric for the block.

JavaScript
import http from 'k6/http';
import { group, sleep } from 'k6';

export default function () {
  group('browse', () => {
    http.get(`${BASE}/`);
    http.get(`${BASE}/products`);
  });

  group('checkout', () => {
    http.post(`${BASE}/cart`, JSON.stringify({ sku: 'A1' }), JSON_HEADERS);
    http.post(`${BASE}/orders`, null, JSON_HEADERS);
  });

  sleep(1);
}

Groups can be nested; the tag then shows the path, for example ::checkout::payment. Two cautions:

  • group() takes a synchronous function. Do not use async callbacks or await inside; k6 would finish the group before the awaited code runs.
  • Do not use groups for fine-grained timing of single requests; use the request's own metrics or a custom Trend.

Groups versus tags: groups are best for journey steps and give you total time per step; tags are best for dimensions (endpoint, region, customer tier) you want to filter thresholds on. They combine well, since the group name is also a tag.

Aggregating by tag yourself

The next program is not k6. It models what k6 does with tags: every data point carries a tags object, and summaries are computed per tag value. It sends requests to a server with a fast and a slow endpoint, tags the points, and reports per-endpoint stats. The slow endpoint is made slower by at least 25 ms, so the comparison is stable.

Node.js Stand-in: statistics per tag

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.

Ten different search URLs collapse to a single Search series. That is exactly the benefit of the name tag.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should you set the name tag when requesting URLs like /products/123 with many different ids?

    Giving all dynamic URLs the same name tag groups them into one series and keeps memory and output size under control.
  2. 2. How do you write a threshold that applies only to requests tagged endpoint:search?

    Sub-metrics use curly braces with tag:value pairs.
  3. 3. What is wrong with using an async callback inside group()?

    k6 groups only work with synchronous callbacks. Async code would run outside the group's scope.
  4. 4. Which is best for a tag value?

    Tag values should come from a small bounded set to avoid cardinality explosions.

Summary

  • Tags label data points; groups label blocks of steps and record group_duration.
  • Add tags per request (params.tags) or for the whole test (options.tags).
  • Use the name tag (or http.url) for dynamic URLs; never tag with unbounded values.
  • Filter with metric{tag:value} in thresholds and dashboards.
  • group() takes synchronous code only.

Next: Test Data and Environment Variables