Zum Hauptinhalt springen

Beobachtbarkeit

Libre WebUI bietet Betreibern zwei Pfade:

  • strukturierte Anwendungsprotokolle auf Standardausgabe und -fehler;
  • optionalen OpenTelemetry-Export für HTTP-Anfragen, dauerhafte Jobs, Zähler sowie Warnungs- und Fehlerprotokolle.

Keiner sendet Telemetrie an das Libre WebUI-Projekt. OpenTelemetry bleibt aus, bis ein Collector-Endpunkt konfiguriert ist. Die Administratorseiten System und Nutzung sind getrennt: Sie lesen Diagnose und Nutzung aus der Bereitstellung, nicht aus einem Collector.

Strukturierte Protokolle​

LOG_FORMAT=text behält die vertraute, bereichsbezogene Konsolenausgabe. Setze LOG_FORMAT=json für ein JSON-Objekt je Zeile:

LOG_LEVEL=info
LOG_FORMAT=json

Jede strukturierte Zeile enthält:

  • ISO-Zeitstempel;
  • Ebene und Logger-Bereich;
  • Nachricht;
  • Korrelations-ID der aktuellen Anfrage oder des Jobs, falls vorhanden; und
  • begrenzte strukturierte Details des Aufrufers.

Jede HTTP-Anfrage erhält X-Request-Id. Libre akzeptiert eingehende IDs nur mit 8–64 Zeichen aus Buchstaben, Ziffern, ., _ oder -, sonst wird eine UUID erzeugt. Die ID wird zurückgegeben und folgt asynchroner Arbeit. Zugriffsprotokolle enthalten Methode, Pfad, Status und Dauer ohne Query-String, da dieser Benutzerinhalt oder kurzlebige Anmeldedaten enthalten kann.

LOG_LEVEL akzeptiert silent, error, warn, info und debug. Debug kann mehr Betriebsdetails offenlegen; aktiviere es nur zur Diagnose und schütze die Ergebnisse.

Redaktionsgrenze​

Strukturierte Details und exportierte Telemetrie nutzen denselben begrenzten Helfer:

  • Felder mit Namen ähnlich Passwörtern, Geheimnissen, Tokens, Schlüsseln, Autorisierung, Cookies, Anmeldedaten, Bearer-Werten oder JWTs werden entfernt;
  • Zeichenketten sind auf 512 Zeichen begrenzt;
  • Arrays, Tiefe und Attributanzahl sind begrenzt; und
  • Fehler behalten Name und begrenzte Nachricht, nicht beliebige Objektgraphen.

Das ist Tiefenverteidigung, keine Erlaubnis zum Protokollieren von Prompts oder Geheimnissen. Kurzer Benutzertext in einem unauffälligen Feld kann weiterhin normal erscheinen. Erweiterungen sollten IDs und Ergebnisse statt Bodies, Prompts, Dokumenttext, Werkzeugergebnissen oder Anbieternutzlasten protokollieren. Begrenze Zugriff und wende Aufbewahrung an.

OpenTelemetry aktivieren​

Libre exportiert OTLP/HTTP JSON direkt, ohne OpenTelemetry-SDK-Abhängigkeit. Gib die HTTP-Basis-URL eines Collectors mit Standardpfaden an:

OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer example-collector-token
OTEL_SERVICE_NAME=libre-webui

Der Exporter hängt /v1/traces, /v1/metrics und /v1/logs an. OTEL_EXPORTER_OTLP_HEADERS ist eine kommagetrennte Liste von key=value-Paaren. Speichere Zugangsdaten als Bereitstellungsgeheimnisse und committe sie nicht. OTEL_SERVICE_NAME ist standardmäßig libre-webui.

Ohne Endpunktvariable sind Spans, Metriken und Logs No-ops; nichts verlässt den Prozess. In Team-Bereitstellungen exportieren Anwendung und externe Worker unabhängig. Gib jedem die nötige Konfiguration; getrennte Dienstnamen erleichtern Dashboards.

Exportierte Signale​

SignalAufgezeichnete Daten
HTTP-Server-SpansMethode und Pfad ohne Query, Antwortstatus, Dauer, Erfolg/Fehler und Anfrage-ID
HTTP-ZählerMonotone Anzahl nach Methode und Statusklasse
Dauerhafte Job-SpansJobtyp, Versuch, Dauer und Erfolg/Fehler
Dauerhafte Job-ZählerMonotone Anzahl nach Jobtyp und Ergebnis
ProtokolleRedigierte Warnungen/Fehler mit Logger-Bereich und Korrelations-IDs

Spans sind lokale abgeschlossene Spans. Libre propagiert derzeit keinen eingehenden Trace-Parent, erstellt keine Dienstbäume und instrumentiert weder Browserrendering noch jeden Anbieteraufruf. Token- und Mediennutzung gehört stattdessen in die lokalen Ledger Nutzungsanalyse und Kosten-Governance.

Übertragungsverhalten​

Telemetrie arbeitet bewusst nach bestem Bemühen:

  • Puffer halten höchstens 2,048 Spans und 2,048 Protokolle und verwerfen unter Druck den ältesten Eintrag;
  • höchstens 512 Zählerserien bleiben erhalten;
  • der Exporter leert ungefähr alle fünf Sekunden;
  • jeder HTTP-Export hat drei Sekunden Zeit; und
  • ein Collector-Fehler verwirft die Charge, ohne Anfrage oder Job zu blockieren.

Der Exporter ist daher kein Auditprotokoll oder dauerhaftes Abrechnungssystem. Nutze das nur anhängbare Sicherheitsaudit, das SQL-Nutzungsledger für Kosten und die Aufbewahrung und Warnungen des Collectors für Telemetrie.

Fehlerbehebung​

Keine Telemetrie. Bestätige OTEL_EXPORTER_OTLP_ENDPOINT in der Umgebung des genauen Prozesses, nur mit Basis-URL, und die Annahme von OTLP/HTTP JSON auf allen drei Pfaden.

Collector meldet nicht autorisiert. Prüfe die kommagetrennte Header-Syntax und ob authorization=Bearer ... oder ein anderer Header erwartet wird. Starte nach Variablenänderungen neu.

Anfragen funktionieren bei Ausfall weiter. Das ist erwartet. Der Exportpfad fällt offen aus und speichert fehlgeschlagene Chargen nicht.

Feld fehlt oder ist gekürzt. Geheimnisähnliche Schlüssel werden entfernt und lange oder tiefe Werte begrenzt. Protokolliere eine sichere Kennung oder Zusammenfassung.

Verwandte Dokumentation​