Customization

This page is about configuration customization.

The long-term goal is to eliminate the need for customization. Many features have already been created that partially make customization unnecessary (foldable sections, gRPC, browser, WebSockets charts). Until the development reaches this long-term goal, it is possible to customize the dashboard configuration.

Warning

The customization of the configuration is not an official dashboard feature, use at your own risk. It is possible that the customization changes in a way that is not backward compatible.

Configuration

The dashboard configuration is a JSON object. The default configuration can be found here. Since this is the internal configuration of the dashboard, it is not intended to be documented for the user. It can change at any time during a refactor.

The recommended way to customize the dashboard is to use the JavaScript helper library published on this page.

JSON Configuration

The JSON configuration can be specified in a file with the extension .json. The name of the configuration file must be set in the environment variable called XK6_DASHBOARD_CONFIG. It can also be specified in the .dashboard.json file created in the current directory.

JavaScript Configuration

The actual configuration can be modified (or a new one can be generated) using a JavaScript configuration. The name of the file containing the JavaScript code that generates the configuration must be set in the environment variable XK6_DASHBOARD_CONFIG. The file extension must be .js. In addition, the JavaScript code can also be specified in the .dashboard.js file created in the current directory.

The default export of the JavaScript configuration file must be a function. The function receives the current configuration object as a parameter, it must return the modified (or new) configuration object.

export default function(config) {
  // modify or create config
  return config
}

The standard logging methods of the console object can be used for logging. These log entries are added to the k6 log.

Helpers

The helper functions can be found in the dot-dashboard-helpers.js file. Copy the contents of this file to the end of your JavaScript configuration file.

TabBuilder

You can use the TabBuilder helper function to create a new tab:

export default function(config) {
  let tab = new TabBuilder(config)

  tab("Custom Tab", ({ section }) => {
    section("My Section", ({ panel }) => {
      // ...
    })
  })

  return config
}

Using the helper, you can create any number of tabs, sections and panels:

export default function(config) {
  let tab = new TabBuilder(config)

  tab("Custom Tab 1", ({ section }) => {
    section("My Section 1", ({ panel }) => {
      // ...
    })

    section("My Section 2", ({ panel }) => {
      // ...
    })
  })

  tab("Custom Tab2", ({ section }) => {
    // ...
  })

  return config
}

tab

section

panel

serie

Example

The example below defines a tab named Custom, inside it a collapsible section named Sample Section, inside it a panel named ̇Sample Panel. The panel is full width and displays three metrics.

To try it out, download the .dashboard.js file and copy it to your current directory. It takes effect during the next k6 run.

export default function (config) {
  const tab = new TabBuilder(config);

  tab("Custom", ({ section }) => {
    section("Sample Section", ({ panel }) => {
      panel("Sample Panel", ({ panel, serie }) => {
        panel.summary = "Example full width panel";
        panel.fullWidth = true;

        serie("http_reqs[?!tags && rate]", "Request Rate");
        serie("http_req_duration[?!tags && p95]", "Request Duration p(95)");
        serie("http_req_failed[?!tags && rate ]", "Request Failed");
      });
    });
  });

  return config;
}

// The helper code follows, which is not displayed for readability.

The full example can be downloaded from the .dashboard.js file. Dashboard customization helpers can be downloaded from the dot-dashboard-helpers.js file.