Observabilita
Libre WebUI nabízí operátorům dvě cesty observability:
- strukturované aplikační protokoly zapisované místně na standardní výstup a chybu;
- volitelný exportér OpenTelemetry pro požadavky HTTP, trvalé úlohy, počitadla a záznamy varování či chyb.
Žádná cesta neposílá telemetrii projektu Libre WebUI. OpenTelemetry je vypnutá, dokud operátor nenastaví koncový bod kolektoru. Stránky správce System a Usage jsou oddělené: čtou diagnostiku a používání modelů či poskytovatelů přímo z instalace, nikoli z kolektoru OpenTelemetry.
Strukturované protokoly
Výchozí LOG_FORMAT=text zachovává známý konzolový výstup s rozsahy. Nastavte
LOG_FORMAT=json pro jeden objekt JSON na řádek:
LOG_LEVEL=info
LOG_FORMAT=json
Každý strukturovaný řádek obsahuje:
- časové razítko ISO;
- úroveň a rozsah loggeru;
- zprávu;
- aktuální korelační ID požadavku nebo trvalé úlohy, pokud existuje; a
- omezené strukturované podrobnosti dodané volajícím.
Každý požadavek HTTP dostane X-Request-Id. Libre přijme příchozí ID jen tehdy, když
má 8–64 písmen, číslic nebo znaků ., _, -; jinak vytvoří UUID. ID se vrátí v
odpovědi a sleduje asynchronní práci v kontextu protokolování. Přístupové protokoly
zaznamenají metodu HTTP, cestu, stav a dobu trvání, ale odstraní řetězec dotazu, protože
parametry mohou obsahovat uživatelský obsah či krátkodobé přihlašovací údaje.
LOG_LEVEL přijímá silent, error, warn, info nebo debug. Ladicí protokolování
může odhalit více provozních detailů; zapínejte ho jen při diagnostice a chraňte výstup
stejně jako jiná instalační data.
Hranice redigování
Strukturované podrobnosti a exportovaná telemetrie procházejí stejnou omezenou pomocnou funkcí redigování:
- pole s názvy připomínajícími hesla, tajemství, tokeny, klíče, autorizaci, cookies, přihlašovací údaje, bearer hodnoty nebo JWT se vynechají;
- řetězce se omezí na 512 znaků;
- pole, hloubka vnoření a počet exportovaných atributů jsou omezené; a
- chybové objekty si zachovají název a omezenou zprávu, nikoli libovolný graf objektů.
Jde o obranu do hloubky, ne povolení protokolovat prompty nebo tajemství. Krátký text uživatele bez názvu pole připomínajícího tajemství může stále vstoupit do protokolu. Rozšíření by měla zapisovat identifikátory a výsledky, nikoli těla požadavků, prompty, text dokumentů, výsledky nástrojů či obsah poskytovatelů. Omezte přístup k protokolům a uplatněte operátorem řízenou dobu uchovávání.
Zapnutí OpenTelemetry
Libre exportuje OTLP/HTTP JSON přímo, bez závislosti na sadě SDK OpenTelemetry. Nasměrujte ho na základní HTTP URL kolektoru, který přijímá standardní cesty signálů:
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer example-collector-token
OTEL_SERVICE_NAME=libre-webui
Exportér přidá k základní URL /v1/traces, /v1/metrics a /v1/logs.
OTEL_EXPORTER_OTLP_HEADERS je čárkami oddělený seznam párů key=value. Přihlašovací
údaje kolektoru ukládejte jako instalační tajemství a nevkládejte je do repozitáře.
Výchozí OTEL_SERVICE_NAME je libre-webui.
Když proměnná koncového bodu chybí, zaznamenávání spanů, metrik a protokolů nic nedělá a nic neopustí proces. V týmové instalaci exportují aplikační a externí worker procesy nezávisle, proto každému dejte odpovídající konfiguraci kolektoru. Samostatný název služby pro role může zpřehlednit řídicí panely.
Exportované signály
| Signál | Co Libre zaznamenává |
|---|---|
| Spany serveru HTTP | Metoda a cesta bez řetězce dotazu, stav odpovědi, doba trvání, úspěch či selhání a ID požadavku |
| Počitadla HTTP | Monotónní počet požadavků podle metody a třídy stavu odpovědi |
| Spany trvalých úloh | Typ úlohy, číslo pokusu, doba trvání a stav úspěchu či selhání |
| Počitadla trvalých úloh | Monotónní počet spuštění podle typu a výsledku |
| Záznamy protokolu | Redigovaná varování a chyby s rozsahem loggeru a korelačními ID požadavku či úlohy |
Spany jsou místní dokončené spany. Libre nyní nešíří příchozího rodiče trasování OpenTelemetry, nevytváří stromy nadřazených a podřízených spanů mezi službami a neinstrumentuje vykreslování prohlížeče ani každé volání poskytovatele. Používání tokenů a médií patří místo toho do místních knih Usage Analytics a Cost Governance.
Chování doručování
Telemetrie je záměrně bez záruky doručení:
- vyrovnávací paměti obsahují nejvýše 2 048 spanů a 2 048 záznamů a při tlaku odstraní nejstarší;
- uchovává se nejvýše 512 řad počitadel;
- exportér vyprazdňuje přibližně každých pět sekund;
- každý export HTTP má třísekundový časový limit; a
- chyba kolektoru danou dávku zahodí a nikdy nezablokuje ani nezpůsobí selhání aplikačního požadavku či trvalé úlohy.
Exportér proto není auditní protokol ani trvalý účetní systém. Pro bezpečnostní události používejte append-only bezpečnostní audit, pro náklady knihu SQL používání a pro telemetrii vlastní uchovávání a upozornění kolektoru.
Řešení problémů
Žádná telemetrie nepřichází. Ověřte, že OTEL_EXPORTER_OTLP_ENDPOINT existuje v
prostředí přesného aplikačního nebo worker procesu, obsahuje jen základní URL kolektoru
a kolektor přijímá OTLP/HTTP JSON na třech standardních cestách.
Kolektor vrací neoprávněný přístup. Zkontrolujte syntaxi čárkami oddělených hlaviček
a zda kolektor očekává authorization=Bearer ... nebo jinou hlavičku. Po změně
proměnných prostředí proces restartujte.
Požadavky uspějí i při nedostupném kolektoru. Jde o očekávané chování. Exportní cesta selhává otevřeně kvůli dostupnosti aplikace a neukládá neúspěšné dávky k opakování.
Pole protokolu chybí nebo je zkrácené. Klíče připomínající tajemství se odstraní a dlouhé či hluboce vnořené hodnoty jsou záměrně omezené. Protokolujte bezpečný identifikátor nebo souhrn namísto oslabení hranice redigování.