Add page.on('metric') docs

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/<K6_VERSION>/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.
+
+<TableWithNestedRows>
+
+| 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. |
+
+</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) 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 >}}