@tryghost/prometheus-metrics 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2013-2025 Ghost Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# Metrics Server
+
+A standalone server for exporting prometheus metrics from Ghost
+
+
+## Usage
+
+
+## Develop
+
+This is a monorepo package.
+
+Follow the instructions for the top-level repo.
+1. `git clone` this repo & `cd` into it as usual
+2. Run `yarn` to install top-level dependencies.
+
+
+
+## Test
+
+- `yarn lint` run just eslint
+- `yarn test` run lint and tests
+

package/build/MetricsServer.d.ts

@@ -0,0 +1,24 @@
+import express from 'express';
+import stoppable from 'stoppable';
+type ServerConfig = {
+    host: string;
+    port: number;
+};
+export declare class MetricsServer {
+    private serverConfig;
+    private handler;
+    private app;
+    private httpServer;
+    private isShuttingDown;
+    constructor({ serverConfig, handler }: {
+        serverConfig: ServerConfig;
+        handler: express.Handler;
+    });
+    start(): Promise<{
+        app: express.Application;
+        httpServer: stoppable.StoppableServer;
+    }>;
+    stop(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export {};

package/build/MetricsServer.js

@@ -0,0 +1,54 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetricsServer = void 0;
+const debug_1 = __importDefault(require("@tryghost/debug"));
+const express_1 = __importDefault(require("express"));
+const stoppable_1 = __importDefault(require("stoppable"));
+const debug = (0, debug_1.default)('metrics-server');
+class MetricsServer {
+    serverConfig;
+    handler;
+    app;
+    httpServer;
+    isShuttingDown;
+    constructor({ serverConfig, handler }) {
+        // initialize local variables
+        this.serverConfig = serverConfig;
+        this.handler = handler;
+        this.app = null;
+        this.httpServer = null;
+        this.isShuttingDown = false;
+    }
+    async start() {
+        // start the server
+        debug('Starting metrics server');
+        this.app = (0, express_1.default)();
+        this.app.get('/metrics', this.handler);
+        const httpServer = this.app.listen(this.serverConfig.port, this.serverConfig.host, () => {
+            debug(`Metrics server listening at ${this.serverConfig.host}:${this.serverConfig.port}`);
+        });
+        this.httpServer = (0, stoppable_1.default)(httpServer, 0);
+        process.on('SIGINT', () => this.shutdown());
+        process.on('SIGTERM', () => this.shutdown());
+        return { app: this.app, httpServer: this.httpServer };
+    }
+    async stop() {
+        // stop the server
+        debug('Stopping metrics server');
+        if (this.httpServer && this.httpServer.listening) {
+            await this.httpServer.stop();
+        }
+    }
+    async shutdown() {
+        if (this.isShuttingDown) {
+            return;
+        }
+        this.isShuttingDown = true;
+        await this.stop();
+        this.isShuttingDown = false;
+    }
+}
+exports.MetricsServer = MetricsServer;

package/build/PrometheusClient.d.ts

@@ -0,0 +1,148 @@
+import { Request, Response } from 'express';
+import client from 'prom-client';
+import type { Metric, MetricObjectWithValues, MetricValue } from 'prom-client';
+import type { Knex } from 'knex';
+type PrometheusClientConfig = {
+    register?: client.Registry;
+    pushgateway?: {
+        enabled: boolean;
+        url?: string;
+        interval?: number;
+        jobName?: string;
+    };
+};
+/**
+ * A client for exporting metrics to Prometheus, based on prom-client
+ */
+export declare class PrometheusClient {
+    /**
+     * Creates a new PrometheusClient instance
+     * @param prometheusConfig - The configuration for the PrometheusClient
+     */
+    constructor(prometheusConfig?: PrometheusClientConfig, logger?: any);
+    client: typeof client;
+    gateway: client.Pushgateway<client.RegistryContentType> | undefined;
+    queries: Map<string, () => void>;
+    acquires: Map<number, () => void>;
+    creates: Map<number, () => void>;
+    private config;
+    private prefix;
+    private pushInterval;
+    private pushRetries;
+    private logger;
+    /**
+     * Initializes the prometheus client, setting up the pushgateway if enabled
+     */
+    init(): void;
+    /**
+     * Pushes metrics to the pushgateway, if enabled
+     */
+    pushMetrics(): Promise<void>;
+    /**
+     * Shuts down the prometheus client cleanly
+     */
+    stop(): void;
+    /**
+     * Tells prom-client to collect default metrics
+     * Only called once on init
+     */
+    collectDefaultMetrics(): void;
+    /**
+     * Handles metrics requests to serve the /metrics endpoint
+     * @param req - The request object
+     * @param res - The response object
+     */
+    handleMetricsRequest(req: Request, res: Response): Promise<void>;
+    /**
+     * Returns the metrics from the registry as a string
+     */
+    getMetrics(): Promise<string>;
+    /**
+     * Returns the metrics from the registry as a JSON object
+     *
+     * Particularly useful for testing
+     */
+    getMetricsAsJSON(): Promise<object[]>;
+    getMetricsAsArray(): Promise<object[]>;
+    /**
+     * Returns the content type for the metrics
+     */
+    getContentType(): "text/plain; version=0.0.4; charset=utf-8";
+    /**
+     * Returns a single metric from the registry
+     * @param name - The name of the metric
+     * @returns The metric
+     */
+    getMetric(name: string): Metric | undefined;
+    /**
+     * Returns the metric object of a single metric, if it exists
+     * @param name - The name of the metric
+     * @returns The values of the metric
+     */
+    getMetricObject(name: string): Promise<MetricObjectWithValues<MetricValue<string>> | undefined>;
+    getMetricValues(name: string): Promise<MetricValue<string>[] | undefined>;
+    /**
+     *
+     */
+    /**
+     * Registers a counter metric
+     * @param name - The name of the metric
+     * @param help - The help text for the metric
+     * @param labelNames - The names of the labels for the metric
+     * @returns The counter metric
+     */
+    registerCounter({ name, help, labelNames }: {
+        name: string;
+        help: string;
+        labelNames?: string[];
+    }): client.Counter;
+    /**
+     * Registers a gauge metric
+     * @param name - The name of the metric
+     * @param help - The help text for the metric
+     * @param collect - The collect function to use for the gauge
+     * @returns The gauge metric
+     */
+    registerGauge({ name, help, collect }: {
+        name: string;
+        help: string;
+        collect?: () => void;
+    }): client.Gauge;
+    /**
+     * Registers a summary metric
+     * @param name - The name of the metric
+     * @param help - The help text for the metric
+     * @param percentiles - The percentiles to calculate for the summary
+     * @param collect - The collect function to use for the summary
+     * @returns The summary metric
+     */
+    registerSummary({ name, help, percentiles, maxAgeSeconds, ageBuckets, pruneAgedBuckets, collect }: {
+        name: string;
+        help: string;
+        percentiles?: number[];
+        maxAgeSeconds?: number;
+        ageBuckets?: number;
+        pruneAgedBuckets?: boolean;
+        collect?: () => void;
+    }): client.Summary;
+    /**
+     * Registers a histogram metric
+     * @param name - The name of the metric
+     * @param help - The help text for the metric
+     * @param buckets - The buckets to calculate for the histogram
+     * @param collect - The collect function to use for the histogram
+     * @returns The histogram metric
+     */
+    registerHistogram({ name, help, buckets }: {
+        name: string;
+        help: string;
+        buckets: number[];
+        collect?: () => void;
+    }): client.Histogram;
+    /**
+     * Instruments the knex connection pool and queries
+     * @param knexInstance - The knex instance
+     */
+    instrumentKnex(knexInstance: Knex): void;
+}
+export {};

package/build/PrometheusClient.js

@@ -0,0 +1,349 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrometheusClient = void 0;
+const http_1 = __importDefault(require("http"));
+const prom_client_1 = __importDefault(require("prom-client"));
+const logging_1 = __importDefault(require("@tryghost/logging"));
+/**
+ * A client for exporting metrics to Prometheus, based on prom-client
+ */
+class PrometheusClient {
+    /**
+     * Creates a new PrometheusClient instance
+     * @param prometheusConfig - The configuration for the PrometheusClient
+     */
+    constructor(prometheusConfig = {}, logger = logging_1.default) {
+        this.config = prometheusConfig;
+        this.client = prom_client_1.default;
+        this.prefix = 'ghost_';
+        this.logger = logger;
+    }
+    client;
+    gateway; // public for testing
+    queries = new Map();
+    acquires = new Map();
+    creates = new Map();
+    config;
+    prefix;
+    pushInterval;
+    pushRetries = 0;
+    logger;
+    /**
+     * Initializes the prometheus client, setting up the pushgateway if enabled
+     */
+    init() {
+        this.collectDefaultMetrics();
+        if (this.config.pushgateway?.enabled) {
+            const gatewayUrl = this.config.pushgateway.url || 'http://localhost:9091';
+            const interval = this.config.pushgateway.interval || 15000;
+            this.gateway = new prom_client_1.default.Pushgateway(gatewayUrl, {
+                timeout: 5000,
+                agent: new http_1.default.Agent({
+                    keepAlive: true,
+                    maxSockets: 1
+                })
+            });
+            this.pushMetrics();
+            this.pushInterval = setInterval(() => {
+                this.pushMetrics();
+            }, interval);
+        }
+    }
+    /**
+     * Pushes metrics to the pushgateway, if enabled
+     */
+    async pushMetrics() {
+        if (this.pushRetries >= 3) {
+            this.logger.error('Failed to push metrics to pushgateway 3 times in a row, giving up');
+            this.stop();
+            return;
+        }
+        if (this.config.pushgateway?.enabled && this.gateway) {
+            const jobName = this.config.pushgateway?.jobName || 'ghost';
+            try {
+                await this.gateway.pushAdd({ jobName });
+                this.logger.debug('Metrics pushed to pushgateway - jobName: ', jobName);
+                this.pushRetries = 0;
+            }
+            catch (err) {
+                let error;
+                if (typeof err === 'object' && err !== null && 'code' in err) {
+                    error = 'Error pushing metrics to pushgateway: ' + err.code;
+                }
+                else {
+                    error = 'Error pushing metrics to pushgateway: Unknown error';
+                }
+                this.logger.error(error);
+                this.pushRetries = this.pushRetries + 1;
+            }
+        }
+    }
+    /**
+     * Shuts down the prometheus client cleanly
+     */
+    stop() {
+        // Clear the push interval
+        if (this.pushInterval) {
+            clearInterval(this.pushInterval);
+        }
+    }
+    /**
+     * Tells prom-client to collect default metrics
+     * Only called once on init
+     */
+    collectDefaultMetrics() {
+        this.client.collectDefaultMetrics({ prefix: this.prefix });
+    }
+    /**
+     * Handles metrics requests to serve the /metrics endpoint
+     * @param req - The request object
+     * @param res - The response object
+     */
+    async handleMetricsRequest(req, res) {
+        try {
+            res.set('Content-Type', this.getContentType());
+            res.end(await this.getMetrics());
+        }
+        catch (err) {
+            if (err instanceof Error && err.message) {
+                res.status(500).end(err.message);
+            }
+            else {
+                res.status(500).end('Unknown error');
+            }
+        }
+    }
+    /**
+     * Returns the metrics from the registry as a string
+     */
+    async getMetrics() {
+        return this.client.register.metrics();
+    }
+    /**
+     * Returns the metrics from the registry as a JSON object
+     *
+     * Particularly useful for testing
+     */
+    async getMetricsAsJSON() {
+        return this.client.register.getMetricsAsJSON();
+    }
+    async getMetricsAsArray() {
+        return this.client.register.getMetricsAsArray();
+    }
+    /**
+     * Returns the content type for the metrics
+     */
+    getContentType() {
+        return this.client.register.contentType;
+    }
+    /**
+     * Returns a single metric from the registry
+     * @param name - The name of the metric
+     * @returns The metric
+     */
+    getMetric(name) {
+        if (!name.startsWith(this.prefix)) {
+            name = `${this.prefix}${name}`;
+        }
+        return this.client.register.getSingleMetric(name);
+    }
+    /**
+     * Returns the metric object of a single metric, if it exists
+     * @param name - The name of the metric
+     * @returns The values of the metric
+     */
+    async getMetricObject(name) {
+        const metric = this.getMetric(name);
+        if (!metric) {
+            return undefined;
+        }
+        return await metric.get();
+    }
+    async getMetricValues(name) {
+        const metricObject = await this.getMetricObject(name);
+        if (!metricObject) {
+            return undefined;
+        }
+        return metricObject.values;
+    }
+    /**
+     *
+     */
+    /**
+     * Registers a counter metric
+     * @param name - The name of the metric
+     * @param help - The help text for the metric
+     * @param labelNames - The names of the labels for the metric
+     * @returns The counter metric
+     */
+    registerCounter({ name, help, labelNames = [] }) {
+        return new this.client.Counter({
+            name: `${this.prefix}${name}`,
+            help,
+            labelNames
+        });
+    }
+    /**
+     * Registers a gauge metric
+     * @param name - The name of the metric
+     * @param help - The help text for the metric
+     * @param collect - The collect function to use for the gauge
+     * @returns The gauge metric
+     */
+    registerGauge({ name, help, collect }) {
+        return new this.client.Gauge({
+            name: `${this.prefix}${name}`,
+            help,
+            collect
+        });
+    }
+    /**
+     * Registers a summary metric
+     * @param name - The name of the metric
+     * @param help - The help text for the metric
+     * @param percentiles - The percentiles to calculate for the summary
+     * @param collect - The collect function to use for the summary
+     * @returns The summary metric
+     */
+    registerSummary({ name, help, percentiles, maxAgeSeconds, ageBuckets, pruneAgedBuckets, collect }) {
+        return new this.client.Summary({
+            name: `${this.prefix}${name}`,
+            help,
+            percentiles: percentiles || [0.5, 0.9, 0.99],
+            maxAgeSeconds,
+            ageBuckets,
+            pruneAgedBuckets,
+            collect
+        });
+    }
+    /**
+     * Registers a histogram metric
+     * @param name - The name of the metric
+     * @param help - The help text for the metric
+     * @param buckets - The buckets to calculate for the histogram
+     * @param collect - The collect function to use for the histogram
+     * @returns The histogram metric
+     */
+    registerHistogram({ name, help, buckets }) {
+        return new this.client.Histogram({
+            name: `${this.prefix}${name}`,
+            help,
+            buckets: buckets
+        });
+    }
+    // Utility functions for creating custom metrics
+    /**
+     * Instruments the knex connection pool and queries
+     * @param knexInstance - The knex instance
+     */
+    instrumentKnex(knexInstance) {
+        // Create some gauges for tracking the connection pool
+        this.registerGauge({
+            name: `db_connection_pool_max`,
+            help: 'The maximum number of connections allowed in the pool',
+            collect() {
+                this.set(knexInstance.client.pool.max);
+            }
+        });
+        this.registerGauge({
+            name: `db_connection_pool_min`,
+            help: 'The minimum number of connections allowed in the pool',
+            collect() {
+                this.set(knexInstance.client.pool.min);
+            }
+        });
+        this.registerGauge({
+            name: `db_connection_pool_active`,
+            help: 'The number of active connections to the database, which can be in use or idle',
+            collect() {
+                this.set(knexInstance.client.pool.numUsed() + knexInstance.client.pool.numFree());
+            }
+        });
+        this.registerGauge({
+            name: `db_connection_pool_used`,
+            help: 'The number of connections currently in use by the database',
+            collect() {
+                this.set(knexInstance.client.pool.numUsed());
+            }
+        });
+        this.registerGauge({
+            name: `db_connection_pool_idle`,
+            help: 'The number of active connections currently idle in pool',
+            collect() {
+                this.set(knexInstance.client.pool.numFree());
+            }
+        });
+        this.registerGauge({
+            name: `db_connection_pool_pending_acquires`,
+            help: 'The number of connections currently waiting to be acquired from the pool',
+            collect() {
+                this.set(knexInstance.client.pool.numPendingAcquires());
+            }
+        });
+        this.registerGauge({
+            name: `db_connection_pool_pending_creates`,
+            help: 'The number of connections currently waiting to be created',
+            collect() {
+                this.set(knexInstance.client.pool.numPendingCreates());
+            }
+        });
+        const queryDurationSummary = this.registerSummary({
+            name: `db_query_duration_seconds`,
+            help: 'Summary of the duration of knex database queries in seconds',
+            percentiles: [0.5, 0.9, 0.99],
+            maxAgeSeconds: 60,
+            ageBuckets: 6,
+            pruneAgedBuckets: false
+        });
+        const acquireDurationSummary = this.registerSummary({
+            name: `db_connection_acquire_duration_seconds`,
+            help: 'Summary of the duration of acquiring a connection from the pool in seconds',
+            percentiles: [0.5, 0.9, 0.99],
+            maxAgeSeconds: 60,
+            ageBuckets: 6,
+            pruneAgedBuckets: false
+        });
+        const createDurationSummary = this.registerSummary({
+            name: `db_connection_create_duration_seconds`,
+            help: 'Summary of the duration of creating a connection in seconds',
+            percentiles: [0.5, 0.9, 0.99],
+            maxAgeSeconds: 60,
+            ageBuckets: 6,
+            pruneAgedBuckets: false
+        });
+        knexInstance.on('query', (query) => {
+            // Add the query to the map
+            this.queries.set(query.__knexQueryUid, queryDurationSummary.startTimer());
+        });
+        knexInstance.on('query-response', (err, query) => {
+            this.queries.get(query.__knexQueryUid)?.();
+            this.queries.delete(query.__knexQueryUid);
+        });
+        knexInstance.client.pool.on('createRequest', (eventId) => {
+            this.creates.set(eventId, createDurationSummary.startTimer());
+        });
+        knexInstance.client.pool.on('createSuccess', (eventId) => {
+            this.creates.get(eventId)?.();
+            this.creates.delete(eventId);
+        });
+        knexInstance.client.pool.on('createFail', (eventId) => {
+            this.creates.get(eventId)?.();
+            this.creates.delete(eventId);
+        });
+        knexInstance.client.pool.on('acquireRequest', (eventId) => {
+            this.acquires.set(eventId, acquireDurationSummary.startTimer());
+        });
+        knexInstance.client.pool.on('acquireSuccess', (eventId) => {
+            this.acquires.get(eventId)?.();
+            this.acquires.delete(eventId);
+        });
+        knexInstance.client.pool.on('acquireFail', (eventId) => {
+            this.acquires.get(eventId)?.();
+            this.acquires.delete(eventId);
+        });
+    }
+}
+exports.PrometheusClient = PrometheusClient;

package/build/index.d.ts

@@ -0,0 +1,2 @@
+export * from './MetricsServer';
+export * from './PrometheusClient';

package/build/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./MetricsServer"), exports);
+__exportStar(require("./PrometheusClient"), exports);

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@tryghost/prometheus-metrics",
+  "version": "1.0.0",
+  "repository": "https://github.com/TryGhost/Ghost/tree/main/packages/prometheus-metrics",
+  "author": "Ghost Foundation",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "scripts": {
+    "dev": "tsc --watch --preserveWatchOutput --sourceMap",
+    "build": "yarn build:ts",
+    "build:ts": "tsc",
+    "prepare": "tsc",
+    "test:unit": "NODE_ENV=testing c8 --src src --all --check-coverage --90 --reporter text --reporter cobertura mocha -r ts-node/register './test/**/*.test.ts'",
+    "test": "yarn test:types && yarn test:unit",
+    "test:types": "tsc --noEmit",
+    "lint:code": "eslint src/ --ext .ts --cache",
+    "lint": "yarn lint:code && yarn lint:test",
+    "lint:test": "eslint -c test/.eslintrc.js test/ --ext .ts --cache"
+  },
+  "files": [
+    "build"
+  ],
+  "devDependencies": {
+    "@types/express": "4.17.21",
+    "@types/sinon": "17.0.4",
+    "@types/stoppable": "1.1.3",
+    "@types/supertest": "6.0.3",
+    "c8": "10.1.2",
+    "knex": "2.4.2",
+    "mocha": "10.8.2",
+    "nock": "13.5.6",
+    "sinon": "19.0.5",
+    "supertest": "7.0.0",
+    "ts-node": "10.9.2",
+    "typescript": "5.8.3"
+  },
+  "dependencies": {
+    "@tryghost/logging": "2.4.21",
+    "express": "4.21.2",
+    "prom-client": "15.1.3",
+    "stoppable": "1.1.0"
+  },
+  "gitHead": "422803e3f596e81f0321c328680e08d8221af5b4"
+}