Skip to content

Customization

Jump to bottom
Iván Szkiba edited this page Jul 1, 2024 · 9 revisions

This page is about configuration customization.

Important

As of v0.7.5, the configuration cannot be customized from JavaScript code.

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.

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.

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
}

The constructor of the TabBuilder class expects the config object as a parameter. After instantiation, we get a callable function object. This function can have the following optional parameters (by type):

  • String is the title of the tab
  • String summary of the tab
  • Object properties of the tab
  • function({tab, section)} to define the contents of the tab. Including:
    • tab is the tab object currently being defined
    • section is a function used to define sections
section

The section is defined using a function, which can have the following optional parameters (by type):

  • String is the title of the section. If it is missing, the section will not be collapsible.
  • String summary of the section
  • Object properties of the section
  • function({section, panel)} to define the contents of the section. Including:
    • section is the section object currently being defined
    • panel is a function used to define panels
panel

The panel is defined using a function, which can have the following optional parameters (according to type):

  • String is the title of the panel
  • String the panel type (chart or stat, default: chart)
  • Object properties of the panel
  • function({panel, serie)} to define the contents of the panel. Including:
    • panel is the panel object currently being defined
    • serie is a function used to define data series
serie

The data serie is defined using a function, which can have the following optional parameters (according to type):

  • String is the query required to select the data serie
  • String is the legend of the data serie
  • Object properties of the data serie

A JMESPath format query is used to select the data series. The query runs on an object that has array type properties with the same name as the metrics. Each array element is an object that has additional properties in addition to the time series data. Based on these additional properties, the data series can be selected with a query. For example, bool properties corresponding to the aggregate type: counter,gauge,rate,avg,min,max,p90,p95,p99, etc.

Clone this wiki locally