Core-Metriken
Die Metrics-Extension stellt drei klassische Primitive bereit:
| Typ | Richtung | Wann |
|---|---|---|
| Counter | Monoton steigend | Gesamtevents, Gesamtwerte über die Zeit. |
| Gauge | Setzbar / inc / dec | Werte zu einem Zeitpunkt, die rauf und runter gehen. |
| Histogram | Verteilung von Beobachtungen | Latenz, Payload-Größe. |
import { ActorSystem } from 'actor-ts';import { MetricsExtensionId } from 'actor-ts/metrics';
const metrics = system.extension(MetricsExtensionId).enable();
const requests = metrics.counter('http_requests_total', { route: '/orders' });const active = metrics.gauge('sessions_active');const latency = metrics.histogram('http_request_duration_ms', { route: '/orders' });
requests.inc();active.set(123);latency.observe(42);Bis enable() gerufen wird, ist die Registry eine Noop-Implementierung —
die Instrumentierung des Frameworks zeichnet also nichts auf. Genau eine
Sache schaltet sie für dich ein:
DevTools aktiviert die Registry,
solange es attached ist — die Übersicht braucht diese Zähler — und ruft
beim Detach disable(). Eine Registry, die du selbst eingeschaltet
hast, wird nie hinter deinem Rücken abgeschaltet.
Counter
Abschnitt betitelt „Counter“const c = metrics.counter('events_total', { source: 'web' });
c.inc(); // → +1c.inc(3); // → +3c.value; // → 4Monoton — geht nur nach oben. Negative Inkremente werfen einen Fehler. Reset beim Prozess-Neustart.
Für „Dinge, die du zählst”:
- Empfangene Requests insgesamt.
- Ausgelöste Fehler insgesamt.
- Cache-Hits / -Misses insgesamt.
Für Dinge, die runtergehen (aktive Sessions sinken), nutze einen Gauge, keinen Counter.
const g = metrics.gauge('sessions_active');
g.set(100); // → 100g.inc(); // → 101g.dec(5); // → 96g.value; // → 96Setzbar + bidirektional. Repräsentiert einen Wert zu einem Zeitpunkt.
Für „Dinge, die du gerade misst”:
- Aktive Sessions / Verbindungen.
- Mailbox-Tiefe.
- Queue-Größe.
- Verfügbarer Speicher.
Histogramme
Abschnitt betitelt „Histogramme“const h = metrics.histogram('http_request_duration_ms', { route: '/orders' }, { buckets: [10, 25, 50, 100, 250, 500, 1000, 2500, 5000],});
h.observe(42);h.observe(118);h.observe(7);Ein Histogram zählt, wie viele Beobachtungen in jeden Bucket fielen. Zur Export-Zeit siehst du:
http_request_duration_ms_bucket{route="/orders", le="10"} 1http_request_duration_ms_bucket{route="/orders", le="25"} 1http_request_duration_ms_bucket{route="/orders", le="50"} 2http_request_duration_ms_bucket{route="/orders", le="100"} 2http_request_duration_ms_bucket{route="/orders", le="250"} 3http_request_duration_ms_bucket{route="/orders", le="+Inf"} 3http_request_duration_ms_count{route="/orders"} 3http_request_duration_ms_sum{route="/orders"} 167Prometheus berechnet Perzentile (p50, p95, p99) zur
Query-Zeit aus diesen Buckets.
Buckets wählen:
- Wähle Buckets, die dein SLO abbilden. Für ein
HTTP-Latenz-Histogram mit 200 ms p95-Ziel inkludiere
100, 200, 500. - Zweier- oder Zehnerpotenzen sind übliche Defaults — neige zu weniger Buckets im Noise-Floor und mehr rund um dein Ziel.
- Default-Buckets (genutzt, wenn du keine spezifizierst):
[0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]— Sekundenskala. Überschreibe für ms-Skala.
Operationen timen
Abschnitt betitelt „Operationen timen“Es gibt kein eigenes Timer-Primitiv — miss eine Operation, indem du ihre verstrichene Dauer in ein Histogram beobachtest:
const timer = metrics.histogram('db_query_duration_ms', { table: 'users' });
const start = performance.now();await runQuery();timer.observe(performance.now() - start);performance.now() ist auf Bun, Node und Deno verfügbar. Wähle
Buckets, die zur beobachteten Einheit passen — hier Millisekunden.
metrics.counter('events_total', { source: 'web', env: 'prod' });Labels machen aus einer Metrik viele Zeitreihen. Zur Export-Zeit ist jede eindeutige Label-Kombination eine separate Serie:
events_total{source="web", env="prod"} 1234events_total{source="web", env="staging"} 56events_total{source="batch", env="prod"} 89In Prometheus / Grafana lesbar als Filter oder Group-by-Achsen.
Namen und Label-Keys sind Konstanten
Abschnitt betitelt „Namen und Label-Keys sind Konstanten“In einen Label-Wert gehören Daten. In einen Metrik-Namen und einen Label-Key nicht:
// ✗ INJECTION — TU DAS NICHTmetrics.counter(`http_requests_${tenantFromHeader}_total`).inc();metrics.counter('http_requests_total', { [headerFromRequest]: 'yes' }).inc();Das Exposition-Format ist zeilenorientiert, und nur die Wert-Hälfte von
key="value" wird gequotet und escaped. Ein Name und ein Key landen roh
darin, weil das Format nichts anbietet, womit man sie escapen könnte. Eine
Tenant-ID von x_total 1\nnode_up{job="prod"} 0\n# erzeugt also keine
seltsam benannte Serie — sie beendet die aktuelle und schreibt eine
weitere. Wer das scrapet, kann das gefälschte node_up nicht von einem
echten unterscheiden, und ein Alert auf node_up == 0 feuert nie wieder.
Die Registry weist deshalb beides schon bei der Registrierung zurück, damit der Fehler als Stacktrace an der verursachenden Stelle auftaucht statt Stunden später als korrupter Scrape:
- ein Metrik-Name muss
[a-zA-Z_:][a-zA-Z0-9_:]*erfüllen - ein Label-Key muss
[a-zA-Z_][a-zA-Z0-9_]*erfüllen — kein Doppelpunkt - ein Label-Key darf nicht mit
__beginnen
Alles andere wirft.
Die dritte Regel ist dieselbe Fälschung eine Schicht weiter. Prometheus
reserviert __-präfigierte Label-Namen für sich selbst und verwirft sie
nach dem Relabeling — aber __name__ ist der Serienname, und ein
Scrape-Job mit honor_labels: true behält dafür den Wert des Targets.
Ein vollkommen wohlgeformtes hits_total{__name__="forged_series"} 1
lässt also den Exporter ehrlich aussehen und wird vom Server unter
forged_series abgelegt. client_golang und client_python weisen das
Präfix an derselben Stelle zurück. Reserviert ist nur die Key-Seite:
__ in einem Label-Wert bleibt unangetastet — deshalb ist
__overflow__, die Overflow-Markierung der Kardinalitätsgrenze, ein Wert
und kein Name.
Die Aufschlüsselung pro Tenant oder pro Route gehört in einen
Label-Wert, an der Quelle beschränkt (siehe bucketize weiter
unten):
// ✓ — konstanter Name, konstanter Key, der variable Teil im Wertmetrics.counter('http_requests_total', { tenant: tenantLabel }).inc();Beide Grammatiken sind exportiert — PROMETHEUS_METRIC_NAME_PATTERN und
PROMETHEUS_LABEL_NAME_PATTERN aus actor-ts/metrics —, sodass Code,
der einen Namen oder einen Key aus etwas anderem als einem Literal
zusammensetzt, dieselbe Frage stellen kann, die die Registry gleich
stellen wird, und „diese Metrik würde abgelehnt“ an der eigenen Grenze
melden kann, statt mehrere Frames tiefer einen Throw zu fangen. Es sind
dieselben Objekte, die die Registry konsultiert, und genau sie schuldet
eine eigene MetricsRegistry dem Renderer: siehe
Der Renderer vertraut seiner Eingabe.
Kardinalitätsdisziplin
Abschnitt betitelt „Kardinalitätsdisziplin“// ✗ HOCH-KARDINAL — TU DAS NICHTmetrics.counter('events_total', { requestId: req.id, // unique pro Request userId: req.user.id, // unique pro User});Jede eindeutige Label-Kombination erzeugt eine Serie. Unbeschränkte Labels (Request-ID, User-ID, Zeitstempel) produzieren unbeschränkte Serien — dein Monitoring-System geht der Speicher aus.
Nur beschränkte Labels:
- Route-Namen (
/orders,/users/:id). - Environment / Region.
- Status-Codes / Arten (ein paar Dutzend Werte).
- Pod-Namen, wenn die Pod-Anzahl beschränkt ist.
Ziel: < 100 Serien pro Metrik. Darüber Alarm schlagen.
bucketize — den Wert an der Quelle beschränken
Abschnitt betitelt „bucketize — den Wert an der Quelle beschränken“Wenn ein Label-Wert von außen kommt — ein URL-Pfad, ein Header, eine ID — bilde ihn auf eine feste Allow-List ab, bevor er die Registry erreicht:
import { bucketize } from 'actor-ts/metrics';
const ALLOWED_ROUTES = ['/orders', '/users/:id', '/health'] as const;
metrics.counter('http_requests_total', { route: bucketize(routeTemplateOf(request), ALLOWED_ROUTES),}).inc();bucketize(value, allowed) gibt value zurück, wenn es in
allowed steht, sonst 'other' — die Familie kann also nie mehr
als allowed.length + 1 Serien halten, egal was ein Angreifer
schickt.
Die Kardinalitätsgrenze
Abschnitt betitelt „Die Kardinalitätsgrenze“bucketize ist die eigentliche Lösung; die Grenze in der Registry
ist der Auffangnetz für die Labels, die niemand beschränkt hat.
Eine Familie hört auf, neue Serien anzulegen, sobald sie
maxSeriesPerFamily davon hält (Default 10 000), und faltet
alles darüber in eine einzige Overflow-Serie:
http_requests_total{route="/orders"} 1234http_requests_total{route="/health"} 56http_requests_total{route="__overflow__"} 8_912_004Die erste Familie, die die Grenze erreicht, loggt eine Warnung mit
Familienname und dem übergelaufenen Tupel — eine Warnung pro
Familie, nicht pro Aufruf. Der Marker steckt im Label-Wert,
nicht in einem Label-Namen: Prometheus reserviert Label-Namen mit
__-Präfix und entfernt sie beim Ingest, was die Overflow-Serie
still in eine echte Serie mischen würde.
Grenze beim Installieren der Registry anheben oder abschalten:
import { MetricsExtensionId, MetricsRegistryOptions } from 'actor-ts/metrics';
const metricsOptions = MetricsRegistryOptions.create().withMaxSeriesPerFamily(50_000);const metrics = system.extension(MetricsExtensionId).enable(metricsOptions);
// oder als einfaches Objekt: .enable({ maxSeriesPerFamily: 50_000 })0 schaltet die Grenze komplett ab — tu das nur, wenn jeder
Label-Wert nachweislich aus einer beschränkten Menge stammt.
(0, nicht Infinity: die Grenze ist eine Ganzzahl-Anzahl, und
Infinity ist keine Ganzzahl.)
Dieselbe Grenze kann auch aus einer Config-Datei kommen, als
actor-ts.metrics.max-series-per-family:
actor-ts.metrics.max-series-per-family = 50000enable() legt die drei pro Feld übereinander: Optionen, die du
übergibst, gewinnen, die Datei füllt, was sie offen lassen, und
10 000 ist der Boden. Die Datei ist der einzige Weg zu den
Registries, die du nie selbst einschaltest — die, die DevTools
einschaltet, solange es angehängt ist, und die in jedem Worker eines
Worker-Mesh,
dessen System aus der Config des Main-Threads gebaut wird.
Eine Serie entfernen
Abschnitt betitelt „Eine Serie entfernen“Die Grenze beschränkt, wie viele Serien eine Familie hält;
remove macht daraus eine Schranke dafür, wie viele lebendig sind:
metrics.gauge('queue_depth', { queue: 'orders' }).set(4_200);
// Die Queue ist weg — ihre Serie auch, und der Platz, den sie belegte.metrics.remove('queue_depth', { queue: 'orders' }); // → trueEs antwortet true, wenn tatsächlich eine Serie entfernt wurde, und
false für eine Familie, die es nicht gibt, für ein Tupel, das nie
erzeugt wurde, und für die Overflow-Serie — die bleibt, weil sie der
stehende Nachweis dafür ist, dass Tupel verworfen wurden, und ihr
Counter hält, wie viele. Die Familie selbst überlebt ihre letzte Serie,
samt Hilfetext und Art.
Entfernt, nicht genullt. Ein Gauge-Child hält seinen letzten Wert,
ein zurückkehrendes Tupel wird also frisch erzeugt und setzt nicht bei
dem Wert fort, den es vorher hatte. Genau das wollte das framework-eigene
actor_mailbox_size:
ein Actor, der abarbeitet, hört auf zu melden, statt für immer einen
Rückstau von 0 zu behaupten.
Ein Aufruf, kein TTL. Die Registry kann eine fertige Entity nicht von einem Counter für etwas Seltenes unterscheiden — eine Serie, die sich eine Stunde nicht bewegt hat, sieht in beiden Fällen gleich aus —, während der Code, dem das Instrument gehört, genau weiß, wann sein Gegenstand weg ist. Ein altersbasierter Durchlauf bräuchte außerdem Uhr und Timer in einem Primitiv, das beides nicht hat, und wäre für Counter schlicht falsch: einer, der herausaltert und neu erzeugt wird, liest sich downstream als ein Reset, den es nie gab. Entferne die Serie eines Counters deshalb nur, wenn das Gezählte endgültig weg ist, nicht um Kardinalität zurückzugewinnen; Gauges haben keine solche Historie und sind der vorgesehene Aufrufer.
Werte im Prozess auslesen
Abschnitt betitelt „Werte im Prozess auslesen“const counter = metrics.counter('events_total');counter.inc();counter.value; // → 1value ist der aktuelle Counter-/Gauge-Wert — eine
readonly-Property, keine Methode. Für Histogramme lies count,
sum, buckets und counts direkt:
const h = metrics.histogram('latency');h.observe(10);h.observe(20);h.count; // → 2h.sum; // → 30h.buckets; // → readonly Bucket-Grenzen, endend mit Infinityh.counts; // → kumulative Beobachtungsanzahl pro BucketNützlich für Tests und eigene Exporter.
Wo es weitergeht
Abschnitt betitelt „Wo es weitergeht“- Observability — Überblick — das größere Bild.
- Prometheus-Exporter —
/metricsfür Prometheus zum Scrapen freilegen. - Stock-Metriken — die automatisch aufgezeichneten Actor/Mailbox/Cluster-Metriken des Frameworks.
- prom-client-Adapter —
für Projekte, die schon
prom-clientnutzen.
MetricsExtension und die Metrik-Primitive kommen aus dem Sub-Pfad
actor-ts/metrics. Die generierte API-Referenz wird allein
aus dem Root-Barrel actor-ts erzeugt, deshalb sind diese Seite und die
Seite Prometheus-Exporter
die Referenz dafür.
