Observerbarhet
Libre WebUI ger operatörer två vägar för observerbarhet:
- strukturerade programloggar som skrivs lokalt till standardutdata och standardfel;
- en valfri OpenTelemetry-exportör för HTTP-förfrågningar, beständiga jobb, räknare samt varnings- och felloggar.
Ingen av vägarna skickar telemetri till Libre WebUI-projektet. OpenTelemetry är avstängt tills en operatör konfigurerar en insamlarslutpunkt. Administratörssidorna för System och Usage är separata: de läser diagnostik och modell-/leverantörsanvändning från själva installationen, inte från en OpenTelemetry-insamlare.
Strukturerade loggar
Standardvärdet LOG_FORMAT=text behåller det välkända avgränsade konsolresultatet.
Ange LOG_FORMAT=json för ett JSON-objekt per rad:
LOG_LEVEL=info
LOG_FORMAT=json
Varje strukturerad rad innehåller:
- en ISO-tidsstämpel;
- nivå och loggningsomfång;
- ett meddelande;
- aktuellt korrelations-ID för förfrågan eller det beständiga jobbet, när det finns; och
- begränsade strukturerade detaljer från anroparen.
Varje HTTP-förfrågan får ett X-Request-Id. Libre accepterar ett inkommande ID
endast när det består av 8–64 bokstäver, siffror, ., _ eller -; annars skapas
ett UUID. ID:t returneras i svaret och följer asynkront arbete genom loggkontexten.
Åtkomstloggar registrerar HTTP-metod, sökväg, status och varaktighet, men tar bort
frågesträngen eftersom frågeparametrar kan innehålla användarinnehåll eller
kortlivade uppgifter.
LOG_LEVEL accepterar silent, error, warn, info eller debug. Felsökningsloggning
kan visa fler driftdetaljer. Aktivera den endast medan du diagnostiserar ett problem
och skydda loggarna som andra distributionsdata.
Sekretessfiltreringsgräns
Strukturerade detaljer och exporterad telemetri går genom samma begränsade sekretessfiltreringsfunktion:
- fält vars namn liknar lösenord, hemligheter, token, nycklar, auktorisering, cookies, uppgifter, bearer-värden eller JWT utelämnas;
- strängar begränsas till 512 tecken;
- arrayer, nästlingsdjup och antalet exporterade attribut begränsas; och
- felobjekt behåller sitt namn och ett begränsat meddelande, inte en godtycklig objektgraf.
Detta är försvar på djupet, inte tillstånd att logga promptar eller hemligheter. En kort användarangiven sträng utan ett hemlighetsliknande fältnamn kan fortfarande bli vanlig loggtext. Programtillägg bör logga identifierare och utfall i stället för förfrågningskroppar, promptar, dokumenttext, verktygsresultat eller leverantörsdata. Begränsa loggåtkomsten och tillämpa en operatörshanterad lagringspolicy.
Aktivera OpenTelemetry
Libre exporterar OTLP/HTTP JSON direkt, utan att lägga till ett beroende av en OpenTelemetry-SDK. Rikta den mot HTTP-bas-URL:en för en insamlare som accepterar standardsökvägarna för signaler:
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ören lägger till /v1/traces, /v1/metrics och /v1/logs efter bas-URL:en.
OTEL_EXPORTER_OTLP_HEADERS är en kommaseparerad lista med key=value-par.
Lagra insamlaruppgifter som distributionshemligheter och versionshantera dem inte.
OTEL_SERVICE_NAME har standardvärdet libre-webui.
När slutpunktsvariabeln saknas gör registrering av spann, mätvärden och loggar ingenting, och ingenting lämnar processen. I en teaminstallation exporterar program- och externa workerprocesser oberoende, så ge varje process den insamlarkonfiguration som den ska använda. Ett eget tjänstenamn per roll kan göra instrumentpaneler enklare att läsa.
Exporterade signaler
| Signal | Vad Libre registrerar |
|---|---|
| HTTP-serverspann | Metod och sökväg utan frågesträng, svarsstatus, varaktighet, lyckad/misslyckad status och förfrågnings-ID |
| HTTP-räknare | Monotont antal förfrågningar per metod och svarsstatusklass |
| Spann för beständiga jobb | Jobbtyp, försöksnummer, varaktighet och lyckad/misslyckad status |
| Räknare för beständiga jobb | Monotont antal körningar per jobbtyp och utfall |
| Loggposter | Sekretessfiltrerade varnings- och felmeddelanden med loggningsomfång samt korrelations-ID:n för förfrågan/jobb |
Spann är lokala, slutförda spann. Libre vidarebefordrar för närvarande inte en inkommande OpenTelemetry-spårförälder, skapar inte träd med över-/underordnade spann mellan tjänster och instrumenterar inte webbläsarrendering eller varje leverantörsanrop. Modellers token- och medieanvändning hör i stället till de lokala liggarna för användningsanalys och kostnadsstyrning.
Leveransbeteende
Telemetrin levereras avsiktligt utan garanti:
- buffertar innehåller högst 2 048 spann och 2 048 loggposter och släpper den äldsta posten under tryck;
- högst 512 räknarserier behålls;
- exportören tömmer ungefär var femte sekund;
- varje HTTP-export har tre sekunders timeout; och
- ett insamlarfel släpper den omgången och får aldrig en programförfrågan eller ett beständigt jobb att misslyckas.
Exportören är därför inte en granskningslogg eller ett beständigt redovisningssystem. Använd den oföränderliga säkerhetsgranskningsloggen för säkerhetshändelser, SQL-användningsliggaren för kostnader och insamlarens egna policyer för lagring och varningar för telemetri.
Felsökning
Ingen telemetri kommer fram. Bekräfta att OTEL_EXPORTER_OTLP_ENDPOINT finns i
miljön för exakt den program- eller workerprocessen, endast innehåller insamlarens
bas-URL och att insamlaren accepterar OTLP/HTTP JSON på de tre standardsökvägarna.
Insamlaren svarar obehörig. Kontrollera syntaxen för kommaseparerade rubriker och
om insamlaren förväntar sig authorization=Bearer ... eller en annan rubrik.
Starta om processen efter att miljövariablerna ändrats.
Förfrågningar lyckas fortfarande när insamlaren är nere. Detta är förväntat. Exportvägen misslyckas öppet för programmets tillgänglighet och lagrar inte misslyckade omgångar för nya försök.
Ett loggfält saknas eller har kortats. Nycklar som liknar hemligheter tas bort, och långa eller djupt nästlade värden begränsas avsiktligt. Logga en säker identifierare eller sammanfattning i stället för att försvaga sekretessfiltreringsgränsen.