Prometheus Metrics

Exposes extension metrics in Prometheus text exposition format. No external dependencies. Zero overhead when not enabled - every metric call uses optional chaining on a nullish reference, so V8 short-circuits on a single pointer check.

Setup

// src/lib/server/metrics.js
import { createMetrics } from 'svelte-adapter-uws-extensions/prometheus';

export const metrics = createMetrics({
  prefix: 'myapp_',
  mapTopic: (topic) => topic.startsWith('room:') ? 'room:*' : topic
});

Pass the metrics object to any extension via its options:

import { metrics } from './metrics.js';
import { redis } from './redis.js';
import { createPresence } from 'svelte-adapter-uws-extensions/redis/presence';
import { createPubSubBus } from 'svelte-adapter-uws-extensions/redis/pubsub';
import { createReplay } from 'svelte-adapter-uws-extensions/redis/replay';
import { createRateLimit } from 'svelte-adapter-uws-extensions/redis/ratelimit';
import { createGroup } from 'svelte-adapter-uws-extensions/redis/groups';
import { createCursor } from 'svelte-adapter-uws-extensions/redis/cursor';

export const bus = createPubSubBus(redis, { metrics });
export const presence = createPresence(redis, { metrics, key: 'id' });
export const replay = createReplay(redis, { metrics });
export const limiter = createRateLimit(redis, { points: 10, interval: 1000, metrics });
export const lobby = createGroup(redis, 'lobby', { metrics });
export const cursors = createCursor(redis, { metrics });

Mounting the endpoint

With uWebSockets.js:

app.get('/metrics', metrics.handler);

Or use metrics.serialize() to get the raw text and serve it however you like.

The recommended deployment shape is to bind /metrics behind a network barrier - a private port, an internal load balancer, or a sidecar scrape target - so the operating-system perimeter does the access control. When that is not available (same-listener mounts, scrape-from-public-network setups), use metrics.authedHandler(predicate) for application-level auth:

import { timingSafeEqual } from 'node:crypto';

const expected = Buffer.from(process.env.SCRAPE_TOKEN);

app.get('/metrics', metrics.authedHandler((res, req) => {
  const provided = req.getHeader('x-scrape-token');
  if (!provided) return false;
  const got = Buffer.from(provided);
  if (got.length !== expected.length) return false;
  return timingSafeEqual(got, expected);
}));

The predicate runs against (res, req) and serves metrics only when it returns truthy. Async predicates are awaited. Predicate exceptions are caught and treated as denial (no error info leaked back). Denials return 401 Unauthorized with a minimal text body and no metrics payload. The wrapper uses res.cork() + res.onAborted() per uWS best practice so a client hang-up during an async predicate does not write to a dead socket.

Options

Metric names must match [a-zA-Z_:][a-zA-Z0-9_:]* and label names must match [a-zA-Z_][a-zA-Z0-9_]* (no __ prefix). Invalid names throw at registration time. HELP text containing backslashes or newlines is escaped automatically.

Cardinality caps

maxBuckets and maxSeries are defense against unbounded prom-scrape growth. The defaults match mature client libraries (Go’s client_golang warns past ~100 buckets; Java’s Micrometer soft-caps at 64; per-metric labelset state past ~10k usually means the metric is no longer query-able through Grafana).

Histogram bucket cap (maxBuckets, default 32): fires once at registration. The error message names the actual length, the configured cap, and both override knobs so the caller can either narrow the bucket array or opt up explicitly.

Per-metric labelset cap (maxSeries, default 10000): the data-plane action is a no-op rather than throwing, so a high-cardinality bug cannot crash the app on metric increment. Existing labelsets continue to increment past the cap; only new labelsets are dropped. The one-shot warn points at mapTopic as the typical fix when a user-controlled dimension (raw client IP, message id, unbounded topic) is leaking into a label.

The dropped-series counter has maxSeries: Infinity so a high-cardinality drop pattern cannot make the drop counter start dropping. The data-plane cost is one Map.size >= maxSeries comparison per inc / set / dec / observe; unmeasurable on hot paths.

Cardinality control

If your topics are user-generated (e.g. room:abc123), per-topic labels will grow unbounded. Use mapTopic to collapse them:

const metrics = createMetrics({
  mapTopic: (topic) => {
    if (topic.startsWith('room:')) return 'room:*';
    if (topic.startsWith('user:')) return 'user:*';
    return topic;
  }
});

Metrics reference

Pub/sub bus

Presence

Replay buffer (Redis and Postgres)

Rate limiting

Broadcast groups

Cursor

LISTEN/NOTIFY bridge

Connection rates

import { wirePublishRateMetrics, connectionMetricsHook } from 'svelte-adapter-uws-extensions/prometheus';

export function init({ platform }) {
  wirePublishRateMetrics(platform, metrics);
}

export const close = connectionMetricsHook(metrics);

connectionMetricsHook(metrics, userClose?) is a close hook factory that records per-connection traffic stats. Pre-existing user close hooks compose by passing them as the second arg.

Cluster-wide publish rate

import { createPublishRateAggregator } from 'svelte-adapter-uws-extensions/redis/publish-rate';
import { wireClusterPublishRateMetrics } from 'svelte-adapter-uws-extensions/prometheus';

const rates = await createPublishRateAggregator(redis);
wireClusterPublishRateMetrics(rates, metrics);

Sharded pub/sub bus

Pub/sub bus state

Leader election

Distributed lock

Distributed session

Connection registry / live.push

Admission control

Replay storage

Job queue (Postgres)

Task runner (Postgres)

Redis function library

Production assertions

import { wireAssertionMetrics } from 'svelte-adapter-uws-extensions/prometheus';
wireAssertionMetrics(metrics);