Prometheus /metrics Endpoint

FrontMCP can expose process metrics (CPU, RSS, heap, event-loop lag) and every framework counter (frontmcp_skills_*_total, plus any counter emitted via createCounter()) as a Prometheus scrape endpoint on the same HTTP listener as /healthz. The endpoint is off by default — turn it on with metrics: { enabled: true }.

Quick Start

import { FrontMcp } from '@frontmcp/sdk';

@FrontMcp({
  info: { name: 'my-server', version: '1.0.0' },
  apps: [MyApp],
  metrics: { enabled: true },
})
class Server {}

Then scrape it:

curl http://localhost:3000/metrics

# HELP frontmcp_process_resident_memory_bytes Resident memory size in bytes
# TYPE frontmcp_process_resident_memory_bytes gauge
frontmcp_process_resident_memory_bytes 50331648
# HELP frontmcp_process_uptime_seconds Time since process start in seconds
# TYPE frontmcp_process_uptime_seconds gauge
frontmcp_process_uptime_seconds 42
# TYPE frontmcp_skills_bundle_pulls_total counter
frontmcp_skills_bundle_pulls_total{source="npm"} 3
...

The Content-Type is the canonical Prometheus text/plain; version=0.0.4; charset=utf-8. The Web-standard handler serves the same endpoint: FrontMcpInstance.createFetchHandler(config) (Bun, Deno, a Node fetch server) answers GET /metrics (or metrics.path) with the same body, auth and headers as the Express listener. Like the Express endpoint, it reads the counters through @frontmcp/observability, which must be installed. On Cloudflare Workers, require() cannot reach bundled modules, so frontmcp build --target cloudflare imports @frontmcp/observability in the generated worker entry and hands it to the SDK with registerOptionalModule() whenever the @FrontMcp source names metrics or observability and the package is installed, including an env-gated block that is off at build time (the build warns when the config enables them and the package is not installed). Process gauges the runtime does not implement (CPU, event-loop lag, handles) are left out of the scrape instead of failing it.

What the endpoint exposes

When enabled, every scrape returns:

Category	Examples	Source
Process gauges	`frontmcp_process_resident_memory_bytes`, `frontmcp_process_heap_bytes`, `frontmcp_process_uptime_seconds`, `frontmcp_process_cpu_seconds_total{mode="user"\|"system"}`	Built-in `ProcessStatsCollector`
Node.js gauges	`frontmcp_nodejs_eventloop_lag_seconds{quantile="mean"\|"p99"}`, `frontmcp_nodejs_active_handles`, `frontmcp_nodejs_active_requests`, `frontmcp_nodejs_open_fds` (Linux only)	`perf_hooks` + `process._getActiveHandles()`
Framework counters	`frontmcp_skills_bundle_pulls_total`, `frontmcp_skills_signature__total`, `frontmcp_skills_replay__total`, `frontmcp_skills_audit_*_total`	`@frontmcp/observability`’s in-memory counter snapshot store
Custom counters	Anything emitted via `createCounter('my_counter_total').inc()`	Same snapshot store

A gauge the runtime cannot measure is left out rather than reported as 0: a Cloudflare Worker, which has no process, serves none of the process gauges. Up to 1.9.2 a Worker listed five frontmcp_process_* gauges, all 0. createCounter() from @frontmcp/observability writes into the same store the scrape reads from — no extra wiring needed.

Configuration

@FrontMcp({
  metrics: {
    enabled: true,                       // default: false
    path: '/metrics',                    // default: '/metrics'
    format: 'prometheus',                // 'prometheus' | 'json', default: 'prometheus'
    auth: 'public',                      // 'public' | 'token' | { token: string }, default: 'public'
    tokenEnv: 'FRONTMCP_METRICS_TOKEN',  // env var to read the bearer from when auth: 'token'
    include: ['process', 'skills'],      // optional category filter
    process: {
      eventLoopLag: true,                // include event-loop lag gauge
      fdCount: true,                     // include /proc/self/fd count (Linux only)
      activeHandles: true,               // include active-handles / active-requests counts
    },
  },
})

`format: 'json'`

Returns a { counters, gauges } envelope at Content-Type application/json — useful for tooling that prefers JSON over text parsing:

{
  "counters": [
    { "name": "frontmcp_skills_bundle_pulls_total", "count": 3, "attributes": { "source": "npm" } }
  ],
  "gauges": [
    { "name": "frontmcp_process_uptime_seconds", "value": 42 }
  ]
}

`auth: 'token'`

Sets Authorization: Bearer <token> as the gate. The token is read from process.env[tokenEnv] (default env var: FRONTMCP_METRICS_TOKEN) at startup. If the env var is unset, the service constructor throws MetricsTokenNotConfiguredError — failing fast so a token-gated endpoint never silently downgrades to public:

metrics: {
  enabled: true,
  auth: 'token',
  tokenEnv: 'FRONTMCP_METRICS_TOKEN',
}

Behaviour:

Missing Authorization header → 401
Authorization: Bearer <wrong> → 403
Authorization: Bearer <correct> → 200

For local / non-secret testing, an inline { token: '...' } literal also works but is discouraged in production:

metrics: {
  enabled: true,
  auth: { token: 'dev-only' },
}

`include[]` filter

Each category maps to a counter-name prefix:

Category	Prefix matched
`process`	`frontmcp_process_`, `frontmcp_nodejs_`
`skills`	`frontmcp_skills_`
`tools`	`frontmcp_tool_`
`resources`	`frontmcp_resource_`
`http`	`frontmcp_http_`
`storage`	`frontmcp_storage_`
`auth`	`frontmcp_auth_`
`sessions`	`frontmcp_session_`

Omit include to emit every category. FrontMCP itself counts only the skills counters above: it records no request, tool-call, error or duration counters, so the other categories match the counters you create with those prefixes (createCounter('frontmcp_tool_my_calls_total')).

Path conflicts

metrics.path MUST NOT collide with MCP transport paths (/mcp, /sse, /messages). The service constructor throws MetricsPathConflictError at startup if it detects an overlap:

metrics: { enabled: true, path: '/mcp' }
// → throws MetricsPathConflictError at boot

createFetchHandler() also refuses a metrics.path equal to its MCP entry path (http.entryPath, / when unset), with the same MetricsPathConflictError, because the metrics route would otherwise answer the GET that MCP clients use to open the event stream. For the same reason it refuses a metrics.path at or under the path of a splitByApp or standalone app (<entryPath>/<appId>), such as /metrics with an app whose id is metrics.

Off-by-default rationale

The endpoint is opt-in because process metrics, framework counter names, and tool vocabularies can hint at deployment scale and feature usage (e.g. frontmcp_skills_signature_failures_total reveals a signing infra exists, frontmcp_auth_checks_total{result="denied"} correlates to attack attempts). Recommendations:

Internet-exposed deployments: use auth: 'token' or terminate the endpoint at a sidecar/ingress with a network ACL.
Cluster-local deployments: auth: 'public' matches the Prometheus / Kubernetes convention; ensure the Prometheus pod can reach the port and external traffic cannot.

How it interacts with OpenTelemetry

createCounter() from @frontmcp/observability writes to two places: the in-memory snapshot store (which this endpoint reads) AND any globally configured OTel MeterProvider (which forwards to OTLP / Prometheus exporter / Grafana Cloud). If you’ve already wired an OTel MeterProvider via metrics.setGlobalMeterProvider(), the values in the scrape match the values pushed via OTel — both paths share the same counter handles.

Adding custom counters

Use createCounter() from @frontmcp/observability. The counter is automatically included in the scrape:

import { createCounter } from '@frontmcp/observability';

const cacheHits = createCounter('my_cache_hits_total', 'Cache hits by tier');

// Later, in a tool / resource / provider:
cacheHits.inc(1, { tier: 'l1' });

// Next scrape returns:
// # TYPE my_cache_hits_total counter
// my_cache_hits_total{tier="l1"} 1

Label values should be bounded (status codes, enum members, tool names) — unbounded values (user IDs, URLs, JWTs) blow up the timeseries count.

Reference

@frontmcp/sdk exports: MetricsService, registerMetricsRoutes, MetricsPathConflictError, MetricsTokenNotConfiguredError
@frontmcp/observability exports: renderPrometheusExposition, renderJsonExposition, ProcessStatsCollector, PROMETHEUS_CONTENT_TYPE, createCounter, getMetricSnapshot
Type definitions: MetricsOptionsInterface, MetricsAuth, MetricsCategory, MetricsFormat, MetricsProcessOptionsInterface
Tracked under issue #397

Get Started

Concepts

Build

Deploy

Plugins

Adapters

Extensibility

Testing

React SDK

Guides

Prometheus /metrics Endpoint

Quick Start

What the endpoint exposes

Configuration

`format: 'json'`

`auth: 'token'`

`include[]` filter

Path conflicts

Off-by-default rationale

How it interacts with OpenTelemetry

Adding custom counters

Reference

​Quick Start

​What the endpoint exposes

​Configuration

​format: 'json'

​auth: 'token'

​include[] filter

​Path conflicts

​Off-by-default rationale

​How it interacts with OpenTelemetry

​Adding custom counters

​Reference

Quick Start

What the endpoint exposes

Configuration

`format: 'json'`

`auth: 'token'`

`include[]` filter

Path conflicts

Off-by-default rationale

How it interacts with OpenTelemetry

Adding custom counters

Reference