tileserver-gl 5.6.0 → 5.7.0-pre.0

package/src/main.js

@@ -113,6 +113,10 @@ program
     '--ignore-missing-files',
     'Continue startup even if configured mbtiles/pmtiles files are missing',
   )
+  .option(
+    '--metrics',
+    'Enable Prometheus metrics endpoint (env: TILESERVER_GL_METRICS)',
+  )
   .version(packageJson.version, '-v, --version');
 program.parse(process.argv);
 const opts = program.opts();
@@ -166,6 +170,11 @@ const startServer = (configPath, config) => {
     publicUrl,
     allowedHosts,
     ignoreMissingFiles: opts.ignoreMissingFiles,
+    metrics: opts.metrics || process.env.TILESERVER_GL_METRICS === 'true',
+    metricsPort: (() => {
+      const port = parseInt(process.env.METRICS_PORT, 10);
+      return !isNaN(port) && port > 0 ? port : 9090;
+    })(),
   });
 };
 

package/src/mbtiles_wrapper.js

@@ -8,6 +8,7 @@ class MBTilesWrapper {
   constructor(mbtiles) {
     this._mbtiles = mbtiles;
     this._getInfoP = util.promisify(mbtiles.getInfo.bind(mbtiles));
+    this._closeP = util.promisify(mbtiles.close.bind(mbtiles));
   }
 
   /**
@@ -25,6 +26,14 @@ class MBTilesWrapper {
   getInfo() {
     return this._getInfoP();
   }
+
+  /**
+   * Closes the underlying MBTiles database handle.
+   * @returns {Promise<void>} A promise that resolves when the database is closed.
+   */
+  close() {
+    return this._closeP();
+  }
 }
 
 /**

package/src/metrics.js

@@ -0,0 +1,70 @@
+// src/metrics.js
+import {
+  Registry,
+  Counter,
+  Histogram,
+  Gauge,
+  collectDefaultMetrics,
+} from 'prom-client';
+
+export const registry = new Registry();
+
+collectDefaultMetrics({ register: registry });
+
+export const httpRequestsTotal = new Counter({
+  name: 'tileserver_http_requests_total',
+  help: 'Total number of HTTP requests',
+  labelNames: ['method', 'route', 'status_code'],
+  registers: [registry],
+});
+
+export const httpRequestDuration = new Histogram({
+  name: 'tileserver_http_request_duration_seconds',
+  help: 'HTTP request duration in seconds',
+  labelNames: ['method', 'route', 'status_code'],
+  buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
+  registers: [registry],
+});
+
+export const tilesServedTotal = new Counter({
+  name: 'tileserver_tiles_served_total',
+  help: 'Total number of tiles served',
+  labelNames: ['type', 'name'],
+  registers: [registry],
+});
+
+export const tileRenderDuration = new Histogram({
+  name: 'tileserver_tile_render_duration_seconds',
+  help: 'Tile pipeline duration in seconds (includes pool wait + render + encode)',
+  labelNames: ['name', 'zoom'],
+  buckets: [0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
+  registers: [registry],
+});
+
+export const tileErrorsTotal = new Counter({
+  name: 'tileserver_tile_errors_total',
+  help: 'Total number of tile errors',
+  labelNames: ['type', 'name'],
+  registers: [registry],
+});
+
+export const renderPoolSize = new Gauge({
+  name: 'tileserver_render_pool_size',
+  help: 'Total objects in render pool',
+  labelNames: ['name'],
+  registers: [registry],
+});
+
+export const renderPoolActive = new Gauge({
+  name: 'tileserver_render_pool_active',
+  help: 'Active (borrowed) objects in render pool',
+  labelNames: ['name'],
+  registers: [registry],
+});
+
+export const renderPoolWaiting = new Gauge({
+  name: 'tileserver_render_pool_waiting',
+  help: 'Clients waiting for a render pool object',
+  labelNames: ['name'],
+  registers: [registry],
+});

package/src/pmtiles_adapter.js

@@ -232,18 +232,22 @@ class S3Source {
       }
 
       if (error.name === 'NoSuchKey') {
-        throw new Error(`PMTiles file not found: ${this.bucket}/${this.key}`);
+        throw new Error(`PMTiles file not found: ${this.bucket}/${this.key}`, {
+          cause: error,
+        });
       }
 
       if (error.name === 'AccessDenied') {
         throw new Error(
           `Access denied: ${this.bucket}/${this.key}. Check credentials and bucket permissions.`,
+          { cause: error },
         );
       }
 
       if (error.name === 'NoSuchBucket') {
         throw new Error(
           `Bucket not found: ${this.bucket}. Check bucket name and endpoint.`,
+          { cause: error },
         );
       }
 
@@ -288,6 +292,23 @@ class PMTilesFileSource {
     );
     return { data: ab };
   }
+
+  /**
+   * Closes the underlying file descriptor for local PMTiles sources.
+   * @returns {void}
+   */
+  close() {
+    if (typeof this.fd === 'number') {
+      const fd = this.fd;
+      try {
+        fs.closeSync(fd);
+      } catch (err) {
+        console.warn(`Failed to close PMTiles file descriptor ${fd}:`, err);
+      } finally {
+        this.fd = null;
+      }
+    }
+  }
 }
 
 /**
@@ -311,6 +332,22 @@ async function readFileBytes(fd, buffer, offset) {
 // Cache for PMTiles objects to avoid creating multiple instances for the same URL
 const pmtilesCache = new Map();
 
+/**
+ * Closes a PMTiles instance if it owns a closeable local file source.
+ * @param {PMTiles} pmtiles - The PMTiles instance to close.
+ * @returns {void}
+ */
+function closePMTiles(pmtiles) {
+  if (!pmtiles) {
+    return;
+  }
+
+  const source = pmtiles.source;
+  if (source && typeof source.close === 'function') {
+    source.close();
+  }
+}
+
 /**
  * Opens a PMTiles file from local filesystem, HTTP URL, or S3 URL.
  * Uses caching to avoid creating multiple PMTiles instances for the same file.
@@ -347,7 +384,7 @@ export function openPMtiles(
     return pmtilesCache.get(cacheKey);
   }
 
-  let pmtiles = undefined;
+  let pmtiles;
 
   if (isS3Url(filePath)) {
     if (verbose >= 2) {
@@ -384,6 +421,17 @@ export function openPMtiles(
   return pmtiles;
 }
 
+/**
+ * Clears the PMTiles cache and closes any local file descriptors owned by cached sources.
+ * @returns {void}
+ */
+export function clearPMtilesCache() {
+  for (const pmtiles of pmtilesCache.values()) {
+    closePMTiles(pmtiles);
+  }
+  pmtilesCache.clear();
+}
+
 /**
  * Retrieves metadata and header information from a PMTiles archive with retry logic for rate limiting.
  * @param {PMTiles} pmtiles - The PMTiles instance.
@@ -462,7 +510,7 @@ export async function getPMtilesInfo(pmtiles, inputFile, maxRetries = 3) {
       // If not a 429 or last retry, throw immediately
       if (!error.message?.includes('429') || attempt === maxRetries - 1) {
         const errorMessage = `${error.message} for file: ${inputFile}`;
-        throw new Error(errorMessage);
+        throw new Error(errorMessage, { cause: error });
       }
     }
   }

package/src/serve_data.js

@@ -5,7 +5,7 @@ import path from 'path';
 
 import clone from 'clone';
 import express from 'express';
-import Pbf from 'pbf';
+import { PbfReader } from 'pbf';
 import { VectorTile } from '@mapbox/vector-tile';
 import { SphericalMercator } from '@mapbox/sphericalmercator';
 
@@ -21,6 +21,8 @@ import { gunzipP, gzipP } from './promises.js';
 import { openMbTilesWrapper } from './mbtiles_wrapper.js';
 
 import fs from 'node:fs';
+
+let metricsModule = null;
 import { fileURLToPath } from 'url';
 
 const packageJson = JSON.parse(
@@ -45,6 +47,16 @@ export const serve_data = {
    */
   init: function (options, repo, programOpts) {
     const { verbose, allowedHosts } = programOpts;
+    // Cache metrics module if enabled. Safe because tests verify before production.
+    if (programOpts.metrics) {
+      import('./metrics.js')
+        .then((m) => {
+          metricsModule = m;
+        })
+        .catch((err) => {
+          console.error('Failed to import metrics module:', err);
+        });
+    }
     const app = express().disable('x-powered-by');
     app.use(express.json());
 
@@ -142,7 +154,7 @@ export const serve_data = {
         headers['Content-Type'] = 'application/x-protobuf';
       } else if (format === 'geojson') {
         headers['Content-Type'] = 'application/json';
-        const tile = new VectorTile(new Pbf(data));
+        const tile = new VectorTile(new PbfReader(data));
         const geojson = {
           type: 'FeatureCollection',
           features: [],
@@ -167,6 +179,12 @@ export const serve_data = {
 
       data = await gzipP(data);
 
+      if (metricsModule) {
+        metricsModule.tilesServedTotal.inc({
+          type: 'vector',
+          name: req.params.id,
+        });
+      }
       return res.status(200).send(data);
     });
 
@@ -548,14 +566,14 @@ export const serve_data = {
         if (!inputFileStats.isFile() || inputFileStats.size === 0) {
           throw Error(`Not valid input file: "${inputFile}"`);
         }
-      } catch (err) {
+      } catch (_err) {
         if (ignoreMissingFiles) {
           console.log(
             `WARN: Data source '${id}' file not found: "${inputFile}" - skipping`,
           );
           return;
         }
-        throw Error(`Not valid input file: "${inputFile}"`);
+        throw Error(`Not valid input file: "${inputFile}"`, { cause: _err });
       }
     }
 
@@ -624,4 +642,29 @@ export const serve_data = {
       sparse,
     };
   },
+  /**
+   * Removes all items from the repository and closes owned local data sources.
+   * @param {object} repo Repository object.
+   * @returns {Promise<void>}
+   */
+  clear: async function (repo) {
+    await Promise.all(
+      Object.keys(repo).map(async (id) => {
+        // eslint-disable-next-line security/detect-object-injection -- id is from Object.keys() iteration
+        const item = repo[id];
+        try {
+          if (item && item.sourceType === 'mbtiles' && item.source) {
+            await new Promise((resolve, reject) => {
+              item.source.close((err) => (err ? reject(err) : resolve()));
+            });
+          }
+        } catch (err) {
+          console.warn(`Failed to close data source "${id}":`, err);
+        } finally {
+          // eslint-disable-next-line security/detect-object-injection -- id is from Object.keys() iteration
+          delete repo[id];
+        }
+      }),
+    );
+  },
 };

package/src/serve_font.js

@@ -4,6 +4,8 @@ import express from 'express';
 
 import { getFontsPbf, listFonts } from './utils.js';
 
+let metricsModule = null;
+
 /**
  * Initializes and returns an Express app that serves font files.
  * @param {object} options - Configuration options for the server.
@@ -13,6 +15,11 @@ import { getFontsPbf, listFonts } from './utils.js';
  */
 export async function serve_font(options, allowedFonts, programOpts) {
   const { verbose } = programOpts;
+  // Cache metrics module if enabled. Safe because tests verify before production.
+  if (programOpts.metrics) {
+    const m = await import('./metrics.js');
+    metricsModule = m;
+  }
   const app = express().disable('x-powered-by');
 
   const lastModified = new Date().toUTCString();
@@ -64,6 +71,9 @@ export async function serve_font(options, allowedFonts, programOpts) {
       );
       res.header('Content-type', 'application/x-protobuf');
       res.header('Last-Modified', lastModified);
+      if (metricsModule) {
+        metricsModule.tilesServedTotal.inc({ type: 'font', name: sFontStack });
+      }
       return res.send(concatenated);
     } catch (err) {
       console.error(

package/src/serve_rendered.js

@@ -539,6 +539,7 @@ function calcZForBBox(bbox, w, h, query) {
  * @param {object} res Express response object.
  * @param {Buffer|null} overlay Optional overlay image.
  * @param {string} mode Rendering mode ('tile' or 'static').
+ * @param {string|null} id Style or dataset ID for metrics labeling.
  * @returns {Promise<void>}
  */
 async function respondImage(
@@ -556,6 +557,7 @@ async function respondImage(
   res,
   overlay = null,
   mode = 'tile',
+  id = null,
 ) {
   if (
     Math.abs(lon) > 180 ||
@@ -599,10 +601,14 @@ async function respondImage(
   }
 
   pool.acquire(async (err, renderer) => {
+    const renderStart = process.hrtime.bigint();
     // Check if pool.acquire failed or returned null/invalid renderer
     if (err) {
       console.error('Failed to acquire renderer from pool:', err);
       if (!res.headersSent) {
+        if (metricsModule) {
+          metricsModule.tileErrorsTotal.inc({ type: 'rendered', name: id });
+        }
         return res.status(503).send('Renderer pool error');
       }
       return;
@@ -613,6 +619,9 @@ async function respondImage(
         'Renderer is null - likely crashed or failed to initialize',
       );
       if (!res.headersSent) {
+        if (metricsModule) {
+          metricsModule.tileErrorsTotal.inc({ type: 'rendered', name: id });
+        }
         return res.status(503).send('Renderer unavailable');
       }
       return;
@@ -627,6 +636,9 @@ async function respondImage(
         console.error('Error removing bad renderer:', e);
       }
       if (!res.headersSent) {
+        if (metricsModule) {
+          metricsModule.tileErrorsTotal.inc({ type: 'rendered', name: id });
+        }
         return res.status(503).send('Renderer invalid');
       }
       return;
@@ -693,6 +705,9 @@ async function respondImage(
             console.error('Error removing failed renderer:', e);
           }
           if (!res.headersSent) {
+            if (metricsModule) {
+              metricsModule.tileErrorsTotal.inc({ type: 'rendered', name: id });
+            }
             return res
               .status(500)
               .header('Content-Type', 'text/plain')
@@ -791,12 +806,34 @@ async function respondImage(
           if (err || !buffer) {
             console.error('Sharp error:', err);
             if (!res.headersSent) {
+              if (metricsModule) {
+                metricsModule.tileErrorsTotal.inc({
+                  type: 'rendered',
+                  name: id,
+                });
+              }
               return res.status(500).send('Image processing failed');
             }
             return;
           }
 
           if (!res.headersSent) {
+            if (metricsModule) {
+              const renderDurationSec =
+                Number(process.hrtime.bigint() - renderStart) / 1e9;
+              metricsModule.tilesServedTotal.inc({
+                type: 'rendered',
+                name: id,
+              });
+              const zoomLabel =
+                process.env.TILESERVER_GL_METRICS_ZOOM === 'true'
+                  ? String(z)
+                  : 'all';
+              metricsModule.tileRenderDuration.observe(
+                { name: id, zoom: zoomLabel },
+                renderDurationSec,
+              );
+            }
             res.set({
               'Last-Modified': item.lastModified,
               'Content-Type': `image/${format}`,
@@ -814,6 +851,9 @@ async function respondImage(
         console.error('Error removing renderer after error:', e);
       }
       if (!res.headersSent) {
+        if (metricsModule) {
+          metricsModule.tileErrorsTotal.inc({ type: 'rendered', name: id });
+        }
         return res.status(500).send('Render failed');
       }
     }
@@ -905,7 +945,7 @@ async function handleTileRequest(
 
   // prettier-ignore
   return await respondImage(
-    options, item, z, tileCenter[0], tileCenter[1], 0, 0, parsedTileSize, parsedTileSize, scale, format, res,
+    options, item, z, tileCenter[0], tileCenter[1], 0, 0, parsedTileSize, parsedTileSize, scale, format, res, null, 'tile', id,
   );
 }
 
@@ -944,8 +984,8 @@ async function handleStaticRequest(
   // eslint-disable-next-line security/detect-object-injection -- id is route parameter, validated by Express
   const item = repo[id];
 
-  let parsedWidth = null;
-  let parsedHeight = null;
+  let parsedWidth;
+  let parsedHeight;
   if (widthAndHeight) {
     const sizeMatch = widthAndHeight.match(/^(\d+)x(\d+)$/);
     if (sizeMatch) {
@@ -1012,7 +1052,7 @@ async function handleStaticRequest(
 
     // prettier-ignore
     return await respondImage(
-    options, item, z, x, y, bearing, pitch, parsedWidth, parsedHeight, scale, format, res, overlay, 'static',
+    options, item, z, x, y, bearing, pitch, parsedWidth, parsedHeight, scale, format, res, overlay, 'static', id,
      );
   } else if (staticTypeMatch.groups.minx) {
     // Area Based Static Image
@@ -1052,7 +1092,7 @@ async function handleStaticRequest(
 
     // prettier-ignore
     return await respondImage(
-      options, item, z, x, y, bearing, pitch, parsedWidth, parsedHeight, scale, format, res, overlay, 'static',
+      options, item, z, x, y, bearing, pitch, parsedWidth, parsedHeight, scale, format, res, overlay, 'static', id,
      );
   } else if (staticTypeMatch.groups.auto) {
     // Area Static Image
@@ -1111,7 +1151,7 @@ async function handleStaticRequest(
 
     // prettier-ignore
     return await respondImage(
-        options, item, z, x, y, bearing, pitch, parsedWidth, parsedHeight, scale, format, res, overlay, 'static',
+        options, item, z, x, y, bearing, pitch, parsedWidth, parsedHeight, scale, format, res, overlay, 'static', id,
       );
   } else {
     return res.sendStatus(404);
@@ -1119,6 +1159,7 @@ async function handleStaticRequest(
 }
 const existingFonts = {};
 let maxScaleFactor = 2;
+let metricsModule = null;
 
 export const serve_rendered = {
   /**
@@ -1312,6 +1353,13 @@ export const serve_rendered = {
 
     const { publicUrl, verbose, fetchTimeout } = programOpts;
 
+    // Cache metrics module if enabled (avoids per-request dynamic imports).
+    // Guard prevents re-importing per style added. Safe because tests verify before production.
+    if (programOpts.metrics && !metricsModule) {
+      const m = await import('./metrics.js');
+      metricsModule = m;
+    }
+
     const styleJSON = clone(style);
 
     // Global sparse flag for HTTP/remote sources (from config options)
@@ -1857,6 +1905,31 @@ export const serve_rendered = {
         maxPoolSize,
       );
     }
+
+    if (metricsModule) {
+      map._metricsInterval = setInterval(() => {
+        [map.renderers, map.renderersStatic].forEach((poolArr) => {
+          poolArr.forEach((pool) => {
+            if (!pool) return;
+            try {
+              const total = pool.size ?? 0;
+              const available = pool.available ?? 0;
+              metricsModule.renderPoolSize.set({ name: id }, total);
+              metricsModule.renderPoolActive.set(
+                { name: id },
+                total - available,
+              );
+              metricsModule.renderPoolWaiting.set(
+                { name: id },
+                pool.pending ?? 0,
+              );
+            } catch (_) {
+              /* pool may be mid-teardown */
+            }
+          });
+        });
+      }, 5000);
+    }
   },
   /**
    * Removes an item from the repository.
@@ -1868,6 +1941,26 @@ export const serve_rendered = {
     // eslint-disable-next-line security/detect-object-injection -- id is function parameter for removal
     const item = repo[id];
     if (item) {
+      if (item.map._metricsInterval) {
+        clearInterval(item.map._metricsInterval);
+      }
+      Object.keys(item.map.sources || {}).forEach((sourceId) => {
+        // eslint-disable-next-line security/detect-object-injection -- sourceId is from Object.keys() iteration
+        const source = item.map.sources[sourceId];
+        // eslint-disable-next-line security/detect-object-injection -- sourceId is from Object.keys() iteration
+        const sourceType = item.map.sourceTypes[sourceId];
+        if (
+          sourceType === 'mbtiles' &&
+          source &&
+          typeof source.close === 'function'
+        ) {
+          source.close((err) => {
+            if (err) {
+              console.warn('Failed to close MBTiles source:', err);
+            }
+          });
+        }
+      });
       item.map.renderers.forEach((pool) => {
         pool.close();
       });
@@ -1879,25 +1972,59 @@ export const serve_rendered = {
     delete repo[id];
   },
   /**
-   * Removes all items from the repository.
+   * Removes all items from the repository and closes owned local data sources.
    * @param {object} repo Repository object.
-   * @returns {void}
+   * @returns {Promise<void>}
    */
-  clear: function (repo) {
-    Object.keys(repo).forEach((id) => {
-      // eslint-disable-next-line security/detect-object-injection -- id is from Object.keys() iteration
-      const item = repo[id];
-      if (item) {
-        item.map.renderers.forEach((pool) => {
-          pool.close();
-        });
-        item.map.renderersStatic.forEach((pool) => {
-          pool.close();
-        });
-      }
-      // eslint-disable-next-line security/detect-object-injection -- id is from Object.keys() iteration
-      delete repo[id];
-    });
+  clear: async function (repo) {
+    await Promise.all(
+      Object.keys(repo).map(async (id) => {
+        // eslint-disable-next-line security/detect-object-injection -- id is from Object.keys() iteration
+        const item = repo[id];
+        try {
+          if (!item) {
+            return;
+          }
+
+          await Promise.all(
+            Object.keys(item.map.sources || {}).map(async (sourceId) => {
+              // eslint-disable-next-line security/detect-object-injection -- sourceId is from Object.keys() iteration
+              const source = item.map.sources[sourceId];
+              // eslint-disable-next-line security/detect-object-injection -- sourceId is from Object.keys() iteration
+              const sourceType = item.map.sourceTypes[sourceId];
+              if (
+                sourceType === 'mbtiles' &&
+                source &&
+                typeof source.close === 'function'
+              ) {
+                await new Promise((resolve) => {
+                  source.close((err) => {
+                    if (err) {
+                      console.warn(
+                        `Failed to close MBTiles source "${sourceId}" while clearing rendered repo entry "${id}":`,
+                        err,
+                      );
+                    }
+                    resolve();
+                  });
+                });
+              }
+            }),
+          );
+          item.map.renderers.forEach((pool) => {
+            pool.close();
+          });
+          item.map.renderersStatic.forEach((pool) => {
+            pool.close();
+          });
+        } catch (err) {
+          console.warn(`Failed to clear rendered repo entry "${id}":`, err);
+        } finally {
+          // eslint-disable-next-line security/detect-object-injection -- id is from Object.keys() iteration
+          delete repo[id];
+        }
+      }),
+    );
   },
 
   /**