For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /de/docs/modules/observability.md (or send Accept: text/markdown).
Audit, Analytics und Fehler
Aktivität mit Workspace-Kontext und bereinigten Event-Daten verstehen.
Finden Sie nützliche Informationen, wenn eine Aktion fehlschlägt
Beobachtbarkeit bedeutet, zu sehen, was Ihre App getan hat. Beginnen Sie mit dem Terminal, auf dem Ihr Webserver läuft: Wiederholen Sie eine fehlgeschlagene Aktion und lesen Sie den ersten Fehler und jede Korrelations-ID, eine Bezeichnung, die Nachrichten von derselben Anfrage verknüpft. Teilen Sie den Befehl, die Zeit und den bereinigten Fehler mit, wenn Sie um Hilfe bitten. Teilen Sie keine .env-Dateien oder Token.
Befolgen Sie für gehostete Fehlerberichte die Anweisungen zu „Zustand und Betrieb“, um die unterstützten Überwachungseinstellungen in apps/web/.env.local oder im Umgebungs-Dashboard des Hosts zu konfigurieren. Speichern Sie den Server und starten Sie ihn neu. Lösen Sie einen kontrollierten Testfehler in einer Testumgebung aus und bestätigen Sie, dass er im richtigen Arbeitsbereichskontext angezeigt wird. Die konfigurierte Überwachung beweist nicht, dass ein Ereignis empfangen wurde.
ALERT_WEBHOOK_URL ist ein optionales HTTPS-Ziel für Job- und Terminal-Webhook-Zustellungsfehlerwarnungen. Erstellen Sie bei Bedarf einen kompatiblen eingehenden Endpunkt und speichern Sie dessen URL serverseitig. andernfalls lassen Sie es leer. Bitten Sie einen Agenten, einen Fehler zu simulieren und genau eine Warnung zu bestätigen, ohne dass der Text Geheimnisse enthält. Lösen Sie für diesen Test keine bezahlte Arbeit oder Ausfälle in Kundenkonten aus.
Audit-Trail für einen Workspace führen
Audit-Datensätze erfassen Änderungen wie Aktualisierungen der Provider-Konfiguration innerhalb eines Workspace. Ermittle vor dem Lesen oder Schreiben dieser Datensätze den authentifizierten Workspace und bewahre diesen Geltungsbereich bei produktspezifischen Ereignissen.
Speichere die Aktion und die Kennungen, die zum Verständnis erforderlich sind. Provider-Zugangsdaten und andere sensible Werte gehören weder in Audit-Nutzdaten noch in Logs.
Produktereignisse erfassen
Das Observability-Paket stellt einen AnalyticsClient-Adapter und Workspace-gebundene AnalyticsEvent-Werte bereit. Jedes Ereignis enthält einen Namen, eine eindeutige Identität, workspaceId und optionale Eigenschaften.
Verwende createObservability, um Ereignisse über den konfigurierten Analytics-Client zu leiten. Strukturierte Eigenschaften werden vor der Übermittlung bereinigt; halte auch sensible Freitexte aus Ereignisnamen und Eigenschaftswerten heraus.
Fehler mit sicherem Kontext melden
ErrorClient erfasst Ausnahmen mit workspaceId-Tags und strukturiertem Zusatzkontext. Die gemeinsame Observability-Schicht bereinigt Ausnahmen und entfernt sensible Kontextwerte, bevor sie diese an den konfigurierten Client weiterleitet.
Verwende lokale Adapter, um erfasste Ereignisse und Ausnahmen ohne Aufruf eines Monitoring-Anbieters zu prüfen. Stelle sicher, dass Workspace-Tags erhalten bleiben und Zugangsdaten vor dem Aktivieren eines externen Ziels entfernt werden.
Eine Anfrage über Aufgaben, Jobs und Webhooks hinweg verfolgen
Einstiegspunkte erzeugen eine Korrelations-ID corr_<uuid>, die die ursprüngliche Anfrage mit der dadurch ausgelösten Arbeit verknüpft. Beim Einreichen einer KI-Aufgabe wird die ID in die Aufgaben-Nutzdaten und das Ereignis ai_task_submitted geschrieben, jeder Empfänger für Abrechnungs-Webhooks erzeugt eine pro Anfrage und der Scheduler eine pro ausgelöstem Job.
Dieselbe ID wird in die Ereigniseigenschaften von job.completed und ai_task_completed, in captureException-Zusatzdaten, die Nutzdaten des webhook_event-Ledgers und die meta-Nutzdaten jedes webhook_delivery-Datensatzes übernommen. So gelangt sie in den signierten Body, den ein Subscriber erhält. Fehlende oder fehlerhafte IDs werden toleriert: Der Consumer erzeugt eine neue ID, statt ältere Datensätze abzulehnen.
Bei echten Fehlern alarmieren
Setze ALERT_WEBHOOK_URL auf einen beliebigen HTTPS-Endpunkt, der einen JSON-POST in der Form {text, name, severity, context} annimmt; ein Slack-artiger eingehender Webhook funktioniert unverändert. Alarme laufen ohne Abwarten mit einem Timeout von fünf Sekunden. Eine fehlgeschlagene Zustellung protokolliert eine Konsolenwarnung; ohne gesetzte Variable bleibt der Alarmgeber inaktiv.
Die bereitgestellten Alarme sind job.failed (warning – ein Job-Handler hat einen Fehler ausgelöst oder der Job-Typ ist unbekannt) und webhook.delivery_failed (critical – nur wenn eine ausgehende Zustellung nach ihrem letzten Versuch endgültig scheitert; gewöhnliche Wiederholungen bleiben still und jeder Zustellungsdatensatz alarmiert höchstens einmal).
Dauer messen und strukturierte Logs ausgeben
serverObservability.measure misst die Dauer einer asynchronen Operation und gibt ein Analytics-Ereignis <name>.duration mit durationMs aus – bei Erfolg und Fehler, ohne den ursprünglichen Fehler zu verdecken. Die Ausführung des Jobs ai.task.execute ist bereits umschlossen, sodass ihre Dauer im konfigurierten Analytics-Client erfasst wird.
serverObservability.logger schreibt pro Datensatz eine JSON-Zeile mit grundlegenden Umgebungs- und Dienstfeldern nach stdout. Die gemeinsame Redaktionsschicht entfernt Geheimnisse, bevor eine Zeile ausgegeben wird.