Zum Inhalt springen
Deutsch

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 counter
http_requests_total{route="/orders"} 1234
http_requests_total{route="/users"} 567
# HELP sessions_active Currently active sessions
# TYPE sessions_active gauge
sessions_active 123
# HELP http_request_duration_ms HTTP request latency
# TYPE http_request_duration_ms histogram
http_request_duration_ms_bucket{route="/orders",le="10"} 100
http_request_duration_ms_bucket{route="/orders",le="50"} 250
http_request_duration_ms_bucket{route="/orders",le="+Inf"} 300
http_request_duration_ms_count{route="/orders"} 300
http_request_duration_ms_sum{route="/orders"} 12450

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 endpoint
const 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.

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 /metrics erwartungsgemäß pro Target.

  • Worker-Threads. Jeder Worker eines Worker-Mesh — auch die, die actor-ts.parallelism.workers für dich startet (Parallelität) — bootet sein eigenes ActorSystem mit eigener Registry, und in einem Worker läuft kein Management-Endpunkt. Das Mesh relayt sie: Alle actor-ts.worker-mesh.metrics-relay-interval (Default 10s) zieht der Main-Thread die Registry jedes Workers und exportiert sie neben seiner eigenen, sodass GET /metrics auf dem Main-Thread der ganze Prozess ist. Solange das Relay läuft, trägt jede Serie ein thread-Label — main fü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 threads
    sum without (thread) (rate(actor_messages_delivered_total[5m]))
    # …and per thread, to see whether the offloaded actors carry the load
    sum by (thread) (rate(actor_messages_delivered_total[5m]))
    # A worker that has stopped answering the relay
    worker_mesh_snapshot_age_seconds > 30

    Die 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 503 oben verhindert — und worker_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, den rate() 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 ein enable() auf dem Main-Thread nach dem Start des Mesh beim nächsten Tick. metrics-relay-interval = 0 schaltet das Relay ab und mit ihm das thread-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 das sum without (thread) von oben. Das Relay deckt ein von Hand mit WorkerMesh.start gestartetes Mesh und das der Parallelismus-Extension gleichermaßen ab; OffloadPool-Worker betreiben kein ActorSystem, und die offload_*-Familien sind bereits die des Main-Threads.

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.

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.

http_requests_total # Counter — Suffix `_total`
sessions_active # Gauge — kein Suffix
http_request_duration_seconds # Histogram — _bucket / _count / _sum
process_cpu_seconds_total # Counter — Prometheus-Namensgebung

Prometheus 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 / _sum sind vom Framework angehängte Suffixe für Histogramme.
  • Labels sind snake_case-Strings.

Das Framework erzwingt diese nicht — aber Prometheus-Tooling erwartet sie.

  • 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.

SerieFormat
CounterEine Zeile pro Serie. metric_name{labels} value
GaugeGleich wie Counter.
HistogramEine _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.

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.