diff --git a/docs/sources/k6/next/javascript-api/k6-browser/metricmessage.md b/docs/sources/k6/next/javascript-api/k6-browser/metricmessage.md new file mode 100644 index 0000000000..71d5416de7 --- /dev/null +++ b/docs/sources/k6/next/javascript-api/k6-browser/metricmessage.md @@ -0,0 +1,59 @@ +--- +title: 'MetricMessage' +description: 'Browser module: MetricMessage Object' +weight: 03 +--- + +# MetricMessage + +A `MetricMessage` object allows tagging of metrics that are measured and emitted for the page. + +`MetricMessage` objects are dispatched by the page when a handler is registered with [page.on('metric')](https://grafana.com/docs/k6//javascript-api/k6-browser/page/on). For each metric that is measured and emitted for the page, the k6 browser module delivers a `MetricMessage` object to the registered handlers, allowing them to pattern match and tag metrics. + +## tag + +The `tag` method matches the given `matches` with the current metric's url and name tags. When a match is found, it will use `name` to replace the existing URL and name tag values. + +Doing this helps group metrics with different URL and name tags that, in fact, reference the same resource, allowing for correlation over time and reducing the cardinality of the metrics. + + + +| Parameter | Type | Description | +| ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| tagMatch | object | The tagMatch object and its properties that are used for matching metrics. Required. | +| tagMatch.name | string | The name value that replaces the current metric's URL and name tag values, if a match is found. Required, and must not be an empty string. | +| tagMatch.matches | object[] | An array of objects containing the matchers which will be used to match against the current metric's URL and name tags. Required. | +| tagMatch.matches.url | RegExp | The regular expression used to find matches in the current metric's URL and name tags. Required. | +| tagMatch.matches.method | string? | Used to match the metric's method tag. Valid values are `'GET'`, `'POST'`, `'PUT'`, `'DELETE'`, `'PATCH'`, `'OPTIONS'`, `'HEAD'`, `'TRACE'` and `'CONNECT'`. It's optional, and when it's not set it will group all metrics regardless of the method tag. | + + + +### Example Usage + +{{< code >}} + + + +```javascript +// First we need to register a handler with `page.on('metric')`. +page.on('metric', (metric) => { + // It will find a match between the current metric url and name tags against + // the supplied regular expression in `url`. + metric.tag({ + // This is the new name value that will replace the existing value in the + // url and name tags when a match is found. + name: 'test', + // You can provide multiple matches here. + matches: [ + { + url: /^https:\/\/test\.k6\.io\/\?q=[0-9a-z]+$/, + // When a method is defined it will also need to match on that too. If a + // method is not provided it will match on all method types. + method: 'GET', + }, + ], + }); +}); +``` + +{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/k6-browser/page/on.md b/docs/sources/k6/next/javascript-api/k6-browser/page/on.md index 4dc34115f4..715b099f6f 100644 --- a/docs/sources/k6/next/javascript-api/k6-browser/page/on.md +++ b/docs/sources/k6/next/javascript-api/k6-browser/page/on.md @@ -7,24 +7,19 @@ description: 'Browser module: page.on method' Registers a handler to be called whenever the specified event occurs. -| Parameter | Type | Default | Description | -| --------- | -------- | ------- | ----------------------------------------------------------------------------------- | -| event | string | `''` | Event to attach the handler to. Currently, only the `'console'` event is supported. | -| handler | function | `null` | A function to be called every time the specified event is emitted. | - -{{< admonition type="caution" >}} - -When using the `page.on` method, the page has to be explicitly [closed](https://grafana.com/docs/k6//javascript-api/k6-browser/page/close/) for the iteration to be able to finish. - -{{< /admonition >}} +| Parameter | Type | Default | Description | +| --------- | -------- | ------- | ------------------------------------------------------------------------------------------- | +| event | string | `''` | Event to attach the handler to. Currently, `'console'` and `'metric'` events are supported. | +| handler | function | `null` | A function to be called every time the specified event is emitted. | ### Events -| Event | Description | -| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Event | Description | +| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `console` | Emitted every time the console API methods are called from within the page JavaScript context. The arguments passed into the handler are defined by the [`ConsoleMessage`](https://grafana.com/docs/k6//javascript-api/k6-browser/consolemessage) class. | +| `metric` | Emitted every time a metric is measured and emitted for the page. The arguments passed into the handler are defined by the [`MetricMessage`](https://grafana.com/docs/k6//javascript-api/k6-browser/metricmessage) object. | -### Example +### Console event Example {{< code >}} @@ -72,3 +67,63 @@ export default async function () { ``` {{< /code >}} + +### Metric event Example + +{{< code >}} + +```javascript +import { browser } from 'k6/browser'; + +export const options = { + scenarios: { + ui: { + executor: 'shared-iterations', + options: { + browser: { + type: 'chromium', + }, + }, + }, + }, +}; + +export default async function () { + const page = await browser.newPage(); + + // We first register a handler using page.on('metric'). Calling page.on('metric') + // multiple times is allowed. The registered handlers will be executed in the + // order page.on was called. + page.on('metric', (metric) => { + // Using metric.tag finds a match between the current metric url and name + // tags against the supplied regular expression in `url`. + // + // At the moment metric.tag is the only method on the metricMessage object. + metric.tag({ + // This is the new name value that will replace the existing value in the + // url and name tags when a match is found. + name: 'test', + // You can provide multiple matches here. + matches: [ + { + url: /^https:\/\/test\.k6\.io\/\?q=[0-9a-z]+$/, + // When a method is defined it will also need to match on that too. If a + // method is not provided it will match on all method types. + method: 'GET', + }, + ], + }); + }); + + try { + // This is only for illustrative purposes, the q query param doesn't affect + // the website. + await page.goto('https://test.k6.io/?q=abc123'); + await page.goto('https://test.k6.io/?q=def456'); + } finally { + await page.close(); + } +} +``` + +{{< /code >}}