feat(browser): opt-in OpenTelemetry OTLP metrics export; v1.13.0

packages/browser/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@harperfast/prerender-browser",
-	"version": "1.12.0",
+	"version": "1.13.0",
 	"type": "module",
 	"description": "Headless-browser render library for Harper Prerender: claims render jobs from the @harperfast/prerender queue, renders pages in headless Chrome (Puppeteer), and posts the HTML back. Embedded by a render service and configured entirely via startWorker() options.",
 	"keywords": [
@@ -44,6 +44,10 @@
 		"prepublishOnly": "npm run build"
 	},
 	"dependencies": {
+		"@opentelemetry/api": "^1.9.1",
+		"@opentelemetry/exporter-metrics-otlp-proto": "^0.221.0",
+		"@opentelemetry/resources": "^2.10.0",
+		"@opentelemetry/sdk-metrics": "^2.10.0",
 		"mqtt": "^5.10.4",
 		"pino": "^9.9.0",
 		"puppeteer": "^24.7.2",

packages/browser/src/Worker.ts

@@ -8,6 +8,7 @@ import { noop } from './util/noop.js';
 import { getResourceCache } from './ResourceCache.js';
 import { settings } from './settings.js';
 import { CpuSampler } from './util/cpu.js';
+import type { MetricsRecorder } from './metrics.js';
 
 export type Renderer = (page: Page, job: RenderJob) => Promise<string | undefined>;
 
@@ -29,6 +30,12 @@ type RenderWorkerConfig = {
 	rps?: number;
 
 	browserLaunchOptions?: LaunchOptions;
+
+	/**
+	 * Optional metrics recorder. When present, each stats window is folded into it (see
+	 * `logStats`) and it is flushed on shutdown. Absent unless the embedder enabled OTLP metrics.
+	 */
+	metrics?: MetricsRecorder;
 };
 
 export default class RenderWorker {
@@ -57,6 +64,9 @@ export default class RenderWorker {
 
 	rps = 10;
 
+	// Optional OTLP metrics recorder; null unless the embedder enabled metrics.
+	private metrics: MetricsRecorder | null = null;
+
 	inflight: Set<Promise<void>> = new Set();
 
 	lastRenderStartTime = Date.now();
@@ -102,6 +112,7 @@ export default class RenderWorker {
 		this.CONCURRENCY = config.maxConcurrency ?? 5;
 		this.BROWSER_MAX_TOTAL_PAGES = config.browserExpirationThreshold ?? 5000;
 		this.renderFn = config.renderer;
+		this.metrics = config.metrics ?? null;
 
 		this.browserCleanupInterval = setInterval(() => {
 			this.closeRetiredBrowsers();
@@ -284,6 +295,40 @@ export default class RenderWorker {
 			rssMb: Math.round(mem.rss / 1024 / 1024),
 			resourceCache: cacheStats,
 		});
+
+		// Fold the same window into OTLP metrics (no-op unless the embedder enabled them). `s`
+		// still holds the raw per-render sample arrays, so histograms get true observations —
+		// not the already-summarized percentiles above.
+		this.metrics?.record(
+			{
+				completed: s.completed,
+				succeeded: s.succeeded,
+				emptyContent: s.emptyContent,
+				fromSitemap: s.fromSitemap,
+				failures: s.failures,
+				expiredSkipped: s.expiredSkipped,
+				concurrencyBlocked: s.concurrencyBlocked,
+				rpsDelayed: s.rpsDelayed,
+				resultPostFailures: s.resultPostFailures,
+				browserLaunches: s.browserLaunches,
+				browserRetirements: s.browserRetirements,
+				renderTimes: s.renderTimes,
+				navTtfb: s.navTtfb,
+				navTotal: s.navTotal,
+				settle: s.settle,
+				postProcess: s.postProcess,
+			},
+			{
+				inflight: this.inflight.size,
+				concurrency: this.CONCURRENCY,
+				retiredBrowsers: this.retiredBrowsers.size,
+				rssBytes: mem.rss,
+				workerCores: cpu.workerCores,
+				nodeCores: cpu.nodeCores,
+				browserCores: cpu.browserCores,
+				cacheHitRate: cacheStats ? cacheStats.hitRate : null,
+			}
+		);
 	}
 
 	/**
@@ -318,7 +363,31 @@ export default class RenderWorker {
 			this.browserCleanupInterval = null;
 		}
 
+		// Emit one final stats window before tearing down. The interval timer is now cleared, so the
+		// up-to-one-window of counts/timings accumulated since the last tick would otherwise be lost
+		// from both the log line and (more importantly) the metrics flush below — logStats() folds it
+		// into the recorder via record(), while this.metrics is still set. Guarded so a failure here
+		// (e.g. mid-uncaughtException) can't block the browser cleanup that follows.
+		try {
+			this.logStats();
+		} catch (err) {
+			logger.warn({ err }, 'failed to log final stats during destroy');
+		}
+
 		const closing: Promise<void>[] = [];
+		// Flush the buffered metrics (incl. the final window just recorded above) before the loop
+		// dies (shutdown() is internally guarded — never throws). Cap the wait so a down collector's
+		// flush retries can't delay container exit — losing that last export to a dead collector is an
+		// acceptable trade. AbortController cancels the cap timer once the flush wins so it doesn't
+		// linger on the event loop (mirrors the drain above).
+		if (this.metrics) {
+			const metrics = this.metrics;
+			this.metrics = null;
+			const ac = new AbortController();
+			const flush = metrics.shutdown().finally(() => ac.abort());
+			const cap = setTimeout(2000, undefined, { signal: ac.signal }).catch(() => {});
+			closing.push(Promise.race([flush, cap]));
+		}
 		if (this.browser) {
 			closing.push(this.browser.close().catch(noop));
 		}

packages/browser/src/index.ts

@@ -24,6 +24,7 @@ import { applySettings, settings, defaultLaunchOptions } from './settings.js';
 import type { BrowserOptions } from './settings.js';
 import { initResourceCache } from './ResourceCache.js';
 import { ErrorHandler } from './errorHandler.js';
+import type { MetricsRecorder } from './metrics.js';
 
 export type StartWorkerOptions = BrowserOptions & {
 	/** Renderer to use instead of the built-in default. */
@@ -54,9 +55,24 @@ export async function startWorker(options: StartWorkerOptions): Promise<RenderWo
 			...settings,
 			harper: { ...settings.harper, pass: settings.harper.pass ? 'REDACTED' : '' },
 			bypass: { ...settings.bypass, token: settings.bypass.token ? 'REDACTED' : '' },
+			// headers may carry an auth token for the collector — never log their values.
+			metrics: { ...settings.metrics, headers: Object.keys(settings.metrics.headers) },
 		},
 	});
 
+	// Optional OTLP metrics: construct only when enabled AND an endpoint is set — that dynamic
+	// import is the only thing that loads the OpenTelemetry SDK, so a disabled worker pays nothing.
+	// A metrics-init failure must never stop the worker from rendering.
+	let metrics: MetricsRecorder | undefined;
+	if (settings.metrics.enabled && settings.metrics.otlpEndpoint) {
+		try {
+			const { createMetrics } = await import('./metrics.js');
+			metrics = await createMetrics(settings.metrics, { workerId: settings.harper.workerId });
+		} catch (err) {
+			logger.error({ err }, 'failed to start metrics export — continuing without metrics');
+		}
+	}
+
 	// Block job intake until the cache has scanned disk and built its in-memory index.
 	await initResourceCache(settings.resourceCache);
 
@@ -66,6 +82,7 @@ export async function startWorker(options: StartWorkerOptions): Promise<RenderWo
 		rps: settings.rps,
 		browserLaunchOptions: settings.browserLaunchOptions ?? defaultLaunchOptions(),
 		renderer,
+		metrics,
 	});
 
 	// Install signal handlers AFTER the worker exists so SIGTERM/SIGINT can drain it