prom-client-Adapter

Wenn deine App prom-client (die De-facto-Node-/Prometheus- Bibliothek) schon für ihre Nicht-Actor-Metriken nutzt, lässt der PromClientAdapter die Framework-Metriken in derselben prom-client-Registry leben — ein /metrics-Endpunkt, alle Metriken zusammen.

import { Registry } from 'prom-client';
import { ActorSystem, MetricsExtensionId, PromClientAdapter } from 'actor-ts';

const promRegistry = new Registry();
// ... registriere deine bestehenden prom-client-Metriken ...

const system = ActorSystem.create('my-app');
const metrics = system.extension(MetricsExtensionId);

// Spiegle Framework-Metriken in die prom-client-Registry:
const adapter = new PromClientAdapter({
  source: metrics.registry,
  target: promRegistry,
});

adapter.start();

// Jetzt enthält der kombinierte Export von prom-client auch Framework-Metriken:
get(async () => ({
  status: 200,
  body: await promRegistry.metrics(),
  contentType: promRegistry.contentType,
}));

Der Adapter spiegelt Framework-Metriken in einem periodischen Intervall (konfigurierbar) in die prom-client-Registry. Beide Registries arbeiten normal; der Adapter synchronisiert Werte zwischen ihnen.

Wann nutzen

Zwei Hauptgründe:

1. Bestehende prom-client-Nutzung — dein Code emittiert Metriken schon via prom-client; du willst keine zwei Registries pflegen.
2. Ein Scrape-Endpunkt — deine Operatoren erwarten eine einzelne /metrics-URL, die alle deine Metriken kombiniert.

Wenn du prom-client noch nicht nutzt, bevorzuge den nativen Prometheus-Exporter des Frameworks — keine zusätzliche Dependency.

Konfiguration

interface PromClientAdapterSettings {
  source:        MetricsRegistry;     // die Registry des Frameworks
  target:        Registry;             // die von prom-client
  syncIntervalMs?: number;             // Default 5000
  prefix?:        string;              // optionaler Namens-Präfix
}

syncIntervalMs ist die Kadenz, in der Framework-Werte in die prom-client-Registry kopiert werden. Für die meisten Scrape- Setups (alle 15-30 s) ist eine 5-Sekunden-Sync mehr als genug.

prefix lässt dich Framework-Metriken namespacen:

new PromClientAdapter({
  source: metrics.registry,
  target: promRegistry,
  prefix: 'actorts_',
});

// → actorts_http_requests_total, actorts_sessions_active, ...

Peer-Dependency

npm install prom-client
# oder: bun add prom-client

prom-client ist Peer — nur benötigt, wenn du diesen Adapter nutzt.

Wo es weitergeht

• Observability — Überblick — das größere Bild.
• Core-Metriken — die Metrik-Primitive des Frameworks, die gespiegelt werden.
• Prometheus-Exporter — die framework-native Alternative, wenn du prom-client nicht brauchst.
• OTel-Adapter — für OpenTelemetry-basierte Pipelines.