Instrumentiert
im Moment, in dem du es schreibst.
Du verdrahtest kein Tracing — die Runtime tut es. Jede Mutation, Query, Subscription, jeder Workflow, Webhook und AI-Call emittiert automatisch einen OpenTelemetry-Span und speist die Metrik-Registry. Lies es im In-App-Dashboard oder exportiere es in das, was du schon betreibst.
// nothing to wire — every primitive emits a span
// posts.create.mutation.server.ts
export default async (input, ctx) =>
ctx.store.insert('posts', input)
// └─ auto span: mutation.posts.create
// + voltro_rpc_* metrics, one traceId
// from the browser through the API
// export: OTEL_EXPORTER_OTLP_ENDPOINT=… → OTLP
// or add @voltro/plugin-prometheus → /metricsWas du bekommst, ohne irgendetwas zu instrumentieren.
OpenTelemetry-native Spans
Jede Primitive emittiert automatisch einen Span — ein Wasserfall pro Request, den du ohne einen einzigen Tracer-Call lesen kannst. Modi: console, otlp (aus OTEL_*-Env auto-erkannt) oder off, mit einem Always-on-Buffer für das In-App-Dashboard.
Eine Metrik-Registry, eingebaut
voltro_rpc_*, voltro_http_*, voltro_ai_* und mehr landen in einer Effect-MetricRegistry — Request-Counts, Latenzen, Error-Rates, AI-Token-Spend — bereit zum Export oder Scrapen.
In-App-Traces & Time-Travel
Der Always-on-Buffer treibt ein Traces-Dashboard in der App — inspiziere den Span-Baum eines Requests und spiele ihn erneut ab, kein externes Backend nötig, um zu starten.
Verteiltes Tracing
Eine traceId fließt vom Browser durch die API und zurück, sodass eine langsame Interaktion ein einziger Trace end-to-end ist — nicht vier zusammenhanglose Logs, die du von Hand korrelieren musst.
Überallhin exportieren
plugin-prometheus exponiert GET /metrics; plugin-datadog pusht Metriken, Logs und Traces; plugin-sentry sendet trace-korrelierte Errors; plugin-logship shippt strukturierte Logs zu Better Stack / Axiom / Loki / jedem JSON-Intake.
CLI + DevTools-Inspektion
voltro logs und voltro traces streamen aus dem Terminal; das DevTools-Dashboard zeigt Routes, RPC, Workflows, Schedules, Cache, Logs, Traces und Pro-Plugin-Panels über /_voltro/inspect/*.
Standardmäßig an, per Seam erweiterbar.
Auch Plugins tragen Observability bei
Observability wird nicht am Ende drangeschraubt — sie wird von der Runtime und jedem First-Party-Plugin emittiert, und ein contributeObservability-Seam lässt deine eigenen Plugins Spans und Metriken auf dieselbe Weise ergänzen. Dreh es für Produktion auf OTLP, lass es in Dev auf console, oder lies das In-App-Dashboard so oder so.
Ein Trace, vier Schichten.
// Nothing to instrument by hand — the span comes from the primitive.
// client.mutation orders.ship 12ms
// server.mutation orders.ship 11ms trace 4f9c…
// store.transactional 7ms trace 4f9c…
// workflow.step reserve 4ms trace 4f9c…
// http POST /warehouse 3ms trace 4f9c…Der Identifier ist an allen vier Stellen derselbe — die einzige Eigenschaft, auf die es ankommt, wenn etwas kaputtgegangen ist: du liest eine Kausalkette, statt vier Systeme über Zeitstempel zu korrelieren und zu hoffen.
Observability im Detail.
Was ist instrumentiert, ohne dass ich etwas tue?
Jeder Procedure-Aufruf, jede Mutation, jeder Workflow-Schritt, jede Cron-Auslösung und jede Datenbank-Query, die die Runtime absetzt. Weil das deklarierte Primitive sind und keine anonymen Funktionen, weiß das Framework, was jedes ist, und kann es messen, tracen und zuordnen, ohne dass du einen Span hinzufügst.
Traces sind end-to-end korreliert: eine Browser-Aktion, der ausgelöste rpc-Aufruf, der Handler, die Queries darunter und ein gestarteter Workflow teilen eine Trace-Id. Das ist der Unterschied zwischen „dieser Request war langsam“ und „dieser Request war langsam wegen dieser drei Queries in diesem Schritt“.
Logs tragen dieselbe Korrelation. Eine Logzeile aus einem Handler ist mit Trace und Subject gestempelt — nach Trace-Id zu filtern gibt dir die ganze Geschichte eines Requests, statt einer Stichwortsuche über einen Tag Ausgabe.
Muss ich Daten an einen Anbieter schicken?
Nein. Standard ist eine lokale Inspect-Oberfläche: `voltro inspect`, `logs`, `traces` und das Dashboard lesen eine laufende App direkt über einen authentifizierten Endpunkt. Nichts verlässt deine Infrastruktur, und es gibt kein Konto anzulegen, bevor du sehen kannst, was deine App tut.
Wenn du einen Anbieter willst, sind das Plugins statt eines Umbaus: Prometheus-Scraping, tiefe Datadog- und Sentry-Integrationen oder strukturierte Logs an Better Stack, Axiom, Loki oder eine beliebige HTTP-Senke. Jedes reitet auf den vorhandenen Metrik- und Log-Hooks — eines hinzuzunehmen heißt nicht, deinen Code erneut zu instrumentieren.
Die Exporter lesen dieselbe vereinheitlichte Metrik-API wie das Dashboard. Das zählt, weil der übliche Fehler zwei Wahrheitsquellen sind — ein Dashboard, das eines sagt, und ein Alarm, der auf etwas anderem feuert — und hier steht hinter beidem eine Registry.
Wie debugge ich etwas, das schon passiert ist?
Indem du einen Datensatz liest statt einen zu rekonstruieren. Ein Workflow führt ein Journal über jeden Schritt, sein Ergebnis und sein Timing — ein vor drei Tagen gescheiterter Lauf lässt sich also inspizieren und wiederholen. Ein Dead-Letter-Lauf ist ein abfragbarer Zustand, keine verlorene Nachricht.
Zeilenhistorie ist optional, aber verfügbar: mit dem Row-History-Plugin wird jedes Insert, Update und Delete auf den von dir gelisteten Tabellen als Snapshot festgehalten. Du kannst fragen, wie eine Zeile zu einem Zeitpunkt aussah, zwei Versionen diffen oder eine zurückholen — Fragen, die sonst zur Archäologie in Backups werden.
Audit ist ein eigenes Thema mit strengerer Zusicherung: wer was getan hat, einem Subject zugeschrieben, inklusive der Frage, ob die Aktion über eine impersonierte Session erfolgte — eine Markierung, die keine Redaction-Regel entfernen kann.
Was ist mit Kosten und Verhalten der KI-Teile?
KI-Aufrufe sind wie alles andere instrumentiert, mit Token-Verbrauch und Kosten pro Aufruf, pro Procedure und pro Mandant zugeordnet. Ein Kostenbudget ist ein deklariertes Primitiv statt eines Dashboard-Alarms — es zu überschreiten ist damit etwas, worauf die Runtime reagieren kann, statt etwas, das später jemand bemerkt.
Agent-Läufe werden aufgezeichnet und lassen sich gegen Golden Cases wiederholen — eine Prompt- oder Modelländerung ist damit als Regressionstest bewertbar statt nach Gefühl, und lässt sich in ein Deploy-Gate hängen, das bei Qualitätsverlust scheitert.
Experimente und Erwartungen sind dieselbe Idee, auf Verhalten angewandt: deklarier, was gelten soll, und lass Verletzungen dort melden, wo sie auftreten, statt sie Wochen später an einer wandernden Metrik zu entdecken.
Was für dich instrumentiert ist.
| Oberfläche | Beantwortet |
|---|---|
| Verteilte Traces | Wo die Zeit blieb — korreliert von der Browser-Aktion über Handler und Query bis zum Workflow-Schritt. |
| Strukturierte Logs | Was in einem Request passierte, mit Trace und Subject gestempelt statt per Stichwort gesucht. |
| Metriken | Eine Registry hinter Dashboard und Exportern — Alarme und Panels können sich nicht widersprechen. |
| Workflow-Journale | Jeder Schritt jedes Laufs, inspizierbar und wiederholbar — auch Dead-Letter-Läufe. |
| Zeilenhistorie | Zeitreise über gelistete Tabellen: was eine Zeile war, was sich änderte, und eine frühere Version zurückholen. |
| Audit | Wer was getan hat, zugeschrieben — inklusive Aktionen über eine impersonierte Session. |
Häufige Fragen
Brauche ich einen Observability-Anbieter, um überhaupt etwas zu sehen?
Nein. CLI und Dashboard lesen eine laufende App über eine authentifizierte lokale Oberfläche — Traces, Logs, Metriken und Workflow-Läufe sind ohne Konto und ohne Egress sichtbar. Anbieter sind Plugins, die du hinzunimmst, wenn du willst.
Muss ich Spans in meine Handler einbauen?
Nein. Procedures, Workflow-Schritte, Cron-Auslösungen und Queries sind instrumentiert, weil sie deklarierte Primitive sind — die Runtime weiß, was jedes ist. Einen Span fügst du hinzu, um etwas innerhalb eines Handlers zu markieren, nicht um die Grundlage zu bekommen.
Kann ich Prometheus, Datadog oder Sentry nutzen?
Ja, als Plugins über die vorhandenen Hooks. Prometheus stellt einen Scrape-Endpunkt aus der vereinheitlichten Metrik-Registry bereit; Datadog und Sentry integrieren tief, mit Fehlern, die zum aktiven Trace korreliert sind statt als eigenständige Ereignisse gemeldet.
Wie finde ich heraus, wie eine Zeile früher aussah?
Mit dem Row-History-Plugin, das jeden Schreibvorgang auf den von dir gelisteten Tabellen als Snapshot festhält. Du kannst eine Zeile zu einem Zeitpunkt lesen, zwei Versionen diffen oder eine zurückholen — ohne ein Backup als Abfrageschnittstelle zu missbrauchen.
Sind KI-Nutzung und -Kosten sichtbar?
Ja, zugeordnet pro Aufruf, pro Procedure und pro Mandant — und ein Kostenbudget ist ein deklariertes Primitiv, auf das die Runtime reagieren kann, statt eines Alarms, den jemand hinterher liest. Agent-Läufe werden außerdem aufgezeichnet und sind als Deploy-Gate gegen Golden Cases wiederholbar.
Observability spannt sich über die ganze Runtime.
Öffne das Framework. Schau es dir selbst an.
Jede Primitive auf dieser Seite ist heute im Framework. Klone den Starter, lass `voltro dev` laufen, in zwei Minuten ist es auf dem Bildschirm.