@tryghost/metrics 3.5.4 → 3.6.0

package/README.md

@@ -65,6 +65,75 @@ An invalid configured rate throws when the instance is constructed. An invalid
 per-call rate is ignored in favour of the configured rate, so a bad call site
 cannot break the code path it is measuring.
 
+### Batching
+
+Sampling reduces how many metrics are shipped; batching reduces how many
+requests they take. With batching on, the Elasticsearch transport buffers
+documents and ships them with the bulk API, so a hot code path costs one
+request per batch instead of one per metric. It is off by default:
+
+```js
+const metrics = require('@tryghost/metrics');
+
+const batched = new metrics.GhostMetrics({
+    metrics: {
+        transports: ['elasticsearch'],
+        batch: true,
+    },
+});
+```
+
+`batch: true` uses the defaults; pass an object to override them:
+
+| Option          | Default     | Meaning                                                         |
+| --------------- | ----------- | --------------------------------------------------------------- |
+| `enabled`       | `true`      | Set to `false` to turn batching off without dropping the config |
+| `size`          | `100`       | Buffered documents that trigger a bulk request                  |
+| `maxWaitMs`     | `5000`      | How long a document may sit in the buffer before it is shipped  |
+| `maxBufferSize` | `size * 10` | Hard cap on buffered documents; further metrics are dropped     |
+
+```js
+const batched = new metrics.GhostMetrics({
+    metrics: {
+        transports: ['elasticsearch'],
+        batch: {
+            size: 500,
+            maxWaitMs: 2000,
+        },
+    },
+});
+```
+
+Documents for different metric names can share a batch, because each bulk
+operation carries its own index. Sampling still applies first, so only metrics
+that survive their sample rate are buffered.
+
+Batching changes two things worth knowing about:
+
+- `metric()` resolves once the metric is **buffered**, not once it has been
+  shipped. It was already fire-and-forget for most callers, but a caller that
+  awaited delivery no longer gets it.
+- Buffered metrics are lost if the process exits without draining them. Call
+  `flush()` from your shutdown handler; it is a no-op when batching is off, so
+  it is always safe to call.
+
+```js
+process.on('SIGTERM', async () => {
+    await batched.flush();
+    process.exit(0);
+});
+```
+
+The buffer is bounded: once it holds `maxBufferSize` documents, further metrics
+are dropped rather than growing the heap while Elasticsearch is slow or down.
+Only one bulk request is ever in flight, and a failed batch is dropped without
+rejecting, so a metric call can never break the code path it is measuring.
+
+Invalid batch config throws when the instance is constructed.
+
+The stdout transport is unaffected - it writes locally, so there is nothing to
+batch.
+
 ### Types
 
 Types ship with the package. `GhostMetrics` is exported as both a value (the
@@ -77,6 +146,7 @@ import type {
     GhostMetricsOptions,
     MetricsOptions,
     MetricOptions,
+    BatchOptions,
     ElasticsearchOptions,
     MetricShipper,
 } from '@tryghost/metrics';

package/lib/GhostMetrics.d.ts

@@ -1,3 +1,5 @@
+import MetricsBatch = require('./MetricsBatch');
+
 /**
  * Elasticsearch transport configuration.
  */
@@ -12,6 +14,29 @@ interface ElasticsearchOptions {
     proxy?: string;
 }
 
+/**
+ * Batch shipping configuration for network transports.
+ */
+interface BatchOptions {
+    /** Set to `false` to turn batching off while keeping the rest of the config. @default true */
+    enabled?: boolean;
+    /** Buffered documents that trigger a bulk request. @default 100 */
+    size?: number;
+    /** How long a document may sit in the buffer before it is shipped, in milliseconds. @default 5000 */
+    maxWaitMs?: number;
+    /** Hard cap on buffered documents; further metrics are dropped. @default `size * 10` */
+    maxBufferSize?: number;
+}
+
+/**
+ * Resolved batch configuration, with every value filled in.
+ */
+interface ResolvedBatchOptions {
+    size: number;
+    maxWaitMs: number;
+    maxBufferSize: number;
+}
+
 /**
  * Metrics-specific configuration, piggy-backed on the logging config.
  */
@@ -27,6 +52,12 @@ interface MetricsOptions {
     sampleRate?: number;
     /** Per-metric sample rate overrides, keyed by metric name. Same validation as `sampleRate`. */
     sampleRates?: Record<string, number>;
+    /**
+     * Ship metrics in batches rather than one request per metric. `true` uses the defaults,
+     * an object overrides them, absent or `false` keeps one request per metric. Throws at
+     * construction time for values that aren't positive whole numbers.
+     */
+    batch?: boolean | BatchOptions;
 }
 
 /**
@@ -71,7 +102,11 @@ declare class GhostMetrics {
     metadata: Record<string, unknown>;
     sampleRate: number;
     sampleRates: Record<string, number>;
+    /** Resolved batch config, or `null` when batching is off. */
+    batch: ResolvedBatchOptions | null;
     shippers: Record<string, MetricShipper>;
+    /** Buffers belonging to batching transports, drained by {@link GhostMetrics.flush}. */
+    batches: MetricsBatch[];
 
     constructor(options?: GhostMetricsOptions);
 
@@ -82,10 +117,16 @@ declare class GhostMetrics {
 
     /**
      * Setup ElasticSearch metric shipper. Metrics are shipped to a per-metric
-     * index named `metrics-<name>`; the metric name should be sluggified.
+     * index named `metrics-<name>`; the metric name should be sluggified. With
+     * batching on, documents are buffered and shipped with the bulk API.
      */
     setupElasticsearchShipper(): void;
 
+    /**
+     * Ship anything buffered by batching transports. A no-op when batching is off.
+     */
+    flush(): Promise<void>;
+
     /**
      * Resolve the sample rate for a metric: per-call override, then per-metric config,
      * then the instance default.
@@ -94,6 +135,8 @@ declare class GhostMetrics {
 
     /**
      * Ship a metric through every configured transport, unless it is dropped by sampling.
+     * With batching on, the returned promise resolves once the metric is buffered rather
+     * than once it has been shipped.
      * @param name Metric name, should be slugified for back-end compatibility (e.g. `"memory-usage"`).
      * @param value Metric value; coerced to an object before being shipped.
      * @param options Per-call options, e.g. a `sampleRate` override.
@@ -106,6 +149,8 @@ declare namespace GhostMetrics {
         ElasticsearchOptions,
         MetricsOptions,
         MetricOptions,
+        BatchOptions,
+        ResolvedBatchOptions,
         GhostMetricsOptions,
         MetricShipper,
     };

package/lib/GhostMetrics.js

@@ -1,4 +1,10 @@
 const jsonStringifySafe = require('json-stringify-safe');
+const MetricsBatch = require('./MetricsBatch');
+
+const DEFAULT_BATCH_SIZE = 100;
+const DEFAULT_BATCH_MAX_WAIT_MS = 5000;
+// Ten batches' worth of headroom before the buffer starts shedding load
+const DEFAULT_BATCH_BUFFER_FACTOR = 10;
 
 /**
  * @description Check a value is usable as a sample rate: a number between 0 and 1 inclusive
@@ -27,6 +33,156 @@ function normalizeSampleRate(rate, key) {
     return rate;
 }
 
+/**
+ * @description Validate a batching config value that must be a positive whole number
+ * @param {any} value Candidate value
+ * @param {number} fallback Value to use when unset
+ * @param {string} key Config key used in the error message
+ * @returns {number}
+ */
+function normalizePositiveInteger(value, fallback, key) {
+    if (value === undefined || value === null) {
+        return fallback;
+    }
+
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1) {
+        throw new Error(`${key} must be a positive whole number, got ${jsonStringifySafe(value)}`);
+    }
+
+    return value;
+}
+
+/**
+ * @description Validate the batching config, returning null when batching is off
+ * @param {any} batch Candidate batch config: absent/false for off, true or a property bag for on
+ * @returns {{size: number, maxWaitMs: number, maxBufferSize: number} | null}
+ */
+function normalizeBatch(batch) {
+    if (batch === undefined || batch === null || batch === false) {
+        return null;
+    }
+
+    if (batch === true) {
+        batch = {};
+    }
+
+    if (typeof batch !== 'object' || Array.isArray(batch)) {
+        throw new Error(
+            `metrics.batch must be a boolean or an object, got ${jsonStringifySafe(batch)}`,
+        );
+    }
+
+    // `enabled` lets a deployment turn batching off without discarding the rest
+    // of the config, which matters when it is layered from config files
+    if ('enabled' in batch && typeof batch.enabled !== 'boolean') {
+        throw new Error(
+            `metrics.batch.enabled must be a boolean, got ${jsonStringifySafe(batch.enabled)}`,
+        );
+    }
+
+    if (batch.enabled === false) {
+        return null;
+    }
+
+    const size = normalizePositiveInteger(batch.size, DEFAULT_BATCH_SIZE, 'metrics.batch.size');
+    const maxWaitMs = normalizePositiveInteger(
+        batch.maxWaitMs,
+        DEFAULT_BATCH_MAX_WAIT_MS,
+        'metrics.batch.maxWaitMs',
+    );
+    const maxBufferSize = normalizePositiveInteger(
+        batch.maxBufferSize,
+        size * DEFAULT_BATCH_BUFFER_FACTOR,
+        'metrics.batch.maxBufferSize',
+    );
+
+    if (maxBufferSize < size) {
+        throw new Error(
+            `metrics.batch.maxBufferSize must be at least metrics.batch.size (${size}), got ${maxBufferSize}`,
+        );
+    }
+
+    return { size, maxWaitMs, maxBufferSize };
+}
+
+/**
+ * @description Clone structured metric data without allowing unusual values
+ * to make instrumentation throw.
+ * @param {any} value Value to clone
+ * @returns {any}
+ */
+function cloneMetricValueFallback(value, seen = new WeakMap()) {
+    if (typeof value !== 'object' || value === null) {
+        return value;
+    }
+
+    if (seen.has(value)) {
+        return seen.get(value);
+    }
+
+    const prototype = Object.getPrototypeOf(value);
+    if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) {
+        return value;
+    }
+
+    const clone = Array.isArray(value) ? [] : Object.create(prototype);
+    seen.set(value, clone);
+
+    for (const [key, nestedValue] of Object.entries(value)) {
+        clone[key] = cloneMetricValueFallback(nestedValue, seen);
+    }
+
+    return clone;
+}
+
+function cloneMetricValue(value) {
+    if (typeof value !== 'object' || value === null) {
+        return value;
+    }
+
+    try {
+        return structuredClone(value);
+    } catch {
+        // Keep instrumentation from throwing for unusual non-cloneable values.
+        return cloneMetricValueFallback(value);
+    }
+}
+
+/**
+ * @description Build the document shipped for a metric value
+ * The value is copied rather than mutated, so a batched document can't be
+ * changed by the caller after it has been buffered.
+ * @param {any} value Value of the metric
+ * @param {object} metadata Metadata to ship alongside the value
+ * @param {number} sampleRate Rate the metric survived
+ * @returns {object}
+ */
+function buildDocument(value, metadata, sampleRate) {
+    // Metrics are expected to be structured data. Clone them synchronously so
+    // callers can safely reuse or mutate nested values after `metric()` returns.
+    const clonedValue = cloneMetricValue(value);
+    const document =
+        typeof clonedValue === 'object' && clonedValue !== null && !Array.isArray(clonedValue)
+            ? clonedValue
+            : { value: clonedValue };
+
+    if (!('@timestamp' in document)) {
+        document['@timestamp'] = Date.now();
+    }
+
+    if (metadata) {
+        document.metadata = cloneMetricValue(metadata);
+    }
+
+    // Sampled documents carry their rate so consumers can scale counts back up.
+    // An absent sampleRate means the metric was not sampled (i.e. a rate of 1).
+    if (sampleRate < 1) {
+        document.sampleRate = sampleRate;
+    }
+
+    return document;
+}
+
 /**
  * @description Metric shipper class built on the loggingrc config used in Ghost projects
  */
@@ -40,6 +196,7 @@ class GhostMetrics {
      * metrics.metadata:    A property bag of metadata values to be shipped alongside the metric value
      * metrics.sampleRate:  Default proportion of metrics to ship, between 0 and 1 (defaults to 1, ship everything)
      * metrics.sampleRates: Per-metric sample rate overrides, keyed by metric name
+     * metrics.batch:       Batch shipping config for network transports; absent or false to ship one metric per request
      * elasticsearch:       Elasticsearch transport configuration
      * @param {object} options Bag of options
      */
@@ -56,6 +213,7 @@ class GhostMetrics {
             this.transports = options.metrics.transports || [];
             this.metadata = options.metrics.metadata || {};
             this.sampleRate = normalizeSampleRate(options.metrics.sampleRate, 'metrics.sampleRate');
+            this.batch = normalizeBatch(options.metrics.batch);
 
             for (const [name, rate] of Object.entries(options.metrics.sampleRates || {})) {
                 this.sampleRates[name] = normalizeSampleRate(rate, `metrics.sampleRates.${name}`);
@@ -64,6 +222,7 @@ class GhostMetrics {
             this.transports = [];
             this.metadata = {};
             this.sampleRate = 1;
+            this.batch = null;
         }
 
         // CASE: special env variable to enable long mode and level info
@@ -72,6 +231,8 @@ class GhostMetrics {
         }
 
         this.shippers = {};
+        // Populated by transports that buffer, so `flush()` can drain them
+        this.batches = [];
 
         this.transports.forEach((transport) => {
             let transportFn = `setup${transport[0].toUpperCase()}${transport.substr(1)}Shipper`;
@@ -126,29 +287,49 @@ class GhostMetrics {
             proxy: 'proxy' in this.elasticsearch ? this.elasticsearch.proxy : null,
         });
 
-        this.shippers.elasticsearch = (name, value, sampleRate) => {
-            if (typeof value !== 'object') {
-                value = { value };
-            }
+        if (!this.batch) {
+            this.shippers.elasticsearch = (name, value, sampleRate) => {
+                return elasticSearch.index(
+                    buildDocument(value, this.metadata, sampleRate),
+                    `metrics-${name}`,
+                );
+            };
 
-            if (!('@timestamp' in value)) {
-                value['@timestamp'] = Date.now();
-            }
+            return;
+        }
 
-            if (this.metadata) {
-                value.metadata = this.metadata;
-            }
+        // Batched metrics are shipped with the bulk API, so a hot code path
+        // costs one request per batch instead of one per metric. Documents for
+        // different metric names can share a batch because each operation
+        // carries its own index.
+        const batch = new MetricsBatch({
+            ...this.batch,
+            ship: (operations) => elasticSearch.bulk(operations),
+        });
 
-            // Sampled documents carry their rate so consumers can scale counts back up.
-            // An absent sampleRate means the metric was not sampled (i.e. a rate of 1).
-            if (sampleRate < 1) {
-                value.sampleRate = sampleRate;
-            }
+        this.batches.push(batch);
 
-            return elasticSearch.index(value, `metrics-${name}`);
+        this.shippers.elasticsearch = (name, value, sampleRate) => {
+            batch.add({
+                index: `metrics-${name}`,
+                document: buildDocument(value, this.metadata, sampleRate),
+            });
+
+            // Resolves once the metric is buffered, not once it is shipped
+            return Promise.resolve();
         };
     }
 
+    /**
+     * @description Ship anything buffered by batching transports
+     * A no-op when batching is off, so callers (e.g. a shutdown handler) can
+     * always call it without knowing how the instance is configured.
+     * @returns {Promise<void>}
+     */
+    async flush() {
+        await Promise.allSettled(this.batches.map((batch) => batch.flush()));
+    }
+
     /**
      * @description Resolve the sample rate for a metric, most specific config first
      * Invalid per-call overrides are ignored rather than thrown, so a bad call site cannot

package/lib/MetricsBatch.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Buffers shipping operations and hands them off in batches.
+ *
+ * Batching trades delivery latency for a much smaller number of requests.
+ * Buffered operations are handed off when the buffer reaches `size`, when
+ * `maxWaitMs` has elapsed since the first buffered operation, or when
+ * {@link MetricsBatch.flush} is called.
+ */
+declare class MetricsBatch<T = unknown> {
+    /** Number of buffered operations that triggers a hand-off. */
+    size: number;
+    /** How long an operation may sit in the buffer before it is handed off, in milliseconds. */
+    maxWaitMs: number;
+    /** Hard cap on buffered operations; further operations are dropped. */
+    maxBufferSize: number;
+    /** Hands a batch of operations to the transport. */
+    ship: (operations: T[]) => Promise<unknown>;
+    /** Operations waiting to be shipped. */
+    buffer: T[];
+    /** Count of operations dropped because the buffer was full. */
+    dropped: number;
+
+    constructor(options: {
+        size: number;
+        maxWaitMs: number;
+        maxBufferSize: number;
+        ship: (operations: T[]) => Promise<unknown>;
+    });
+
+    /**
+     * Buffer an operation, handing the buffer off if it is now full. Operations
+     * arriving once the buffer is at `maxBufferSize` are dropped.
+     */
+    add(operation: T): void;
+
+    /** Start the max-wait timer, unless one is already running. */
+    startTimer(): void;
+
+    /**
+     * Ship everything buffered right now, waiting behind any in-flight batch.
+     * Never rejects.
+     */
+    flush(): Promise<void>;
+
+    /** Hand the whole buffer to the transport. Never rejects. */
+    drain(): Promise<void>;
+}
+
+export = MetricsBatch;

package/lib/MetricsBatch.js

@@ -0,0 +1,117 @@
+/**
+ * @description Buffers shipping operations and hands them off in batches
+ *
+ * Batching trades delivery latency for a much smaller number of requests: the
+ * caller gets one round-trip per batch instead of one per metric. Buffered
+ * operations are handed off when the buffer reaches `size`, when `maxWaitMs`
+ * has elapsed since the first buffered operation, or when `flush()` is called.
+ */
+class MetricsBatch {
+    /**
+     * @param {object} options Bag of options
+     * @param {number} options.size Number of buffered operations that triggers a hand-off
+     * @param {number} options.maxWaitMs How long an operation may sit in the buffer before it is handed off
+     * @param {number} options.maxBufferSize Hard cap on buffered operations; further operations are dropped
+     * @param {(operations: any[]) => Promise<any>} options.ship Hands a batch of operations to the transport
+     */
+    constructor({ size, maxWaitMs, maxBufferSize, ship }) {
+        this.size = size;
+        this.maxWaitMs = maxWaitMs;
+        this.maxBufferSize = maxBufferSize;
+        this.ship = ship;
+
+        this.buffer = [];
+        this.timer = null;
+        // Serialises hand-offs, so only one batch is ever in flight
+        this.pending = Promise.resolve();
+        // A non-zero count means the transport couldn't keep up and metrics
+        // were lost; read it off the instance when metrics go missing
+        this.dropped = 0;
+    }
+
+    /**
+     * @description Buffer an operation, handing the buffer off if it is now full
+     * @param {any} operation Operation to ship
+     */
+    add(operation) {
+        if (this.buffer.length >= this.maxBufferSize) {
+            // Shed load rather than growing without bound when the transport is
+            // slow or down: losing metrics beats exhausting the heap
+            this.dropped += 1;
+            return;
+        }
+
+        this.buffer.push(operation);
+
+        // Queue exactly once when the buffer crosses the threshold. `drain()`
+        // resets the buffer before awaiting the transport, so the next buffer
+        // can independently cross the threshold and line up behind it.
+        if (this.buffer.length === this.size) {
+            this.flush();
+            return;
+        }
+
+        this.startTimer();
+    }
+
+    /**
+     * @description Start the max-wait timer, unless one is already running
+     * The timer is unreferenced so a partially full buffer can never hold the
+     * event loop - and therefore the process - open.
+     */
+    startTimer() {
+        if (this.timer) {
+            return;
+        }
+
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.flush();
+        }, this.maxWaitMs);
+
+        this.timer.unref?.();
+    }
+
+    /**
+     * @description Ship everything buffered right now
+     * Waits behind any in-flight batch, so batches reach the transport in
+     * order and only one request is open at a time.
+     * @returns {Promise<void>}
+     */
+    flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+
+        const previous = this.pending;
+
+        this.pending = previous.then(() => this.drain());
+
+        return this.pending;
+    }
+
+    /**
+     * @description Hand the whole buffer to the transport
+     * Never rejects, so a failed batch can't poison the hand-off chain or the
+     * code path being measured. Transports report their own failures - the
+     * Elasticsearch one logs them under the `logging:elasticsearch` debug namespace.
+     * @returns {Promise<void>}
+     */
+    async drain() {
+        if (this.buffer.length === 0) {
+            return;
+        }
+
+        const operations = this.buffer;
+        this.buffer = [];
+
+        try {
+            await this.ship(operations);
+        } catch {
+            // Swallowed: a metric call can never break the path it measures
+        }
+    }
+}
+
+module.exports = MetricsBatch;

package/lib/metrics.d.ts

@@ -17,6 +17,8 @@ declare namespace metrics {
     export type ElasticsearchOptions = GhostMetricsClass.ElasticsearchOptions;
     export type MetricsOptions = GhostMetricsClass.MetricsOptions;
     export type MetricOptions = GhostMetricsClass.MetricOptions;
+    export type BatchOptions = GhostMetricsClass.BatchOptions;
+    export type ResolvedBatchOptions = GhostMetricsClass.ResolvedBatchOptions;
     export type GhostMetricsOptions = GhostMetricsClass.GhostMetricsOptions;
     export type MetricShipper = GhostMetricsClass.MetricShipper;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryghost/metrics",
-  "version": "3.5.4",
+  "version": "3.6.0",
   "license": "MIT",
   "author": "Ghost Foundation",
   "repository": {
@@ -19,9 +19,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@tryghost/elasticsearch": "^5.4.10",
-    "@tryghost/pretty-stream": "^2.3.13",
-    "@tryghost/root-utils": "^2.3.13",
+    "@tryghost/elasticsearch": "^5.4.11",
+    "@tryghost/pretty-stream": "^2.3.14",
+    "@tryghost/root-utils": "^2.3.14",
     "json-stringify-safe": "^5.0.1"
   },
   "devDependencies": {