Add initial page.on('metric') release note change

release notes/v0.55.0.md

@@ -55,6 +55,71 @@ export default async function () {
 
 </details>
 
+### `page.on('metric)` to group urls
+
+Modern websites are complex, and perform a high number of requests to behave as the creators intended. Requests no longer just serve content that will be used for display to the end user, but also to retrieve valuable insights, analytics, serve adverts, and requests can be dynamically altered for cache busting purposes. Such requests are usually dynamically generated and may contain IDs that change often. This can be an issue when it comes to correlating and analyzing your k6 test results.
+
+When it comes to load testing a website using the k6 browser module, such dynamic requests can result is a high number of similar looking requests which are hard to correlate and find any valuable insights in. This can also lead to tests erroring with a too-many-metrics error due to a high cardinality with metrics that are tagged with similar but dynamically changing URLs.
+
+This is also an issue with synthetic tests, where you may not face the too-many-metrics message, but you will end up with a high number of uncorrelated metric data that can't be tracked over time.
+
+To overcome this issue in the browser module, we have implemented `page.on('metric')` which allows you to define url patterns using regex to match against. When a match is found the `url` and `name` tags for the metric will be replaced by the new `name`.
+
+#### Example usage
+
+```js
+
+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 metric object. It is
+    // the method that will match on the url tag with the defined regex pattern.
+    // It can be called multiple times from within the callback function.
+    metric.tag({
+      // This is the new name that will be used for any metric which matches on
+      // the existing url tag.
+      name: 'test',
+      // You can provide multiple matches here. Any metrics that match will all
+      // use the new name defined above.
+      matches: [
+        // 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.
+        {url: /^https:\/\/test\.k6\.io\/\?q=[0-9a-z]+$/, 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();
+  }
+}
+
+```
+
 ### `ControlOrMeta` support in the keyboard [browser#1457](https://github.com/grafana/xk6-browser/pull/1457)
 
 This will allow us to write the test for all platforms that either work with `Control` or `Meta` when performing keyboard actions. For example `control+click` on windows, and `meta+click` on mac to open a link in a new window.