Mapbox GL JS Terrain and Tile Fetch Integration - Performance Measurement Boundary

Direct answer

Yes—terrain tile fetch latency can be isolated from base map tile latency after the fact, but only by URL pattern, not by Mapbox GL JS API. Terrain tiles use terrain-rgb URLs; base map tiles use style source URLs. You can filter DevTools Network or PerformanceObserver resource entries by that pattern and compute responseEnd - startTime per tile. What you cannot do is query a terrain-specific load event, cache hit/miss counter, or GPU elevation decode time from JavaScript.

Confirmed behavior versus likely explanation

• Confirmed: Mapbox GL JS v2.x shares one tile pipeline for terrain and base map tiles. No public method separates their timing, exposes terrain cache metrics, or reports when terrain tiles finish loading.
• Confirmed: map.setTerrain() replaces the terrain property and triggers a style reload. There is no documented hot-swap or terrain-completion callback.
• Confirmed: GPU elevation sampling happens during the render phase. No JavaScript hook separates terrain shader work from base layer compositing.
• Likely explanation: The terrain/base map boundary is internal to the loader and renderer. Attributing a render delay to terrain requires correlating terrain resource timing with map.on('render') frames, not waiting for a terrain event.

Measurement steps for this case

1. Set terrain with a Mapbox Terrain-RGB source, for example map.setTerrain({ source: 'mapbox-dem' }).
2. Open DevTools Network, filter by terrain-rgb, reload the map, and record each tile's responseEnd - startTime. Compare against a filter for base map tile URLs.
3. Use PerformanceObserver with entryTypes: ['resource'], log entries whose URL contains terrain-rgb, mark the start when terrain is applied, and stop after the last terrain tile response ends.
4. Verify cache behavior with a normal reload versus a hard reload (Ctrl+Shift+R). In the Network Size column, terrain tiles served from disk or memory cache appear as cache entries rather than transferred bytes.
5. Confirm that terrain switching causes a full reload by listening to map.on('style.load') after setTerrain and measuring the elapsed time.

const terrainEntries = [];
const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.name.includes('terrain-rgb')) {
      terrainEntries.push({
        url: entry.name,
        fetchMs: entry.responseEnd - entry.startTime
      });
    }
  }
});
observer.observe({ entryTypes: ['resource'], buffered: true });

const start = performance.now();
map.setTerrain({ source: 'mapbox-dem' });
map.once('style.load', () => {
  console.log('terrain style reload ms:', performance.now() - start);
  console.log('terrain tiles:', terrainEntries.length);
});

Assumptions and uncertainty

This assumes Mapbox GL JS v2.x and a Mapbox Terrain-RGB source such as mapbox-dem. Behavior can vary across v2.x minor versions, and first-request timing includes DNS, TCP, and TLS setup while later requests reuse connections. GPU elevation decode time remains inseparable from base map compositing in JavaScript. Treat the code snippet as a starting point, not a production instrumentation library.

Missing diagnostic detail: Which Mapbox GL JS minor version are you using? Terrain reload mechanics changed across v2.x releases, and the version determines whether map.setTerrain() triggers a full style reload in your build.