Prometheus-Exporter
Der Prometheus-Exporter verwandelt die In-Process-
Metriken-Registry in das Prometheus-Textformat, das
Prometheus / Grafana / Thanos von /metrics scrapen.
import { ActorSystem } from 'actor-ts';import { MetricsExtensionId, exportPrometheus } from 'actor-ts/metrics';
const system = ActorSystem.create('my-app');const metrics = system.extension(MetricsExtensionId);
// In einem HTTP-Handler:get(async () => { const text = exportPrometheus(metrics.get()); return { status: 200, body: text, contentType: 'text/plain; version=0.0.4' };});Gibt einen einzelnen String im Prometheus-0.0.4-Exposition-Format zurück:
# HELP http_requests_total Total HTTP requests# TYPE http_requests_total counterhttp_requests_total{route="/orders"} 1234http_requests_total{route="/users"} 567
# HELP sessions_active Currently active sessions# TYPE sessions_active gaugesessions_active 123
# HELP http_request_duration_ms HTTP request latency# TYPE http_request_duration_ms histogramhttp_request_duration_ms_bucket{route="/orders",le="10"} 100http_request_duration_ms_bucket{route="/orders",le="50"} 250http_request_duration_ms_bucket{route="/orders",le="+Inf"} 300http_request_duration_ms_count{route="/orders"} 300http_request_duration_ms_sum{route="/orders"} 12450Über den Management-Endpunkt
Abschnitt betitelt „Über den Management-Endpunkt“Der einfachste Weg führt über die Management-Routen:
import { managementRoutes } from 'actor-ts/management';
// cluster can be null when you only need the metrics endpointconst routes = managementRoutes(system, null, { enableMetricsEndpoint: true, // ← exposes GET /metrics});await system.http(8558).bind(routes);Prometheus-Scrape-Config:
scrape_configs: - job_name: 'actor-ts' static_configs: - targets: ['my-app:8558']Der Management-Server läuft auf einem separaten Port vom Haupt-HTTP-Server deiner App. Typisches Muster: App auf 8080 (öffentlich), Management auf 8558 (nur intern).
Diese Route liest die Registry über collect() und braucht deshalb
eine Registry, die sich so lesen lässt — die des Frameworks kann
das. Die prom-client-Bridge
kann es nicht: sie leitet ihre Schreibvorgänge weiter und behält
keinen Snapshot. Mit dieser Bridge antwortet die Route mit 503
und benennt den Konflikt, statt mit 200 und leerem Body, den
Prometheus als gesundes Target ohne Serien akzeptieren würde.
Scrape in diesem Setup die eigene /metrics-Route von prom-client
und lass enableMetricsEndpoint aus.
Geltungsbereich: pro Prozess, pro Thread
Abschnitt betitelt „Geltungsbereich: pro Prozess, pro Thread“Jedes ActorSystem besitzt seine eigene Registry, und GET /metrics
exportiert genau die des Systems, das die Route gebunden hat. Nichts
aggregiert über Systeme hinweg, und daraus folgen zwei Deployment-Formen:
-
Cluster-Knoten. Jeder Knoten exportiert sich selbst. Das ist das Prometheus-Modell — jede Instanz scrapen, in der TSDB aggregieren — und das Gegenteil dessen, was DevTools tut, das für seine eigenen Ansichten Werte über Knoten hinweg föderiert. Eine Zahl, die in DevTools über Knoten hinweg übereinstimmt, unterscheidet sich unter
/metricserwartungsgemäß pro Target. -
Worker-Threads. Jeder Worker eines Worker-Mesh — auch die, die
actor-ts.parallelism.workersfür dich startet (Parallelität) — bootet sein eigenesActorSystemmit eigener Registry, und in einem Worker läuft kein Management-Endpunkt. Das Mesh relayt sie: Alleactor-ts.worker-mesh.metrics-relay-interval(Default10s) zieht der Main-Thread die Registry jedes Workers und exportiert sie neben seiner eigenen, sodassGET /metricsauf dem Main-Thread der ganze Prozess ist. Solange das Relay läuft, trägt jede Serie einthread-Label —mainfür die eigenen Samples des Main-Threads,worker-0,worker-1, … für die jedes Workers (der Slot, der auch der Name des Threads ist) — denn zwei Threads melden dieselben Stock-Familien unter denselben Labels, und das Label ist das, was sie auseinanderhält. Aggregiere darüber für eine Prozesszahl:# Messages delivered by the whole process, all threadssum without (thread) (rate(actor_messages_delivered_total[5m]))# …and per thread, to see whether the offloaded actors carry the loadsum by (thread) (rate(actor_messages_delivered_total[5m]))# A worker that has stopped answering the relayworker_mesh_snapshot_age_seconds > 30Die Werte eines Workers sind höchstens ein Relay-Intervall alt. Ein Worker, der lebt, aber nicht mehr antwortet, behält seinen letzten exportierten Snapshot — eine Serie, die verschwindet, ist genau die Fehlerform, die das
503oben verhindert — undworker_mesh_snapshot_age_seconds{worker="worker-N"}auf dem Main-Thread sagt, wie lange schon; ein Worker, der das Mesh verlässt, nimmt seine Serien mit, und ein neu gestarteter Slot kommt unter demselben Label zurück, mit Countern, die von vorn beginnen — ein Reset, denrate()verkraftet. Die erste Anfrage geht beim Start des Mesh hinaus und ist zugleich das, was die Registry eines Workers einschaltet, sodass in einem Worker nichts aktiviert werden muss; das Zählen eines Workers beginnt mit seiner ersten Anfrage, also greift einenable()auf dem Main-Thread nach dem Start des Mesh beim nächsten Tick.metrics-relay-interval = 0schaltet das Relay ab und mit ihm dasthread-Label: Ein einthreadiges System, oder ein Mesh mit abgeschaltetem Relay, exportiert exakt die Bytes, die es vor dem Relay exportiert hat. Worker einzuschalten ist deshalb der eine Moment, in dem sich die Label-Menge jeder Serie ändert — eine Regel über eine rohe Familie (actor_mailbox_dropped_total > 0) funktioniert weiter, eine, die eine Familie über die Änderung hinweg mit sich selbst vergleicht, braucht dassum without (thread)von oben. Das Relay deckt ein von Hand mitWorkerMesh.startgestartetes Mesh und das der Parallelismus-Extension gleichermaßen ab; OffloadPool-Worker betreiben keinActorSystem, und dieoffload_*-Familien sind bereits die des Main-Threads.
Manuelles Verdrahten
Abschnitt betitelt „Manuelles Verdrahten“Wenn du die Management-Routen nicht nutzt, route GET /metrics
selbst:
import { path, get } from 'actor-ts/http';import { exportPrometheus } from 'actor-ts/metrics';
const routes = path('metrics', get(async () => ({ status: 200, body: exportPrometheus(metrics.get()), contentType: 'text/plain; version=0.0.4', headers: {}, })),);exportPrometheus(registry) und prometheusHandler(registry) rendern
diese Registry — die eigene des Main-Threads — und nichts sonst. Auf
einem System mit Worker-Mesh liegen die
relayten Worker-Snapshots auf der MetricsExtension, nicht in der
Registry, also ist die zusammengeführte Sicht, die die Management-Route
liefert, renderPrometheusSamples(collectAll()):
import { path, get } from 'actor-ts/http';import { MetricsExtensionId, renderPrometheusSamples } from 'actor-ts/metrics';
const routes = path('metrics', get(async () => ({ status: 200, body: renderPrometheusSamples(system.extension(MetricsExtensionId).collectAll()), contentType: 'text/plain; version=0.0.4', headers: {}, })),);collectAll() ist collect(), bis ein Mesh sein Relay registriert, also
ist die zweite Form überall sicher, und die erste ist auf einem Mesh eine
dokumentierte Hälfte.
Binde wenn möglich an einen dedizierten Port — Prometheus’ Scrapes sind periodisch und sollten den App-Port nicht teilen.
Der Renderer vertraut seiner Eingabe
Abschnitt betitelt „Der Renderer vertraut seiner Eingabe“renderPrometheusSamples schreibt Familiennamen und Label-Keys roh —
das Textformat bietet für keine der beiden Positionen ein Escaping, denn
sie sind seine Grammatik. Sicher macht das die Registry: Sie weist
einen Namen außerhalb von [a-zA-Z_:][a-zA-Z0-9_:]* und einen Label-Key
außerhalb von [a-zA-Z_][a-zA-Z0-9_]* schon beim Anlegen der Serie
zurück, also ist alles, was sie eingesammelt hat, bereits geprüft. Der
Renderer prüft bewusst nicht erneut — das kostete einen regulären
Ausdruck pro Familie bei jedem Scrape, für eine Frage, die bei der
Registrierung einmal beantwortet wurde.
Die Pflicht wandert also mit der Eingabe. Wenn du MetricsRegistry
selbst implementierst oder renderPrometheusSamples eine Liste gibst,
die du zusammengebaut statt eingesammelt hast, gehört diese Prüfung
dir. Ein Sample mit dem Namen
x_total 1\nnode_up{job="prod"} 0\n# rendert als genau diese drei
Zeilen, und wer das scrapet, kann das gefälschte node_up nicht von
einem echten unterscheiden — ein Alert auf node_up == 0 wird so
zuverlässig stummgeschaltet wie durch einen behobenen Ausfall. Genau
dafür sind die beiden Grammatiken exportiert, und die beiden reservierten
Keys mit ihnen:
import { PROMETHEUS_LABEL_NAME_PATTERN, PROMETHEUS_METRIC_NAME_PATTERN, RESERVED_LABEL_PREFIX, THREAD_LABEL, renderPrometheusSamples, type MetricSample,} from 'actor-ts/metrics';
const usableLabelKey = (key: string): boolean => PROMETHEUS_LABEL_NAME_PATTERN.test(key) && key !== THREAD_LABEL && !key.startsWith(RESERVED_LABEL_PREFIX);
const trustworthy = (sample: MetricSample): boolean => PROMETHEUS_METRIC_NAME_PATTERN.test(sample.name) && Object.keys(sample.labels).every(usableLabelKey);
// `samples` came from somewhere this package never checked.const renderForeign = (samples: ReadonlyArray<MetricSample>): string => renderPrometheusSamples(samples.filter(trustworthy));Die Grammatiken sind die Injection-Hälfte; die beiden reservierten Keys
sind die Fälschung, die die Grammatiken nicht abfangen. thread ist das
Label, das die Exposition selbst stempelt, solange ein Worker-Mesh relayt
(#1570), und __ ist der Namensraum des Servers — ein __name__ unter
den Labels eines Samples wird von einem Scrape-Job mit
honor_labels: true übernommen, der das Sample dann unter dem Namen
ablegt, den dieses Label trägt (#1513).
Das Worker-Mesh-Relay ist das ausgearbeitete Beispiel: Ein Snapshot aus
einem Worker überquert eine Thread-Grenze, also prüft das Relay jeden
Namen und jeden Label-Key erneut — beide Grammatiken und beide
Reservierungen, über denselben Helper, den auch die Registry benutzt —,
bevor die Samples den Renderer erreichen. Für alles, was
system.metrics selbst angelegt hat, braucht es das nicht: Die Prüfung
ist beim anlegenden Aufruf schon passiert.
Namenskonventionen
Abschnitt betitelt „Namenskonventionen“http_requests_total # Counter — Suffix `_total`sessions_active # Gauge — kein Suffixhttp_request_duration_seconds # Histogram — _bucket / _count / _sumprocess_cpu_seconds_total # Counter — Prometheus-NamensgebungPrometheus hat Konventionen (Naming-Guide):
- Counter enden auf
_total(oder beschreiben, was gezählt wird). - Histogramme / Timer enthalten die Einheit im Namen
(
_seconds,_ms,_bytes). _count/_sumsind vom Framework angehängte Suffixe für Histogramme.- Labels sind snake_case-Strings.
Das Framework erzwingt diese nicht — aber Prometheus-Tooling erwartet sie.
Scrape-Frequenz vs Gauge-Update-Rate
Abschnitt betitelt „Scrape-Frequenz vs Gauge-Update-Rate“- Scrape alle 15-30 Sekunden — Prometheus-Default.
- Gauges in beliebiger Kadenz aktualisieren — Prometheus sieht nur den Wert zur Scrape-Zeit.
- Counter können in beliebiger Rate inkrementiert werden; Prometheus berechnet die Rate aus aufeinanderfolgenden Scrapes.
Für sehr schnell ändernde Werte (Speichernutzung, Mailbox-Tiefe) kann der Gauge zur Scrape-Zeit veraltet sein. Das ist okay — Prometheus ist mit seinen Samples eventually consistent.
Details zum Exposition-Format
Abschnitt betitelt „Details zum Exposition-Format“| Serie | Format |
|---|---|
| Counter | Eine Zeile pro Serie. metric_name{labels} value |
| Gauge | Gleich wie Counter. |
| Histogram | Eine _bucket{le=N}-Zeile pro Bucket + _count + _sum. |
Der Exporter übernimmt die Formatierung; du baust sie nicht manuell.
Ein Label-Wert ist das einzige Feld, das Daten trägt, und die
0.0.4-Escape-Tabelle definiert dafür genau drei Escapes — \\, \n und
". Der Exporter schreibt diese drei und sonst keine: Jedes andere
C0-Steuerzeichen (Carriage Return, NUL, der Unit Separator, …) wird aus
dem Wert und aus dem # HELP-Text entfernt statt escaped, denn ein
Escape außerhalb dieser Tabelle lässt Reader auf Basis von
prometheus/common — Pushgateway, den node_exporter-Textfile-Collector,
promtool check metrics — den gesamten Scrape-Body verwerfen, nicht
nur die eine Serie. Ein Tab überlebt; ein Line Feed ebenso, als \n.
Derselbe Strip läuft auch beim Anlegen einer Serie, eine Ebene
unter dem Exporter — zwei Werte, die sich nur in Steuerzeichen
unterscheiden, sind deshalb eine Serie, deren Counter summiert, und
nicht zwei. Gemessen:
counter('m_total', { msg: 'ab' }).inc(1) neben
counter('m_total', { msg: 'a\x1fb' }).inc(2) lässt die Registry eine
einzige Serie halten und rendert die eine Zeile m_total{msg="ab"} 3.
Dass die beiden verschmelzen, ist eine Korrektheitseigenschaft und keine Bequemlichkeit. Bis #1414 lief der Strip nur zur Render-Zeit, die Registry hielt zwei Kinder, und der Body trug zwei Zeilen, deren Metrikname und Label-Menge Byte für Byte gleich waren — eine duplizierte Serie, und ein Prometheus-Scrape verwirft dafür den gesamten Body. Ein einziger Label-Wert mit einem Unit Separator riss also jede andere Familie mit.
Ein Steuerzeichen in einem Label-Wert ist trotzdem ein Bug an seiner Quelle: Entferne oder ersetze es dort, statt dich auf den Exporter zu verlassen. Das Verschmelzen hält die Exposition gültig, es macht aus zwei Subjekten aber kein einziges.
Wo es weitergeht
Abschnitt betitelt „Wo es weitergeht“- Observability — Überblick — das größere Bild.
- Core-Metriken — die vier Primitive.
- Management — Überblick —
der einfache Weg,
/metricszu exponieren. - Stock-Metriken — die automatisch aufgezeichneten Metriken des Frameworks, die hier erscheinen.
exportPrometheus, prometheusHandler und renderPrometheusSamples
kommen aus dem Sub-Pfad actor-ts/metrics. Die generierte
API-Referenz wird allein aus dem Root-Barrel actor-ts
erzeugt, deshalb ist diese Seite die Referenz für die drei.
