Überwachung einrichten

Beginne mit den Containerprotokollen und dem Zustand der Dienste. Ergänze Prometheus-Messwerte für Trends und Alarme sowie eine Fehlererfassung, wenn du vergangene Fehler durchsuchen möchtest. Tale übermittelt diese Daten nur dann an einen externen Überwachungsdienst, wenn du einen einrichtest.

Anwendungsprotokolle lesen

Container schreiben auf stdout und stderr. Die mitgelieferte Compose-Konfiguration nutzt Dockers Protokolltreiber json-file: maximal 10 MB pro Datei und drei Dateien pro Container. Verwende die Dienstnamen aus der Compose-Datei deiner Installation:

docker compose logs --tail=100 backend-api backend-worker
docker compose logs -f backend-api

Mit Ctrl-C beendest du die laufende Anzeige; die Container laufen weiter. Suche für Anfragen, Anmeldung und interaktive Chat-Antworten in backend-api; für Hintergrundaufgaben, eingereihte Agent-Aufrufe und Dokumentverarbeitung in backend-worker. docker compose ps zeigt dir Container, die wiederholt neu starten.

journalctl -u docker zeigt das Journal des Docker-Daemons. Beim Standardtreiber json-file ersetzt es die Containerprotokolle nicht. Für journald oder eine zentrale Protokollsammlung musst du den Docker-Protokolltreiber und die Sammlung gesondert einrichten. Tale liefert keinen Dienst zur Protokollweiterleitung mit. Nach einem Treiberwechsel musst du die betroffenen Container neu erstellen.

Geschützte Messwerte aktivieren

Setze einen starken METRICS_BEARER_TOKEN in der Bereitstellungsumgebung. Übernimm die Änderung über deinen Bereitstellungsablauf, sodass die betroffenen Dienste neu erstellt werden. Ein einfacher Containerneustart lädt die Compose-Umgebungswerte nicht neu. Hinterlege denselben Token in der Geheimnisverwaltung deines Überwachungssystems.

Der Proxy verlangt für diese Routen Authorization: Bearer <token>. Ohne konfigurierten Token antworten sie mit 401.

Das Backend beantwortet Wissensanfragen und verarbeitet Dokumente. HTTP- und Warteschlangenmesswerte helfen, Fehler und Rückstau zu erkennen; sie messen nicht gesondert die Dauer der Suche oder Antwortgenerierung. BACKEND_UPSTREAM legt bei einer getrennten Bereitstellung das Backend-Ziel fest. Es entsteht dadurch kein eigener Metrikdienst für die Wissensverarbeitung.

Richte pro Metrikroute einen eigenen Abfrageauftrag ein. Im Beispiel ist /run/secrets/tale_metrics_token eine Datei im Prometheus-Container, die ausschließlich den Token enthält. Erstelle sie über deine Geheimnisverwaltung und erlaube Prometheus den Lesezugriff.

scrape_configs:
  - job_name: tale-platform
    scheme: https
    metrics_path: /metrics/platform
    authorization:
      credentials_file: /run/secrets/tale_metrics_token
    static_configs:
      - targets: ['tale.example.com']
  - job_name: tale-backend
    scheme: https
    metrics_path: /metrics/backend
    authorization:
      credentials_file: /run/secrets/tale_metrics_token
    static_configs:
      - targets: ['tale.example.com']

Frage /metrics/sla-rules nicht als Metriken ab. Die generierten Regeln verweisen auf Zeitreihen, die zusätzliche Instrumentierung benötigen. Allein das Laden der Datei weist die Einhaltung der Antwortzeitziele nicht nach. Prüfe die Regeln, bevor du sie über die Regelkonfiguration von Prometheus lädst. Die vollständige Einrichtung beschreibt Prometheus und Grafana.

Ziel für Fehlerberichte wählen

SENTRY_DSN aktiviert die optionale Fehlererfassung. Du kannst Sentry oder einen kompatiblen Dienst wie GlitchTip oder Bugsink verwenden. Browser, Backend und Sandbox nutzen denselben DSN und die Umgebungsbezeichnung SENTRY_ENVIRONMENT; Server-Ereignisse enthalten Prozessrolle und Versionsnummer.

SENTRY_DSN=https://your-key@your-sentry-host/project-id
SENTRY_ENVIRONMENT=example-pr
SENTRY_TRACES_SAMPLE_RATE=0.1

Verwaltete Deployments verwenden als Umgebungsbezeichnung standardmäßig ihren bestehenden name. Für eine andere Bezeichnung deklarierst du "environment": { "SENTRY_ENVIRONMENT": { "env": "TALE_REPORTING_ENVIRONMENT" } } in der Deployment-Spezifikation und setzt die Variable am Ziel. Der Wert beginnt mit einem Kleinbuchstaben oder einer Ziffer und enthält 1–64 Kleinbuchstaben, Ziffern oder Bindestriche. Deployment-Identität, Zustand und gespeicherte Zugangsdaten bleiben an ihren bestehenden Pfaden.

Sandbox-Fehler umfassen fehlgeschlagene HTTP-Anfragen und Hintergrundaufgaben. Erwartete Client-Abbrüche und nach einer Abmeldung geschlossene SSE-Streams werden ausgeschlossen. Die Sandbox sendet nur Fehler; die Tracing-Einstellungen für Browser und Backend aktivieren kein Sandbox-Tracing. Sie nutzt den unten beschriebenen Datenschutzfilter des Backends.

SENTRY_TRACES_SAMPLE_RATE gilt für Leistungstraces im Browser; in der Entwicklung beträgt die Standardrate 1.0. Backend-Tracing ist standardmäßig deaktiviert. Setze BACKEND_SENTRY_TRACES_SAMPLE_RATE auf einen Wert zwischen 0 und 1, um es einzuschalten (zum Beispiel erfasst 0.05 5 % der Vorgänge), und verwende ein Ziel, das Sentry-Transaktionen annimmt. Erstelle die Backend-API- und Worker-Dienste nach der Änderung neu. Wähle Raten passend zu deinem Überwachungsbudget; mit der Backend-Rate 0 deaktivierst du Spans, während die Fehlererfassung aktiv bleibt.

Backend-Spans messen die Bearbeitung von HTTP-Anfragen und die Ausführung von Hintergrundjobs. Ein Job enthält untergeordnete Spans für die Drain-Prüfung, den Handler oder die Übergabe. Zustandsprüfungen und Metrikabfragen sind ausgenommen; HTTP-Spans messen nicht die Lebensdauer eines gestreamten Antwortinhalts. Span-Namen verwenden Routenklassen und registrierte Warteschlangennamen. Spans enthalten weder Anfrage- und Job-Inhalte noch SQL-Text, Kennungen, URLs, Benutzerkontext oder Breadcrumbs. Ausgehende Anfragen tragen keine Trace-Header. Agentenarbeit enthält außerdem untergeordnete Spans für Belegen, Gateway-Bereitstellung, Staging, Ausführung, Persistierung und Harvest. Sie verwenden feste Namen und enthalten keine Prompts, Dateipfade oder Zugangsdaten.

Backend-Ereignisse enthalten nie Cookies oder Inhalte der Anfrage. Autorisierungs-, Cookie-, API-Schlüssel-, Token-, Secret- und Sitzungs-Header, Webhook- und Freigabe-Tokens in URLs sowie Zugangswerte in Abfrageparametern wie OAuth-Codes werden vor dem Senden durch [Filtered] ersetzt. Stackframes und Fehlermeldungen werden unverändert übertragen; berücksichtige bei der Zielwahl deine Vorgaben zur Datenverarbeitung.

Ein Neustart der Datenbank gilt nicht als Fehler; ein verwaltetes Upgrade erstellt die Datenbank bei jedem Release neu. Solange sie nicht erreichbar ist, antworten Anfragen mit 503 DATABASE_UNAVAILABLE und Retry-After, Hintergrundjobs schlagen fehl und werden nach der Richtlinie ihrer Warteschlange wiederholt, und offene Live-Update-Streams warten ab und laufen danach weiter. Stattdessen landet jeweils eine Warnung im Protokoll. Die Job-Warteschlange schreibt für den ganzen Ausfall nur eine, nicht eine für jede fehlgeschlagene Abfrage. Bleibt die Datenbank länger als etwa eine Minute unerreichbar, sendet ein API-Prozess mit offenen Live-Update-Streams für diesen Ausfall ein einziges Ereignis der Stufe „warning“. Ein Backend-Prozess, der startet, während die Datenbank nicht erreichbar ist, oder sie verliert, bevor seine Job-Warteschlange läuft, wartet bis zu etwa einer Minute auf sie, statt sich zu beenden, und schreibt für jeden neuen Versuch eine Warnung ins Protokoll. Ist die Datenbank danach noch immer nicht erreichbar, schlägt der Start fehl und wird als Fehler gemeldet. Ein falscher Host oder Port in DATABASE_URL lässt den Start deshalb erst nach etwa einer Minute fehlschlagen.

Auch eine Anfrage, die ihr Client aufgegeben hat, meldet das Backend nicht. Das passiert etwa, wenn du einen Browser-Tab schließt oder einen Upload abbrichst, während die Daten noch übertragen werden. Die Anfrage erhält den Status 499, zählt in den Anfragemetriken zu den Clientfehlern und hinterlässt eine einzige Debug-Zeile im Protokoll. Jeder andere Fehler in einer Anfrage, deren Client nicht mehr verbunden ist, wird weiterhin gemeldet. Eine App-Anfrage mit leerem oder abgeschnittenem JSON-Body beantwortet das Backend mit 400 INVALID_JSON, ohne sie zu melden.

Fehler, die auf keinen Defekt in Tale hinweisen, meldet der Browser nicht:

• Fehler aus einer Browsererweiterung
• Anfragen, die die Seite selbst abgebrochen hat, etwa weil du sie vor dem vollständigen Laden verlassen hast
• Anfragen, die das Backend mit einem Status unter 500 ablehnt, etwa bei fehlender Berechtigung oder einem bereits vergebenen Namen
• Anfragen, die gar keine Antwort erhalten, zum Beispiel weil das Gerät offline ist
• Anfragen, die fehlschlagen, während die Plattform oder ihre Datenbank neu startet: UPSTREAM_UNAVAILABLE vom Proxy während eines Deployments oder Neustarts und 503 DATABASE_UNAVAILABLE von der Plattform

Andere Serverfehler ab Status 500 meldet er weiterhin.

Aggregierte Nutzungsstatistik mit Umami

Die Erfassung ist standardmäßig ausgeschaltet. Du aktivierst sie für jedes Deployment getrennt mit UMAMI_URL, UMAMI_WEBSITE_ID und UMAMI_PROXY_TOKEN; die Umgebungsreferenz beschreibt die Werte. Verwende je Deployment eine eigene Website-ID. Erstelle den betroffenen Produktionsdienst mit den neuen Umgebungswerten neu; ein neues Image ist nicht nötig. Leere zum Abschalten die Website-ID und wende die Änderung genauso an. Der Vite-Entwicklungsserver stellt diese Konfiguration nicht bereit.

Der Browser lädt den Umami-Tracker von seiner eigenen Origin unter /_a/script.js und sendet ausgewählte Ereignisse an /_a/api/send. Ein konfigurierter Basispfad steht vor diesen URLs. Nur Website-ID und Proxy-Pfad gelangen in die Browserkonfiguration; Origin und Bearer-Token der Erfassung bleiben auf dem Server.

UMAMI_URL muss auf ein Gateway zeigen, das GET /_collect/script.js und POST /_collect/api/send mit diesem Bearer-Token authentifiziert. Die URL eines normalen Umami-Dashboards allein erfüllt diese Anforderungen nicht. Caddy muss X-Analytics-Client-IP aus einer vertrauenswürdigen Client-Adresse neu setzen. Halte die Anwendungsports privat und konfiguriere vertrauenswürdige Proxy-Netze, wenn ein weiterer Proxy vorgeschaltet ist. Der Server leitet die geprüfte IP-Adresse, den User-Agent des Browsers und die nötigen Umami-Header weiter; Browser-Cookies, Zugangsdaten und Referrer-Header entfernt er.

Die Berichte enthalten bekannte öffentliche Seitenpfade oder private Routenvorlagen der Plattform, Referrer-Origins, Browsersprache, Bildschirmgröße, Browser, Betriebssystem, Gerät und ungefähren Standort. Die Erfassung leitet Besuche und Standort aus der IP-Adresse ab, ohne die ursprüngliche Adresse zu speichern. Platzhalter ersetzen private Organisations- und Ressourcen-IDs. Seitentitel, Suchparameter, Fragmente, Formularfelder und Produktinhalte sind ausgeschlossen. Die Marketing-Seite zählt zusätzlich abgeschlossene Kontakt- und Demo-Anfragen ohne deren Inhalt. Es gibt keine websiteübergreifende Identität, automatische Klickerfassung oder Sitzungsaufzeichnung. Do Not Track und Global Privacy Control deaktivieren die Erfassung.

Prüfe nach dem Rollout das Verhalten mit einem Browser, der die Erfassung zulässt:

1. Öffne eine bekannte Seite, wechsle zu einer anderen und prüfe beide Seitenaufrufe in der Umami-Website des Deployments.
2. Prüfe den Anfrageinhalt. Private Routen enthalten Platzhalter, aber keine Suchparameter, Titel oder Formulardaten.
3. Aktiviere Do Not Track oder Global Privacy Control und prüfe, dass die Erfassung stoppt.
4. Blockiere die Erfassung oder teste einen Ausfall. Die normale Navigation muss weiter funktionieren.

Grenzen kennen

Tale exportiert derzeit keine OpenTelemetry-Traces über OTLP. Ein OpenTelemetry Collector kann die Prometheus-Messwerte erfassen. Aus dem Abfragen von Messwerten entstehen aber keine verteilten Traces. Dafür braucht die Anwendung zusätzlich eine entsprechende Instrumentierung.

Alarmgrenzen und Reaktionsabläufe findest du unter Betrieb. Bei einem ausgefallenen Dienst helfen die Symptomtabellen der Fehlersuche.