Tags and Groups

The analysis of your load results is a required step to find performance issues; a load test usually targets a service involving different subsystems and resources, making it hard to find the issue/s degrading your performance.

k6 provides two scripting APIs to help you during the analysis and easily visualize, sort and filter your test results.

• Groups: organize your load script around common logic.
• Tags: categorize your checks, thresholds, custom metrics and requests with tags for in-depth filtering.

Groups

Groups are optional, and it allows you to “group” a large load script to help you with the test result analysis. Groups can be nested, allowing you the BDD-style of testing.

This makes all metrics emitted in a group to have the tag group with a value of all group names wrapping it separated by '::' (two colons). There is also a default/root group with the name '' (empty string) which means that if you just have a single group named 'cool requests' the actual value of the group tag will be ::cool requests.

For example, you could use groups to organize multiple requests due to loading a page or executing a user action.

1import { group } from 'k6';
2
3export default function () {
4
5  group('visit product listing page', function () {
6    // ...
7  });
8  group('add several products to the shopping cart', function () {
9    // ...
10  });
11  group('visit login page', function () {
12    // ...
13  });
14  group('authenticate', function () {
15    // ...
16  });
17  group('checkout process', function () {
18    // ...
19  });
20
21}

Groups do the following tasks internally:

• For each group() function, k6 emits a group_duration metric that contains the total time to execute the group function.

• When a taggable resource: checks, requests, or custom metrics runs within a group, k6 will set the tag group with the current group name. Read more about it in Tags.

Both options, the group_duration metric and group tagging, could help you analyze and visualize better the results of more complex tests. Check out how they work in your k6 result output.

Discouraged use cases

Wrapping each individual request within a group might add boilerplate code and be unnecessary.

1// reconsider this type of code
2group('get post', function () {
3   http.get(`http://example.com/posts/${id}`);
4});
5group('list posts', function () {
6   let res = http.get(`http://example.com/posts`);
7   check(res, {
8     'is status 200': (r) => r.status === 200,
9   });
10});

If your code looks like the example above, consider the following alternatives to write cleaner code:

• For dynamic URLs, use the URL grouping feature.
• To provide a meaningful name to your request, set the value of tags.name.
• To reuse common logic or organize your code better, group logic in functions or create a local Javascript module and import it into the test script.
• If you need to model advanced user patterns, check out Scenarios.

Tags

Tags are a simple and powerful way to categorize your k6 entities for later results filtering.

k6 provides two types of tags:

• User-defined tags: the ones you've added when writing your script.
• System tags: tags automatically assigned by k6.

System tags

Currently, k6 automatically creates the following tags by default:

If you choose, you could disable some of the above tags by using the systemTags option, just keep in mind that some data collectors (e.g. cloud) may require that certain tags be present. Also, you can enable some additional system tags, if you need them:

User-defined tags

User-defined tags allow you to categorize k6 entities based on your logic. The following entities can be tagged:

• checks
• thresholds
• custom metrics
• requests

1import http from 'k6/http';
2import { Trend } from 'k6/metrics';
3import { check } from 'k6';
4
5let myTrend = new Trend('my_trend');
6
7export default function () {
8  // Add tag to request metric data
9  let res = http.get('http://httpbin.org/', {
10    tags: {
11      my_tag: "I'm a tag",
12    },
13  });
14
15  // Add tag to check
16  check(
17    res,
18    { 'status is 200': (r) => r.status === 200 },
19    { my_tag: "I'm a tag" },
20  );
21
22  // Add tag to custom metric
23  myTrend.add(res.timings.connecting, { my_tag: "I'm a tag" });
24}

Test wide tags

Besides attaching tags on requests, checks and custom metrics you can set test wide tags that will be set across all metrics. You can either set the tags on the CLI using one or more --tag NAME=VALUE flags or in the script:

1export let options = {
2  tags: {
3    name: 'value',
4  },
5};

Tags in results output

1{
2  "type ": "Point ",
3  "data ": {
4    "time ": "2017-05-09T14:34:45.239531499+02:00 ",
5    "value ": 459.865729,
6    "tags ": {
7      "group ": "::my group::json ",
8      "method ": "GET ",
9      "status ": "200 ",
10      "url ": "https://httpbin.org/get "
11    }
12  },
13  "metric ": "http_req_duration "
14}

Read more about the k6 results output syntax to see how tags affect your test result output.

Tags and Groups in k6 Cloud Results

In k6 Cloud Results you can see groups in the result tabs.

When using Groups, Checks and HTTP Requests can be viewed by group, as shown below. You can switch between the group and list layout by changing the "view as" selection in the top right.

Additionally you can filter the results by tags in the analysis tab.