feat: Add a demo how to implement performance metrics using our callbacks (#7077)

CommanderStorm · Copilot · kaigritun · web-flow · commit 9c6ea6cfb97b · 2026-03-29T14:58:02.000+03:00
* document the performance metrics * expose PerformanceMetrics of the map * make the map and performance api work nicely with multiple map instances * write an performance example page * fix ts import * update index * reimplement the PerformanceMonitor without the small memory leak * rename the metrics * fix typo * simplify the code a bit * fix initalisation typing bug * add lastFrameTimeMs * add resetRuntimeMetrics * update docs * inital tests * fix naming * fix import * fix lints * add the reset function to the metrics example * bump bundle size * Apply suggestion from @CommanderStorm * refactor: make function and variable naming in `PerformanceUtils` more sensible (#7096) * rename the PerformanceUtils * make PerformanceUtils.remove adhere to how this is named across the codebase * document validateStyle better * change to different spelling * Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Apply suggestion from @CommanderStorm --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * make the hash tests even more strict where the line between valid and invalid is (#7097) * fix: handle WebGL context loss when style is not loaded (#7094) * fix: handle WebGL context loss when style is not loaded Fix TypeError when WebGL context is lost before the map style is loaded. When a map is created without a style (or the style hasn't finished loading), this.style is null. The _contextLost handler was accessing this.style._layers and calling this.style.destroy() without checking if style exists first. This adds a null check around the style-dependent operations in the context lost handler. Fixes #7022 * refactor: invert if for readability, add changelog entry - Invert if (this.style) to early return for reduced indentation - Add changelog entry for the bug fix --------- Co-authored-by: Kai Gritun <kai@kaigritun.com> * chore(deps-dev): bump devtools-protocol from 0.0.1580600 to 0.0.1581282 (#7102) Bumps [devtools-protocol](https://github.com/ChromeDevTools/devtools-protocol) from 0.0.1580600 to 0.0.1581282. - [Commits](ChromeDevTools/devtools-protocol@v0.0.1580600...v0.0.1581282) --- updated-dependencies: - dependency-name: devtools-protocol dependency-version: 0.0.1581282 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * chore(deps-dev): bump puppeteer from 24.37.1 to 24.37.2 (#7100) Bumps [puppeteer](https://github.com/puppeteer/puppeteer) from 24.37.1 to 24.37.2. - [Release notes](https://github.com/puppeteer/puppeteer/releases) - [Changelog](https://github.com/puppeteer/puppeteer/blob/main/CHANGELOG.md) - [Commits](puppeteer/puppeteer@puppeteer-v24.37.1...puppeteer-v24.37.2) --- updated-dependencies: - dependency-name: puppeteer dependency-version: 24.37.2 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * chore(deps-dev): bump typedoc-plugin-markdown from 4.9.0 to 4.10.0 (#7101) Bumps [typedoc-plugin-markdown](https://github.com/typedoc2md/typedoc-plugin-markdown/tree/HEAD/packages/typedoc-plugin-markdown) from 4.9.0 to 4.10.0. - [Release notes](https://github.com/typedoc2md/typedoc-plugin-markdown/releases) - [Changelog](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/CHANGELOG.md) - [Commits](https://github.com/typedoc2md/typedoc-plugin-markdown/commits/typedoc-plugin-markdown@4.10.0/packages/typedoc-plugin-markdown) --- updated-dependencies: - dependency-name: typedoc-plugin-markdown dependency-version: 4.10.0 dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * reimplement using the observer pattern * Apply suggestion from @CommanderStorm * Apply suggestion from @CommanderStorm * Apply suggestion from @CommanderStorm * Apply suggestion from @CommanderStorm * remove the strip plugin * fix imports * fix naming * make the design more consistently named * integrate witht the documentation subsystem * Fix which items are exported for the docs * make the example more pretty * Apply suggestion from @CommanderStorm * fix linting errors * fix tests * add a testcase * simplify the LivecyclePerformanceObserver * make the naming clearer * add a marking observer * fix import * increase magic sourcemap number ???? * add more testcases * expose the marking observer * Update src/util/performance_observer/observer.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update test/examples/display-performance-metrics.html Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update test/examples/display-performance-metrics.html Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update test/examples/display-performance-metrics.html * add a changelog entry * implement in terms of the higher overhead event system * Apply suggestions from code review Co-authored-by: Frank Elsinga <frank@elsinga.de> * simplify the metrics example * Apply suggestion from @CommanderStorm * Apply suggestion from @CommanderStorm * simplify example * Apply suggestion from @CommanderStorm * Apply suggestions from code review Co-authored-by: Frank Elsinga <frank@elsinga.de> * Update typedoc.json Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * remove the now unnessary @rollup/plugin-strip --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Kai Gritun <kaigritun@gmail.com> Co-authored-by: Kai Gritun <kai@kaigritun.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,7 @@
 ## main
 ### ✨ Features and improvements
 - _...Add new stuff here..._
+- Add example showing how to measure map performance using built-in events (`load`, `idle`, `render`) ([#7077](https://github.com/maplibre/maplibre-gl-js/pull/7077)) (by [@CommanderStorm](https://github.com/CommanderStorm))
 
 ### 🐞 Bug fixes
 - Make `fitBounds` and `fitScreenCoordinates` respect the `zoomSnap` map option by snapping the zoom level down to keep bounds fully visible ([#7332](https://github.com/maplibre/maplibre-gl-js/issues/7332) (by [@CommanderStorm](https://github.com/CommanderStorm))
diff --git a/build/rollup_plugins.ts b/build/rollup_plugins.ts
@@ -4,7 +4,6 @@ import resolve from '@rollup/plugin-node-resolve';
 import replace from '@rollup/plugin-replace';
 import commonjs from '@rollup/plugin-commonjs';
 import terser from '@rollup/plugin-terser';
-import strip from '@rollup/plugin-strip';
 import {type Plugin} from 'rollup';
 import json from '@rollup/plugin-json';
 import {visualizer} from 'rollup-plugin-visualizer';
@@ -31,10 +30,6 @@ export const plugins = (production: boolean): Plugin[] => [
             '_token_stack:': ''
         }
     }),
-    production && strip({
-        sourceMap: true,
-        functions: ['PerformanceUtils.*']
-    }),
     production && terser({
         compress: {
             pure_getters: true,
diff --git a/docs/assets/examples/display-performance-metrics.png b/docs/assets/examples/display-performance-metrics.png
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -44,7 +44,6 @@
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-replace": "^6.0.3",
-    "@rollup/plugin-strip": "^3.0.4",
     "@rollup/plugin-terser": "^1.0.0",
     "@rollup/plugin-typescript": "^12.1.4",
     "@stylistic/eslint-plugin": "^5.10.0",
diff --git a/src/source/geojson_worker_source.ts b/src/source/geojson_worker_source.ts
@@ -1,5 +1,5 @@
 import {getJSON} from '../util/ajax';
-import {RequestPerformance} from '../util/performance';
+import {RequestPerformance} from '../util/request_performance';
 import {GeoJSONWrapper} from '@maplibre/vt-pbf';
 import {EXTENT} from '../data/extent';
 import {GeoJSONVT, type GeoJSONVTOptions} from '@maplibre/geojson-vt';
diff --git a/src/source/vector_tile_worker_source.ts b/src/source/vector_tile_worker_source.ts
@@ -5,7 +5,7 @@ import {WorkerTile} from './worker_tile';
 import {WorkerTileState, type ParsingState} from './worker_tile_state';
 import {BoundedLRUCache} from '../tile/tile_cache';
 import {extend} from '../util/util';
-import {RequestPerformance} from '../util/performance';
+import {RequestPerformance} from '../util/request_performance';
 import {VectorTileOverzoomed, sliceVectorTileLayer, toVirtualVectorTile} from './vector_tile_overzoomed';
 import {MLTVectorTile} from './vector_tile_mlt';
 import type {
diff --git a/src/ui/map.ts b/src/ui/map.ts
@@ -22,7 +22,6 @@ import {Event, ErrorEvent, type Listener} from '../util/evented';
 import {type MapEventType, type MapLayerEventType, MapMouseEvent, type MapSourceDataEvent, type MapStyleDataEvent} from './events';
 import {TaskQueue} from '../util/task_queue';
 import {throttle} from '../util/throttle';
-import {PerformanceMarkers, PerformanceUtils} from '../util/performance';
 import {type Source} from '../source/source';
 import {type StyleLayer} from '../style/style_layer';
 import {Terrain} from '../render/terrain';
@@ -687,8 +686,6 @@ export class Map extends Camera {
     transformConstrain: TransformConstrainFunction | null;
 
     constructor(options: MapOptions) {
-        PerformanceUtils.mark(PerformanceMarkers.create);
-
         const resolvedOptions = {...defaultOptions, ...options, canvasContextAttributes: {
             ...defaultOptions.canvasContextAttributes,
             ...options.canvasContextAttributes
@@ -3678,7 +3675,6 @@ export class Map extends Camera {
 
         if (this.loaded() && !this._loaded) {
             this._loaded = true;
-            PerformanceUtils.mark(PerformanceMarkers.load);
             this.fire(new Event('load'));
         }
 
@@ -3707,7 +3703,6 @@ export class Map extends Camera {
 
         if (this._loaded && !this._fullyLoaded && !somethingDirty) {
             this._fullyLoaded = true;
-            PerformanceUtils.mark(PerformanceMarkers.fullLoad);
         }
 
         return this;
@@ -3772,8 +3767,6 @@ export class Map extends Camera {
         this._container.removeEventListener('scroll', this._onMapScroll, false);
         this._container.classList.remove('maplibregl-map');
 
-        PerformanceUtils.remove();
-
         this._removed = true;
         this.fire(new Event('remove'));
     }
@@ -3795,7 +3788,6 @@ export class Map extends Camera {
             browser.frame(
                 this._frameRequest,
                 (paintStartTimeStamp) => {
-                    PerformanceUtils.recordStartOfFrameAt(paintStartTimeStamp);
                     this._frameRequest = null;
                     try {
                         this._render(paintStartTimeStamp);
diff --git a/src/util/performance.ts b/src/util/performance.ts
diff --git a/src/util/request_performance.test.ts b/src/util/request_performance.test.ts
@@ -1,5 +1,5 @@
 import {describe, test, expect, beforeEach, afterEach, vi} from 'vitest';
-import {RequestPerformance} from './performance';
+import {RequestPerformance} from './request_performance';
 
 describe('RequestPerformance', () => {
     const url = 'http://example.com/test.json';
diff --git a/src/util/request_performance.ts b/src/util/request_performance.ts
@@ -0,0 +1,35 @@
+/**
+ * @internal
+ * Safe wrapper for the performance resource timing API in web workers with graceful degradation
+ */
+export class RequestPerformance {
+    private start: string;
+    private end: string;
+    private measure: string;
+
+    constructor (url: string) {
+        this.start = `${url}#start`;
+        this.end = `${url}#end`;
+        this.measure = url;
+
+        performance.mark(this.start);
+    }
+
+    finish() {
+        performance.mark(this.end);
+        let resourceTimingData = performance.getEntriesByName(this.measure);
+
+        // fallback if web worker implementation of perf.getEntriesByName returns empty
+        if (resourceTimingData.length === 0) {
+            performance.measure(this.measure, this.start, this.end);
+            resourceTimingData = performance.getEntriesByName(this.measure);
+
+            // cleanup
+            performance.clearMarks(this.start);
+            performance.clearMarks(this.end);
+            performance.clearMeasures(this.measure);
+        }
+
+        return resourceTimingData;
+    }
+}
diff --git a/test/examples/display-performance-metrics.html b/test/examples/display-performance-metrics.html
@@ -0,0 +1,67 @@
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8" />
+<title>Display Map Performance Metrics</title>
+<meta property="og:description" content="Measure map performance using built-in events." />
+<meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no" />
+<link rel='stylesheet' href='../../dist/maplibre-gl.css' />
+<script src='../../dist/maplibre-gl-dev.js'></script>
+<style>
+    body { margin: 0; padding: 0; }
+    #map { position: absolute; top: 0; bottom: 0; width: 100%; }
+    #metrics {
+        position: absolute;
+        top: 10px;
+        left: 10px;
+        background: white;
+        padding: 10px 14px;
+        border-radius: .4rem;
+        font-family: sans-serif;
+        font-size: 14px;
+        z-index: 100;
+    }
+    #metrics div { margin: 4px 0; }
+    #metrics span { font-weight: bold; }
+</style>
+</head>
+<body>
+<div id="map"></div>
+<div id="metrics">
+    <div>Load: <span id="load">—</span></div>
+    <div>Idle: <span id="idle">—</span></div>
+    <div>FPS: <span id="fps">—</span></div>
+</div>
+
+<script>
+    const createdAt = performance.now();
+
+    const map = new maplibregl.Map({
+        container: "map",
+        style: "https://demotiles.maplibre.org/style.json",
+        center: [0, 0],
+        zoom: 1,
+    });
+
+    map.on("load", () => {
+        document.getElementById("load").textContent = (performance.now() - createdAt).toFixed(0) + " ms";
+    });
+
+    map.once("idle", () => {
+        document.getElementById("idle").textContent = (performance.now() - createdAt).toFixed(0) + " ms";
+    });
+
+    let frameCount = 0;
+    let fpsStart = performance.now();
+    map.on("render", () => {
+        frameCount++;
+        const elapsed = performance.now() - fpsStart;
+        if (elapsed >= 1000) {
+            document.getElementById("fps").textContent = Math.round(frameCount * 1000 / elapsed);
+            frameCount = 0;
+            fpsStart = performance.now();
+        }
+    });
+</script>
+</body>
+</html>
diff --git a/typedoc.json b/typedoc.json
