Obserwowalność
Libre WebUI zapewnia operatorom dwie ścieżki:
- ustrukturyzowane dzienniki aplikacji zapisywane lokalnie do standardowego wyjścia i błędów;
- opcjonalny eksporter OpenTelemetry dla żądań HTTP, trwałych zadań, liczników i rekordów ostrzeżeń/błędów.
Żadna ścieżka nie wysyła telemetrii do projektu Libre WebUI. OpenTelemetry jest wyłączone do ustawienia kolektora. Administracyjne strony System i Użycie są osobne: czytają diagnostykę i użycie z wdrożenia, nie kolektora.
Ustrukturyzowane dzienniki
Domyślne LOG_FORMAT=text zachowuje zwykłe wyjście konsoli. Ustaw LOG_FORMAT=json, aby otrzymać obiekt JSON na wiersz:
LOG_LEVEL=info
LOG_FORMAT=json
Każdy wiersz zawiera:
- znacznik czasu ISO;
- poziom i zakres loggera;
- komunikat;
- identyfikator korelacji żądania lub trwałego zadania, jeśli istnieje; oraz
- ograniczone ustrukturyzowane szczegóły wywołującego.
Każde żądanie HTTP dostaje X-Request-Id. Libre akceptuje przychodzący ID tylko, gdy ma 8–64 znaków: litery, cyfry, ., _ lub -; inaczej tworzy UUID. ID wraca w odpowiedzi i podąża za pracą asynchroniczną. Dzienniki dostępu zapisują metodę, ścieżkę, stan i czas, bez query string, bo parametry mogą zawierać treść użytkownika lub krótkotrwałe poświadczenia.
LOG_LEVEL przyjmuje silent, error, warn, info albo debug. Debug może ujawnić więcej szczegółów; włączaj tylko do diagnostyki i chroń dzienniki jak inne dane wdrożenia.
Granica redakcji
Szczegóły i telemetria przechodzą przez ten sam ograniczający mechanizm:
- pola przypominające hasła, sekrety, tokeny, klucze, autoryzację, ciasteczka, poświadczenia, bearer lub JWT są pomijane;
- ciągi mają maksymalnie 512 znaków;
- tablice, głębokość i liczba atrybutów są ograniczone; oraz
- błędy zachowują nazwę i ograniczony komunikat, nie dowolny graf.
To obrona warstwowa, nie zgoda na logowanie promptów lub sekretów. Krótki tekst użytkownika bez podejrzanej nazwy może nadal trafić do logu. Rozszerzenia powinny zapisywać identyfikatory i wyniki zamiast treści żądań, promptów, dokumentów, narzędzi lub dostawców. Ogranicz dostęp i stosuj retencję operatora.
Włączanie OpenTelemetry
Libre eksportuje OTLP/HTTP JSON bez zależności od SDK OpenTelemetry. Wskaż bazowy HTTP URL kolektora przyjmującego standardowe ścieżki:
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer example-collector-token
OTEL_SERVICE_NAME=libre-webui
Eksporter dodaje /v1/traces, /v1/metrics i /v1/logs. OTEL_EXPORTER_OTLP_HEADERS to lista key=value oddzielona przecinkami. Poświadczenia kolektora przechowuj jako sekrety wdrożenia; nie commituj. Domyślne OTEL_SERVICE_NAME to libre-webui.
Bez zmiennej punktu zapisywanie spanów, metryk i logów nic nie robi i nic nie opuszcza procesu. W zespole aplikacja i zewnętrzny worker eksportują niezależnie, więc ustaw każdy proces osobno. Różne nazwy usług ułatwiają pulpity.
Eksportowane sygnały
| Sygnał | Co zapisuje Libre |
|---|---|
| Spany serwera HTTP | Metoda i ścieżka bez query, stan odpowiedzi, czas, sukces/błąd i ID żądania |
| Liczniki HTTP | Monotoniczna liczba żądań według metody i klasy odpowiedzi |
| Spany trwałych zadań | Typ, numer próby, czas i sukces/błąd |
| Liczniki trwałych zadań | Monotoniczna liczba według typu i wyniku |
| Rekordy logów | Zredagowane ostrzeżenia/błędy z zakresem i ID korelacji |
Spany są lokalnie zakończone. Libre obecnie nie propaguje przychodzącego trace parent, nie buduje drzew między usługami i nie instrumentuje renderowania przeglądarki ani każdego dostawcy. Tokeny modeli i multimedia należą do lokalnych rejestrów Analizy użycia i Zarządzania kosztami.
Zachowanie dostarczania
Telemetria celowo działa best-effort:
- bufory mieszczą 2,048 spanów i 2,048 rekordów, usuwając najstarsze pod presją;
- przechowywane są maksymalnie 512 serie liczników;
- opróżnianie następuje co około pięć sekund;
- eksport HTTP ma trzysekundowy limit; oraz
- błąd kolektora usuwa partię i nigdy nie blokuje żądania ani zadania.
Eksporter nie jest dziennikiem audytu ani trwałą księgowością. Użyj dopisywanego dziennika bezpieczeństwa, rejestru SQL dla kosztów oraz retencji i alertów kolektora.
Rozwiązywanie problemów
Brak telemetrii. Sprawdź OTEL_EXPORTER_OTLP_ENDPOINT w dokładnym procesie aplikacji/workera, tylko bazowy URL i obsługę OTLP/HTTP JSON na trzech ścieżkach.
Kolektor odrzuca autoryzację. Sprawdź składnię nagłówków i wymaganie authorization=Bearer ... lub innego nagłówka. Uruchom proces ponownie po zmianie.
Żądania działają mimo awarii kolektora. To oczekiwane. Eksport fail-open chroni dostępność i nie utrwala nieudanych partii.
Pole logu znikło lub skrócono. Podejrzane klucze są usuwane, a długie/głębokie wartości ograniczane. Zapisz bezpieczny identyfikator lub podsumowanie zamiast osłabiać redakcję.