Observeerbaarheid
Libre WebUI biedt operators twee paden voor observeerbaarheid:
- gestructureerde toepassingslogs die lokaal naar standaarduitvoer en standaardfout worden geschreven;
- een optionele OpenTelemetry-exporter voor HTTP-verzoeken, duurzame taken, tellers en logrecords voor waarschuwingen/fouten.
Geen van beide paden stuurt telemetrie naar het Libre WebUI-project. OpenTelemetry staat uit totdat een operator een collectoreindpunt instelt. De beheerderspagina's Systeem en Gebruik staan hier los van: ze lezen diagnose en model-/providergebruik uit de implementatie zelf, niet uit een OpenTelemetry-collector.
Gestructureerde logs
De standaard LOG_FORMAT=text behoudt de vertrouwde console-uitvoer per bereik. Stel LOG_FORMAT=json in voor één JSON-object per regel:
LOG_LEVEL=info
LOG_FORMAT=json
Elke gestructureerde regel bevat:
- een ISO-tijdstempel;
- niveau en loggerbereik;
- een bericht;
- de correlatie-ID van het huidige verzoek of de duurzame taak, als die bestaat; en
- begrensde gestructureerde details van de aanroeper.
Elk HTTP-verzoek krijgt een X-Request-Id. Libre accepteert een inkomende ID alleen wanneer deze 8–64 tekens lang is en bestaat uit letters, cijfers, ., _ of -; anders wordt een UUID gemaakt. De ID wordt in het antwoord teruggestuurd en volgt asynchroon werk via de logcontext. Toegangslogs registreren HTTP-methode, pad, status en duur; de querytekenreeks wordt verwijderd omdat queryparameters gebruikersinhoud of kortlevende referenties kunnen bevatten.
LOG_LEVEL accepteert silent, error, warn, info of debug. Debuglogging kan meer operationele details blootleggen; schakel dit alleen in tijdens diagnose en beveilig de resulterende logs als andere implementatiegegevens.
Redactiegrens
Gestructureerde details en geëxporteerde telemetrie lopen door dezelfde begrensde redactiehelper:
- velden waarvan de naam lijkt op wachtwoorden, geheimen, tokens, sleutels, autorisatie, cookies, referenties, bearer-waarden of JWT's worden weggelaten;
- tekenreeksen worden beperkt tot 512 tekens;
- arrays, nestingsdiepte en aantallen geëxporteerde attributen zijn begrensd; en
- foutobjecten behouden hun naam en een begrensd bericht, geen willekeurige objectgrafiek.
Dit is diepgaande verdediging, geen toestemming om prompts of geheimen te loggen. Een korte, door de gebruiker geleverde tekenreeks zonder een geheimachtige veldnaam kan nog steeds gewone logtekst zijn. Toepassingsuitbreidingen moeten ID's en uitkomsten loggen in plaats van verzoekbody's, prompts, documenttekst, toolresultaten of providerpayloads. Beperk toegang tot logs en pas door de operator beheerd bewaarbeleid toe.
OpenTelemetry inschakelen
Libre exporteert OTLP/HTTP JSON rechtstreeks, zonder een afhankelijkheid van een OpenTelemetry-SDK toe te voegen. Richt het op de HTTP-basis-URL van een collector die de standaard signaalpaden accepteert:
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer example-collector-token
OTEL_SERVICE_NAME=libre-webui
De exporter voegt /v1/traces, /v1/metrics en /v1/logs aan de basis-URL toe. OTEL_EXPORTER_OTLP_HEADERS is een kommagescheiden lijst met paren key=value. Bewaar collectorreferenties als implementatiegeheimen; commit ze niet. OTEL_SERVICE_NAME is standaard libre-webui.
Wanneer de eindpuntvariabele ontbreekt, doen span-, metriek- en logregistratie niets en verlaat niets het proces. In een teamimplementatie exporteren toepassings- en externe workerprocessen onafhankelijk; geef elk proces de collectorconfiguratie die het moet gebruiken. Een aparte servicenaam per rol kan dashboards leesbaarder maken.
Geëxporteerde signalen
| Signaal | Wat Libre vastlegt |
|---|---|
| HTTP-serverspans | Methode en pad zonder querytekenreeks, antwoordstatus, duur, geslaagd/mislukt en verzoek-ID |
| HTTP-tellers | Monotoon verzoekaantal per methode en antwoordstatusklasse |
| Spans van duurzame taken | Taaktype, pogingsnummer, duur en status geslaagd/mislukt |
| Tellers van duurzame taken | Monotoon uitvoeringsaantal per taaktype en uitkomst |
| Logrecords | Geredigeerde waarschuwings- en foutberichten met loggerbereik plus correlatie-ID's van verzoek/taak |
Spans zijn lokaal voltooide spans. Libre draagt momenteel geen inkomende OpenTelemetry-traceparent over, maakt geen ouder-/kindspanbomen tussen services en instrumenteert niet de browserweergave en elke provideraanroep. Gebruik van modeltokens en media hoort in plaats daarvan bij de lokale logboeken voor Gebruiksanalyse en Kostenbeheer.
Leveringsgedrag
Telemetrie werkt bewust op basis van beste inspanning:
- buffers bevatten maximaal 2,048 spans en 2,048 logrecords en verwijderen onder druk de oudste vermelding;
- maximaal 512 tellerreeksen worden bewaard;
- de exporter leegt ongeveer elke vijf seconden;
- elke HTTP-export heeft een time-out van drie seconden; en
- een collectorfout verwijdert die batch en blokkeert of verstoort nooit een toepassingsverzoek of duurzame taak.
De exporter is daarom geen auditlog of duurzaam boekhoudsysteem. Gebruik het alleen-aanvullen beveiligingsauditlog voor beveiligingsgebeurtenissen, het SQL-gebruikslogboek voor kosten en de eigen bewaar- en waarschuwingsfuncties van de collector voor telemetrie.
Problemen oplossen
Er komt geen telemetrie aan. Controleer of OTEL_EXPORTER_OTLP_ENDPOINT aanwezig is in de omgeving van het exacte toepassings- of workerproces, alleen de basis-URL van de collector bevat en of de collector OTLP/HTTP JSON op de drie standaardpaden accepteert.
De collector meldt dat toegang niet is toegestaan. Controleer de kommagescheiden headersyntaxis en of de collector authorization=Bearer ... of een andere header verwacht. Start het proces opnieuw nadat je omgevingsvariabelen hebt gewijzigd.
Verzoeken blijven slagen terwijl de collector niet beschikbaar is. Dit is verwacht. Het exportpad faalt open om de toepassing beschikbaar te houden en bewaart mislukte batches niet om opnieuw te proberen.
Een logveld ontbreekt of is ingekort. Geheimachtige sleutels worden verwijderd en lange of diep geneste waarden zijn bewust begrensd. Log een veilige ID of samenvatting in plaats van de redactiegrens te verzwakken.