Tags and Groups

A load test usually targets a service with different subsystems and resources. This can make it hard to pinpoint the issues that are degrading performance.

To help you visualize, sort, and filter your test results, k6 adds the following to your results.

• Tags categorize your checks, thresholds, custom metrics, and requests for in-depth filtering.
• Groups apply tags to the script's functions.

Besides these granular tags, you can also use options to set test-wide tags. You can use these tags to compare results from multiple tests.

In addition to filtering results, you can also use tags to limit the operations that your thresholds analyze.

Tags

Tags are a powerful way to categorize your k6 entities and filter test results.

k6 provides two types of tags:

• System tags. Tags that k6 automatically assigns.
• User-defined tags. Tags that you add when you write your script.

System tags

Currently, k6 automatically creates the following tags by default:

To disable some of the preceding tags, use the systemTags option. Note that some data collectors, for example cloud runs, may require certain tags.

The following system tags are optional. Enable them as needed:

User-defined tags

Define your own tags to categorize k6 entities based on your test logic. You can tag the following entities:

• requests
• checks
• thresholds
• custom metrics

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

Test-wide tags

Besides attaching tags to requests, checks, and custom metrics, you can set test-wide tags across all metrics. You can set these tags in two ways:

• In the CLI, using one or more --tag NAME=VALUE flags

• In the script itself:

  test-wide-tags.js

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

  Copy

Code-defined tags

In the case, a user-defined tag with advanced logic for handling which tag to set is required then it's possible doing it by defining the tag from the code.

To support advanced tagging workflows, it is also possible to directly set and get them from scripts' code.

k6/execution.vu.tags object's properties can indeed be directly assigned new key/value pairs to define new tags dynamically. This can prove useful, as demonstrated in the following example, to track a container's group from nested groups, and aggregating nested group's sub-metrics.

import http from 'k6/http';
import exec from 'k6/execution';
import { group } from 'k6';

export const options = {
  thresholds: {
    'http_reqs{container_group:main}': ['count==3'],
    'http_req_duration{container_group:main}': ['max<1000'],
  },
};

export default function () {
  exec.vu.tags.containerGroup = 'main';

  group('main', function () {
    http.get('https://test.k6.io');
    group('sub', function () {
      http.get('https://httpbin.test.k6.io/anything');
    });
    http.get('https://test-api.k6.io');
  });

  delete exec.vu.tags.containerGroup;

  http.get('https://httpbin.test.k6.io/delay/3');
}

Using the same API, you can also retrieve any already set user-defined or system-defined tag:

import exec from 'k6/execution';

export default function () {
  const tag = exec.vu.tags['scenario'];
  console.log(tag); // default
}

Tagging stages

Thanks to some helper functions in the k6-jslib-utils project, if an executor supports the stages option, you can add tags with the current ongoing stage. Similar to other tags tag, the tag is added to all samples collected during the iteration.

One way to tag the executed operations is to invoke the tagWithCurrentStageIndex function for setting a stage tag for identifying the stage that has executed them:

import http from 'k6/http';
import exec from 'k6/execution';
import { tagWithCurrentStageIndex } from 'https://jslib.k6.io/k6-utils/1.3.0/index.js';

export const options = {
  stages: [
    { target: 5, duration: '5s' },
    { target: 10, duration: '10s' },
  ],
};

export default function () {
  tagWithCurrentStageIndex();

  // all the requests will have a `stage` tag
  // with its value equal to the index of the stage
  http.get('https://test.k6.io'); // e.g. {stage: "1"}
}

Additionally, a profiling function tagWithCurrentStageProfile can add a tag with a computed profile of the current running stage:

import http from 'k6/http';
import exec from 'k6/execution';
import { tagWithCurrentStageProfile } from 'https://jslib.k6.io/k6-utils/1.3.0/index.js';

export const options = {
  stages: [{ target: 10, duration: '10s' }],
};

export default function () {
  tagWithCurrentStageProfile();

  // all the requests are tagged with a `stage` tag
  // with the index of the stage as value
  http.get('https://test.k6.io'); // {stage_profile: ramp-up}
}

The profile value based on the current stage can be one of the following options:

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.test.k6.io/get "
11    }
12  },
13  "metric ": "http_req_duration "
14}

To see how tags affect your test-result output, refer to the k6 results output syntax.

Groups

For extra organization, use groups to organize a load script by functions. You can also nest groups for BDD-style testing.

All metrics emitted in a group have the tag group with a value of all wrapping group names separated by :: (two colons). The root group uses the name '' (empty string). If you have a single group named cool requests, the actual value of the group is ::cool requests.

For example, you could use groups to organize multiple requests by page loads or user actions.

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

Groups do the following tasks internally:

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

• When a taggable resource—a check, request, or custom metric—runs within a group, k6 sets the tag group with the current group name. For more info, refer to the Tags section.

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

Discouraged: one group per request

Wrapping each request within a group might add unnecessary boilerplate.

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

If your code looks like the preceding snippet, consider the following strategies 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.
• To model advanced user patterns, check out Scenarios.