Add page.on('metric') docs

docs/sources/k6/next/javascript-api/k6-browser/metricmessage.md

@@ -0,0 +1,58 @@
+---
+title: 'MetricMessage'
+slug: 'metricmessage'
+description: 'Browser module: MetricMessage Class'
+weight: 03
+---
+
+# MetricMessage
+
+`MetricMessage` objects are dispatched by page via registering a handler with [page.on('metric')](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/on). For each metric that it measured and emitted for the page, k6 browser delivers it to the registered handlers.
+
+## tag
+
+The Metric Message exposes a single method, `tag`. It will match 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 will help group metrics with disparate url and name tags, which are in fact referencing the same resource, so that a correlation can be found over time and preventing high cardinality issues in the backend database that is storing the metrics.
+
+<TableWithNestedRows>
+
+| Parameter               | Type     | Description                                                                                                                                                                                                                                                                                 |
+| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| tagMatch                | object   | It is required.                                                                                                                                                                                                                                                                             |
+| tagMatch.name           | string   | It is a required field and it must not be an empty string. It will replace the current metric's url and name tag values when a match is found.                                                                                                                                              |
+| tagMatch.matches        | object[] | It is a required field. It is an array of objects containing the regular expression and optional method to match against the current metric's url and name tags. It will iterate over all the objects in `matches` until a match is found, or to the end of the array if no match is found. |
+| tagMatch.matches.url    | RegExp   | It is a required field. It is used to match against the current metric url and name tags.                                                                                                                                                                                                   |
+| tagMatch.matches.method | string   | It is optional. When it is not set, a match will occur on all method types. When it is set, it will match on the one method that is set. Valid values are `'GET'`, `'POST'`, `'PUT'`, `'DELETE'`, `'PATCH'`, `'OPTIONS'`, `'HEAD'`, `'TRACE'` and `'CONNECT'`                               |
+
+</TableWithNestedRows>
+
+### Example Usage
+
+{{< code >}}
+
+<!-- eslint-skip-->
+
+```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 >}}

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/<K6_VERSION>/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/<K6_VERSION>/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/<K6_VERSION>/javascript-api/k6-browser/metricmessage) class.                                |
 
-### Example
+### Console event Example
 
 {{< code >}}
 
@@ -72,3 +67,62 @@ 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();
+
+  // Here we call page.on('metric). It's possible to call page.on('metric') more
+  // than once, and the callback function will be executed in the order page.on
+  // was called.
+  page.on('metric', (metric) => {
+    // At the moment metric.tag is the only method on the metricMessage object.
+    // 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',
+        },
+      ],
+    });
+  });
+
+  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 >}}