@frontmcp/observability 1.2.1 → 1.3.0

package/esm/index.mjs

@@ -3116,6 +3116,239 @@ init_winston_sink();
 init_pino_sink();
 init_otlp_sink();
 
+// libs/observability/src/prometheus/render.ts
+var METRIC_NAME_REGEX = /^[a-zA-Z_:][a-zA-Z0-9_:]*$/;
+var LABEL_NAME_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+var PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+function escapeLabelValue(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
+function sortedLabelString(attributes) {
+  const keys = Object.keys(attributes).filter((k) => LABEL_NAME_REGEX.test(k)).sort();
+  if (keys.length === 0) return "";
+  const pairs = keys.map((k) => `${k}="${escapeLabelValue(attributes[k] ?? "")}"`);
+  return `{${pairs.join(",")}}`;
+}
+function formatFloat(value) {
+  if (!Number.isFinite(value)) return "";
+  if (Number.isInteger(value)) return String(value);
+  return String(value);
+}
+function renderPrometheusExposition(counters, gauges = [], options = {}) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const entry of counters) {
+    if (!METRIC_NAME_REGEX.test(entry.name)) continue;
+    const valueStr = formatFloat(entry.count);
+    if (valueStr === "") continue;
+    const labels = sortedLabelString(entry.attributes ?? {});
+    const line = `${entry.name}${labels} ${valueStr}`;
+    let group = byName.get(entry.name);
+    if (!group) {
+      group = {
+        type: "counter",
+        help: options.counterHelp?.[entry.name],
+        lines: []
+      };
+      byName.set(entry.name, group);
+    }
+    group.lines.push(line);
+  }
+  for (const entry of gauges) {
+    if (!METRIC_NAME_REGEX.test(entry.name)) continue;
+    const valueStr = formatFloat(entry.value);
+    if (valueStr === "") continue;
+    const labels = sortedLabelString(entry.attributes ?? {});
+    const line = `${entry.name}${labels} ${valueStr}`;
+    let group = byName.get(entry.name);
+    if (!group) {
+      group = { type: "gauge", help: entry.help, lines: [] };
+      byName.set(entry.name, group);
+    } else if (entry.help && !group.help) {
+      group.help = entry.help;
+    }
+    group.lines.push(line);
+  }
+  if (byName.size === 0) return "";
+  const sortedNames = Array.from(byName.keys()).sort();
+  const blocks = [];
+  for (const name of sortedNames) {
+    const group = byName.get(name);
+    if (!group) continue;
+    const block = [];
+    if (group.help) {
+      block.push(`# HELP ${name} ${group.help.replace(/\n/g, " ")}`);
+    }
+    block.push(`# TYPE ${name} ${group.type}`);
+    block.push(...group.lines.slice().sort());
+    blocks.push(block.join("\n"));
+  }
+  return blocks.join("\n") + "\n";
+}
+function renderJsonExposition(counters, gauges = []) {
+  return {
+    counters: counters.filter((c) => METRIC_NAME_REGEX.test(c.name) && Number.isFinite(c.count)).map((c) => ({ name: c.name, count: c.count, attributes: { ...c.attributes ?? {} } })),
+    gauges: gauges.filter((g) => METRIC_NAME_REGEX.test(g.name) && Number.isFinite(g.value)).map((g) => ({
+      name: g.name,
+      value: g.value,
+      attributes: { ...g.attributes ?? {} },
+      ...g.help ? { help: g.help } : {}
+    }))
+  };
+}
+
+// libs/observability/src/process-stats/process-stats.collector.ts
+import { readdirSync } from "@frontmcp/utils";
+var NS_PER_SECOND = 1e9;
+var MICROS_PER_SECOND = 1e6;
+function defaultMonitorEventLoopDelay() {
+  try {
+    const { monitorEventLoopDelay } = __require("node:perf_hooks");
+    const histogram = monitorEventLoopDelay({ resolution: 10 });
+    histogram.enable();
+    return histogram;
+  } catch {
+    return void 0;
+  }
+}
+function defaultGetActiveHandles() {
+  const proc = process;
+  if (typeof proc._getActiveHandles !== "function") return void 0;
+  try {
+    return proc._getActiveHandles();
+  } catch {
+    return void 0;
+  }
+}
+function defaultGetActiveRequests() {
+  const proc = process;
+  if (typeof proc._getActiveRequests !== "function") return void 0;
+  try {
+    return proc._getActiveRequests();
+  } catch {
+    return void 0;
+  }
+}
+function defaultReadFdCount() {
+  if (process.platform !== "linux") return void 0;
+  try {
+    return readdirSync("/proc/self/fd").length;
+  } catch {
+    return void 0;
+  }
+}
+var ProcessStatsCollector = class {
+  constructor(init = {}) {
+    this.options = init.options ?? {};
+    this.cpuUsage = init.cpuUsage ?? ((prev) => process.cpuUsage(prev));
+    this.memoryUsage = init.memoryUsage ?? (() => process.memoryUsage());
+    this.uptime = init.uptime ?? (() => process.uptime());
+    this.getActiveHandles = init.getActiveHandles ?? defaultGetActiveHandles;
+    this.getActiveRequests = init.getActiveRequests ?? defaultGetActiveRequests;
+    this.readFdCount = init.readFdCount ?? defaultReadFdCount;
+    this.cpuStart = this.cpuUsage();
+    if (this.options.eventLoopLag !== false) {
+      this.histogram = init.monitorEventLoopDelay ? init.monitorEventLoopDelay() : defaultMonitorEventLoopDelay();
+    }
+  }
+  collect() {
+    const entries = [];
+    const cpu = this.cpuUsage(this.cpuStart);
+    entries.push({
+      name: "frontmcp_process_cpu_seconds_total",
+      value: cpu.user / MICROS_PER_SECOND,
+      attributes: { mode: "user" },
+      help: "CPU time consumed since collector start, by mode (seconds)"
+    });
+    entries.push({
+      name: "frontmcp_process_cpu_seconds_total",
+      value: cpu.system / MICROS_PER_SECOND,
+      attributes: { mode: "system" }
+    });
+    const mem = this.memoryUsage();
+    entries.push({
+      name: "frontmcp_process_resident_memory_bytes",
+      value: mem.rss,
+      help: "Resident memory size in bytes"
+    });
+    entries.push({
+      name: "frontmcp_process_heap_bytes",
+      value: mem.heapTotal,
+      help: "Total V8 heap size in bytes"
+    });
+    entries.push({
+      name: "frontmcp_process_heap_used_bytes",
+      value: mem.heapUsed,
+      help: "Used V8 heap size in bytes"
+    });
+    entries.push({
+      name: "frontmcp_process_external_bytes",
+      value: mem.external,
+      help: "Memory used by C++ objects bound to JS in bytes"
+    });
+    entries.push({
+      name: "frontmcp_process_uptime_seconds",
+      value: this.uptime(),
+      help: "Time since process start in seconds"
+    });
+    if (this.options.eventLoopLag !== false && this.histogram) {
+      const meanSeconds = this.histogram.mean / NS_PER_SECOND;
+      const p99Seconds = this.histogram.percentile(99) / NS_PER_SECOND;
+      if (Number.isFinite(meanSeconds)) {
+        entries.push({
+          name: "frontmcp_nodejs_eventloop_lag_seconds",
+          value: meanSeconds,
+          attributes: { quantile: "mean" },
+          help: "Event-loop lag in seconds, sampled at 10ms resolution since the last scrape"
+        });
+      }
+      if (Number.isFinite(p99Seconds)) {
+        entries.push({
+          name: "frontmcp_nodejs_eventloop_lag_seconds",
+          value: p99Seconds,
+          attributes: { quantile: "p99" }
+        });
+      }
+      this.histogram.reset();
+    }
+    if (this.options.activeHandles !== false) {
+      const handles = this.getActiveHandles?.();
+      if (handles !== void 0) {
+        entries.push({
+          name: "frontmcp_nodejs_active_handles",
+          value: handles.length,
+          help: "Currently active libuv handles (sockets, timers, etc.)"
+        });
+      }
+      const requests = this.getActiveRequests?.();
+      if (requests !== void 0) {
+        entries.push({
+          name: "frontmcp_nodejs_active_requests",
+          value: requests.length,
+          help: "Currently active libuv requests (file I/O, DNS, etc.)"
+        });
+      }
+    }
+    if (this.options.fdCount !== false) {
+      const fdCount = this.readFdCount();
+      if (typeof fdCount === "number") {
+        entries.push({
+          name: "frontmcp_nodejs_open_fds",
+          value: fdCount,
+          help: "Number of open file descriptors (Linux only)"
+        });
+      }
+    }
+    return entries;
+  }
+  /**
+   * Release the perf_hooks histogram listener. Call when the collector is
+   * no longer used (e.g., when reconfiguring the server).
+   */
+  close() {
+    this.histogram?.disable?.();
+  }
+};
+
 // libs/observability/src/testing/index.ts
 import {
   BasicTracerProvider,
@@ -3178,8 +3411,10 @@ export {
   OTEL_TRACER,
   ObservabilityPlugin,
   OtlpSink,
+  PROMETHEUS_CONTENT_TYPE,
   PinoSink,
   PrettySpanExporter,
+  ProcessStatsCollector,
   REQUEST_LOG_COLLECTOR,
   RequestLogCollector,
   RpcAttributes,
@@ -3212,6 +3447,8 @@ export {
   otelToFrontmcpContext,
   recordHookEvent,
   redactFields,
+  renderJsonExposition,
+  renderPrometheusExposition,
   reportStartup,
   resetCounterCacheForTesting,
   resetMetricSnapshot,

package/esm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/observability",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "OpenTelemetry instrumentation, structured JSON logging, and request log objects for FrontMCP",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -51,8 +51,8 @@
     "@opentelemetry/api": "^1.9.0"
   },
   "peerDependencies": {
-    "@frontmcp/sdk": "1.2.1",
-    "@frontmcp/utils": "1.2.1",
+    "@frontmcp/sdk": "1.3.0",
+    "@frontmcp/utils": "1.3.0",
     "@opentelemetry/sdk-trace-base": "^1.25.0",
     "@opentelemetry/sdk-node": "^0.52.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.52.0",

package/index.d.ts

@@ -6,6 +6,9 @@ export { StructuredLogTransport, LOG_LEVEL_TO_OTEL_SEVERITY, StdoutSink, Console
 export type { StructuredLogEntry, StructuredLogError, StructuredLogTransportOptions, LogSink, SinkConfig, StdoutSinkConfig, ConsoleSinkConfig, WinstonSinkConfig, PinoSinkConfig, CallbackSinkConfig, OtlpSinkConfig, OtlpSinkOptions, WinstonLike, PinoLike, ContextAccessor, ContextSnapshot, } from './logging';
 export { TelemetryAccessor, TelemetrySpan, TelemetryFactory, TELEMETRY_ACCESSOR, TELEMETRY_FACTORY, createCounter, getMetricSnapshot, getCounterTotal, resetMetricSnapshot, resetTelemetrySnapshotForTesting, resetCounterCacheForTesting, normalizeBundleSource, normalizeErrorReason, KNOWN_BUNDLE_SOURCES, KNOWN_ERROR_REASONS, } from './telemetry';
 export type { TelemetryCounter, CounterSnapshotEntry, KnownBundleSource, KnownErrorReason } from './telemetry';
+export { PROMETHEUS_CONTENT_TYPE, renderJsonExposition, renderPrometheusExposition } from './prometheus';
+export type { GaugeSnapshotEntry, RenderOptions } from './prometheus';
+export { ProcessStatsCollector } from './process-stats';
 export { createTestTracer, getFinishedSpans, assertSpanExists, assertSpanAttribute, findSpan, findSpansByAttribute, } from './testing';
 export type { TestTracer } from './testing';
 export { RequestLogCollector, REQUEST_LOG_COLLECTOR } from './request-log';

package/index.js

@@ -330,8 +330,10 @@ __export(index_exports, {
   OTEL_TRACER: () => OTEL_TRACER,
   ObservabilityPlugin: () => ObservabilityPlugin,
   OtlpSink: () => OtlpSink,
+  PROMETHEUS_CONTENT_TYPE: () => PROMETHEUS_CONTENT_TYPE,
   PinoSink: () => PinoSink,
   PrettySpanExporter: () => PrettySpanExporter,
+  ProcessStatsCollector: () => ProcessStatsCollector,
   REQUEST_LOG_COLLECTOR: () => REQUEST_LOG_COLLECTOR,
   RequestLogCollector: () => RequestLogCollector,
   RpcAttributes: () => RpcAttributes,
@@ -364,6 +366,8 @@ __export(index_exports, {
   otelToFrontmcpContext: () => otelToFrontmcpContext,
   recordHookEvent: () => recordHookEvent,
   redactFields: () => redactFields,
+  renderJsonExposition: () => renderJsonExposition,
+  renderPrometheusExposition: () => renderPrometheusExposition,
   reportStartup: () => reportStartup,
   resetCounterCacheForTesting: () => resetCounterCacheForTesting,
   resetMetricSnapshot: () => resetMetricSnapshot,
@@ -3155,6 +3159,239 @@ init_winston_sink();
 init_pino_sink();
 init_otlp_sink();
 
+// libs/observability/src/prometheus/render.ts
+var METRIC_NAME_REGEX = /^[a-zA-Z_:][a-zA-Z0-9_:]*$/;
+var LABEL_NAME_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+var PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+function escapeLabelValue(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
+function sortedLabelString(attributes) {
+  const keys = Object.keys(attributes).filter((k) => LABEL_NAME_REGEX.test(k)).sort();
+  if (keys.length === 0) return "";
+  const pairs = keys.map((k) => `${k}="${escapeLabelValue(attributes[k] ?? "")}"`);
+  return `{${pairs.join(",")}}`;
+}
+function formatFloat(value) {
+  if (!Number.isFinite(value)) return "";
+  if (Number.isInteger(value)) return String(value);
+  return String(value);
+}
+function renderPrometheusExposition(counters, gauges = [], options = {}) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const entry of counters) {
+    if (!METRIC_NAME_REGEX.test(entry.name)) continue;
+    const valueStr = formatFloat(entry.count);
+    if (valueStr === "") continue;
+    const labels = sortedLabelString(entry.attributes ?? {});
+    const line = `${entry.name}${labels} ${valueStr}`;
+    let group = byName.get(entry.name);
+    if (!group) {
+      group = {
+        type: "counter",
+        help: options.counterHelp?.[entry.name],
+        lines: []
+      };
+      byName.set(entry.name, group);
+    }
+    group.lines.push(line);
+  }
+  for (const entry of gauges) {
+    if (!METRIC_NAME_REGEX.test(entry.name)) continue;
+    const valueStr = formatFloat(entry.value);
+    if (valueStr === "") continue;
+    const labels = sortedLabelString(entry.attributes ?? {});
+    const line = `${entry.name}${labels} ${valueStr}`;
+    let group = byName.get(entry.name);
+    if (!group) {
+      group = { type: "gauge", help: entry.help, lines: [] };
+      byName.set(entry.name, group);
+    } else if (entry.help && !group.help) {
+      group.help = entry.help;
+    }
+    group.lines.push(line);
+  }
+  if (byName.size === 0) return "";
+  const sortedNames = Array.from(byName.keys()).sort();
+  const blocks = [];
+  for (const name of sortedNames) {
+    const group = byName.get(name);
+    if (!group) continue;
+    const block = [];
+    if (group.help) {
+      block.push(`# HELP ${name} ${group.help.replace(/\n/g, " ")}`);
+    }
+    block.push(`# TYPE ${name} ${group.type}`);
+    block.push(...group.lines.slice().sort());
+    blocks.push(block.join("\n"));
+  }
+  return blocks.join("\n") + "\n";
+}
+function renderJsonExposition(counters, gauges = []) {
+  return {
+    counters: counters.filter((c) => METRIC_NAME_REGEX.test(c.name) && Number.isFinite(c.count)).map((c) => ({ name: c.name, count: c.count, attributes: { ...c.attributes ?? {} } })),
+    gauges: gauges.filter((g) => METRIC_NAME_REGEX.test(g.name) && Number.isFinite(g.value)).map((g) => ({
+      name: g.name,
+      value: g.value,
+      attributes: { ...g.attributes ?? {} },
+      ...g.help ? { help: g.help } : {}
+    }))
+  };
+}
+
+// libs/observability/src/process-stats/process-stats.collector.ts
+var import_utils2 = require("@frontmcp/utils");
+var NS_PER_SECOND = 1e9;
+var MICROS_PER_SECOND = 1e6;
+function defaultMonitorEventLoopDelay() {
+  try {
+    const { monitorEventLoopDelay } = require("node:perf_hooks");
+    const histogram = monitorEventLoopDelay({ resolution: 10 });
+    histogram.enable();
+    return histogram;
+  } catch {
+    return void 0;
+  }
+}
+function defaultGetActiveHandles() {
+  const proc = process;
+  if (typeof proc._getActiveHandles !== "function") return void 0;
+  try {
+    return proc._getActiveHandles();
+  } catch {
+    return void 0;
+  }
+}
+function defaultGetActiveRequests() {
+  const proc = process;
+  if (typeof proc._getActiveRequests !== "function") return void 0;
+  try {
+    return proc._getActiveRequests();
+  } catch {
+    return void 0;
+  }
+}
+function defaultReadFdCount() {
+  if (process.platform !== "linux") return void 0;
+  try {
+    return (0, import_utils2.readdirSync)("/proc/self/fd").length;
+  } catch {
+    return void 0;
+  }
+}
+var ProcessStatsCollector = class {
+  constructor(init = {}) {
+    this.options = init.options ?? {};
+    this.cpuUsage = init.cpuUsage ?? ((prev) => process.cpuUsage(prev));
+    this.memoryUsage = init.memoryUsage ?? (() => process.memoryUsage());
+    this.uptime = init.uptime ?? (() => process.uptime());
+    this.getActiveHandles = init.getActiveHandles ?? defaultGetActiveHandles;
+    this.getActiveRequests = init.getActiveRequests ?? defaultGetActiveRequests;
+    this.readFdCount = init.readFdCount ?? defaultReadFdCount;
+    this.cpuStart = this.cpuUsage();
+    if (this.options.eventLoopLag !== false) {
+      this.histogram = init.monitorEventLoopDelay ? init.monitorEventLoopDelay() : defaultMonitorEventLoopDelay();
+    }
+  }
+  collect() {
+    const entries = [];
+    const cpu = this.cpuUsage(this.cpuStart);
+    entries.push({
+      name: "frontmcp_process_cpu_seconds_total",
+      value: cpu.user / MICROS_PER_SECOND,
+      attributes: { mode: "user" },
+      help: "CPU time consumed since collector start, by mode (seconds)"
+    });
+    entries.push({
+      name: "frontmcp_process_cpu_seconds_total",
+      value: cpu.system / MICROS_PER_SECOND,
+      attributes: { mode: "system" }
+    });
+    const mem = this.memoryUsage();
+    entries.push({
+      name: "frontmcp_process_resident_memory_bytes",
+      value: mem.rss,
+      help: "Resident memory size in bytes"
+    });
+    entries.push({
+      name: "frontmcp_process_heap_bytes",
+      value: mem.heapTotal,
+      help: "Total V8 heap size in bytes"
+    });
+    entries.push({
+      name: "frontmcp_process_heap_used_bytes",
+      value: mem.heapUsed,
+      help: "Used V8 heap size in bytes"
+    });
+    entries.push({
+      name: "frontmcp_process_external_bytes",
+      value: mem.external,
+      help: "Memory used by C++ objects bound to JS in bytes"
+    });
+    entries.push({
+      name: "frontmcp_process_uptime_seconds",
+      value: this.uptime(),
+      help: "Time since process start in seconds"
+    });
+    if (this.options.eventLoopLag !== false && this.histogram) {
+      const meanSeconds = this.histogram.mean / NS_PER_SECOND;
+      const p99Seconds = this.histogram.percentile(99) / NS_PER_SECOND;
+      if (Number.isFinite(meanSeconds)) {
+        entries.push({
+          name: "frontmcp_nodejs_eventloop_lag_seconds",
+          value: meanSeconds,
+          attributes: { quantile: "mean" },
+          help: "Event-loop lag in seconds, sampled at 10ms resolution since the last scrape"
+        });
+      }
+      if (Number.isFinite(p99Seconds)) {
+        entries.push({
+          name: "frontmcp_nodejs_eventloop_lag_seconds",
+          value: p99Seconds,
+          attributes: { quantile: "p99" }
+        });
+      }
+      this.histogram.reset();
+    }
+    if (this.options.activeHandles !== false) {
+      const handles = this.getActiveHandles?.();
+      if (handles !== void 0) {
+        entries.push({
+          name: "frontmcp_nodejs_active_handles",
+          value: handles.length,
+          help: "Currently active libuv handles (sockets, timers, etc.)"
+        });
+      }
+      const requests = this.getActiveRequests?.();
+      if (requests !== void 0) {
+        entries.push({
+          name: "frontmcp_nodejs_active_requests",
+          value: requests.length,
+          help: "Currently active libuv requests (file I/O, DNS, etc.)"
+        });
+      }
+    }
+    if (this.options.fdCount !== false) {
+      const fdCount = this.readFdCount();
+      if (typeof fdCount === "number") {
+        entries.push({
+          name: "frontmcp_nodejs_open_fds",
+          value: fdCount,
+          help: "Number of open file descriptors (Linux only)"
+        });
+      }
+    }
+    return entries;
+  }
+  /**
+   * Release the perf_hooks histogram listener. Call when the collector is
+   * no longer used (e.g., when reconfiguring the server).
+   */
+  close() {
+    this.histogram?.disable?.();
+  }
+};
+
 // libs/observability/src/testing/index.ts
 var import_sdk_trace_base = require("@opentelemetry/sdk-trace-base");
 function createTestTracer(name = "test") {
@@ -3214,8 +3451,10 @@ function findSpansByAttribute(spans, key, value) {
   OTEL_TRACER,
   ObservabilityPlugin,
   OtlpSink,
+  PROMETHEUS_CONTENT_TYPE,
   PinoSink,
   PrettySpanExporter,
+  ProcessStatsCollector,
   REQUEST_LOG_COLLECTOR,
   RequestLogCollector,
   RpcAttributes,
@@ -3248,6 +3487,8 @@ function findSpansByAttribute(spans, key, value) {
   otelToFrontmcpContext,
   recordHookEvent,
   redactFields,
+  renderJsonExposition,
+  renderPrometheusExposition,
   reportStartup,
   resetCounterCacheForTesting,
   resetMetricSnapshot,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/observability",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "OpenTelemetry instrumentation, structured JSON logging, and request log objects for FrontMCP",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -51,8 +51,8 @@
     "@opentelemetry/api": "^1.9.0"
   },
   "peerDependencies": {
-    "@frontmcp/sdk": "1.2.1",
-    "@frontmcp/utils": "1.2.1",
+    "@frontmcp/sdk": "1.3.0",
+    "@frontmcp/utils": "1.3.0",
     "@opentelemetry/sdk-trace-base": "^1.25.0",
     "@opentelemetry/sdk-node": "^0.52.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.52.0",

package/process-stats/index.d.ts

@@ -0,0 +1 @@
+export { ProcessStatsCollector } from './process-stats.collector';

package/process-stats/process-stats.collector.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Process-stats collector (issue #397).
+ *
+ * Emits per-scrape Node.js process metrics in `GaugeSnapshotEntry` shape so
+ * the Prometheus serializer can pass them straight through. Pure read of
+ * `process.*` and `perf_hooks.monitorEventLoopDelay()` — no I/O beyond the
+ * single Linux-only `/proc/self/fd` directory probe (wrapped in try/catch
+ * so non-Linux platforms silently skip that gauge).
+ *
+ * Design choices:
+ *   - CPU is emitted as a monotonic counter-shaped gauge built from
+ *     `process.cpuUsage()` deltas — operators graph `rate()` of this.
+ *   - Event-loop lag uses `perf_hooks.monitorEventLoopDelay({ resolution: 10 })`
+ *     started at construction; `collect()` reads mean + p99 and calls
+ *     `reset()` so each scrape sees a fresh window.
+ *   - `process._getActiveHandles()` / `_getActiveRequests()` are
+ *     undocumented but stable since Node 14; guarded behind feature
+ *     detection so they no-op on edge runtimes.
+ *   - All probes are individually toggleable via `MetricsProcessOptions`.
+ */
+import type { GaugeSnapshotEntry } from '../prometheus/render';
+interface MetricsProcessOptions {
+    eventLoopLag?: boolean;
+    fdCount?: boolean;
+    activeHandles?: boolean;
+}
+interface ELDHistogram {
+    mean: number;
+    percentile(p: number): number;
+    reset(): void;
+    disable?(): void;
+}
+/**
+ * Optional dependency injection points used by tests; production callers
+ * never pass these.
+ */
+interface ProcessStatsCollectorOptions {
+    options?: MetricsProcessOptions;
+    cpuUsage?: (prev?: NodeJS.CpuUsage) => NodeJS.CpuUsage;
+    memoryUsage?: () => NodeJS.MemoryUsage;
+    uptime?: () => number;
+    monitorEventLoopDelay?: () => ELDHistogram | undefined;
+    getActiveHandles?: () => unknown[] | undefined;
+    getActiveRequests?: () => unknown[] | undefined;
+    readFdCount?: () => number | undefined;
+}
+export declare class ProcessStatsCollector {
+    private readonly options;
+    private readonly cpuUsage;
+    private readonly memoryUsage;
+    private readonly uptime;
+    private readonly histogram?;
+    private readonly getActiveHandles?;
+    private readonly getActiveRequests?;
+    private readonly readFdCount;
+    private cpuStart;
+    constructor(init?: ProcessStatsCollectorOptions);
+    collect(): GaugeSnapshotEntry[];
+    /**
+     * Release the perf_hooks histogram listener. Call when the collector is
+     * no longer used (e.g., when reconfiguring the server).
+     */
+    close(): void;
+}
+export {};

package/prometheus/index.d.ts

@@ -0,0 +1,2 @@
+export { PROMETHEUS_CONTENT_TYPE, renderJsonExposition, renderPrometheusExposition } from './render';
+export type { GaugeSnapshotEntry, RenderOptions } from './render';

package/prometheus/render.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Prometheus text-exposition serializer (zero-dep).
+ *
+ * Implements the Prometheus 0.0.4 text format documented at
+ * https://prometheus.io/docs/instrumenting/exposition_formats/#text-based-format
+ * without pulling in `prom-client` — keeps `@frontmcp/observability`'s
+ * runtime footprint to `@opentelemetry/api` only (issue #397).
+ *
+ * Counter snapshot entries come from
+ * `@frontmcp/observability`'s in-memory store (`getMetricSnapshot()`); gauge
+ * entries come from the `ProcessStatsCollector` introduced alongside this
+ * serializer.
+ */
+import type { CounterSnapshotEntry } from '../telemetry/telemetry.counters';
+/**
+ * A single gauge sample at a point in time. Values are emitted unchanged
+ * (no resampling, no rate calculation).
+ */
+export interface GaugeSnapshotEntry {
+    /** Metric name (must match `/^[a-zA-Z_:][a-zA-Z0-9_:]*$/`). */
+    name: string;
+    /** Sample value. NaN / non-finite values are dropped. */
+    value: number;
+    /** Optional bounded-cardinality labels. */
+    attributes?: Record<string, string>;
+    /** Optional `# HELP` line. */
+    help?: string;
+}
+/**
+ * Optional rendering knobs.
+ */
+export interface RenderOptions {
+    /** Map of counter-name → `# HELP` text. Counter names not in the map omit the HELP line. */
+    counterHelp?: Record<string, string>;
+}
+/**
+ * Content-Type emitted alongside the text format (canonical Prometheus
+ * 0.0.4 value — pinned so consumers can match exactly).
+ */
+export declare const PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+/**
+ * Render counter + gauge snapshots as Prometheus 0.0.4 text exposition.
+ *
+ * - Groups entries by metric name so `# HELP` / `# TYPE` lines emit once
+ *   per metric.
+ * - Drops entries whose metric name fails Prometheus naming validation.
+ * - Sorts metric names alphabetically so output is byte-deterministic.
+ * - Empty input → empty string.
+ */
+export declare function renderPrometheusExposition(counters: readonly CounterSnapshotEntry[], gauges?: readonly GaugeSnapshotEntry[], options?: RenderOptions): string;
+/**
+ * Render counter + gauge snapshots as a JSON envelope — useful when
+ * a consumer prefers JSON over Prometheus text parsing.
+ */
+export declare function renderJsonExposition(counters: readonly CounterSnapshotEntry[], gauges?: readonly GaugeSnapshotEntry[]): {
+    counters: CounterSnapshotEntry[];
+    gauges: GaugeSnapshotEntry[];
+};