Observerbarhed
Libre WebUI giver operatører to veje til observerbarhed:
- strukturerede programlogfiler, der skrives lokalt til standardoutput og standardfejl;
- en valgfri OpenTelemetry-eksportør til HTTP-anmodninger, vedvarende jobs, tællere samt advarsels- og fejllogposter.
Ingen af vejene sender telemetri til Libre WebUI-projektet. OpenTelemetry er slået fra, indtil en operatør konfigurerer et indsamlingsslutpunkt. Administratorsiderne for System og Usage er separate: De læser diagnostik og model-/udbyderbrug fra selve installationen, ikke fra en OpenTelemetry-indsamler.
Strukturerede logfiler
Standardværdien LOG_FORMAT=text bevarer det velkendte afgrænsede konsoloutput.
Angiv LOG_FORMAT=json for ét JSON-objekt pr. linje:
LOG_LEVEL=info
LOG_FORMAT=json
Hver struktureret linje indeholder:
- et ISO-tidsstempel;
- niveau og loggerområde;
- en besked;
- det aktuelle korrelations-ID for anmodningen eller det vedvarende job, hvis det findes; og
- afgrænsede strukturerede detaljer fra kalderen.
Hver HTTP-anmodning får et X-Request-Id. Libre accepterer kun et indgående ID,
når det består af 8–64 bogstaver, cifre, ., _ eller -; ellers oprettes et UUID.
ID'et returneres i svaret og følger asynkront arbejde gennem logkonteksten.
Adgangslogfiler registrerer HTTP-metode, sti, status og varighed, men fjerner query-
strengen, fordi queryparametre kan indeholde brugerindhold eller kortlivede
legitimationsoplysninger.
LOG_LEVEL accepterer silent, error, warn, info eller debug. Debuglogning
kan vise flere driftsdetaljer. Aktivér den kun under diagnosticering af et problem,
og beskyt logfilerne som andre installationsdata.
Grænse for fortrolighedsfiltrering
Strukturerede detaljer og eksporteret telemetri går gennem den samme afgrænsede fortrolighedsfiltrering:
- felter, hvis navne ligner adgangskoder, hemmeligheder, tokens, nøgler, godkendelse, cookies, legitimationsoplysninger, bearer-værdier eller JWT'er, udelades;
- strenge begrænses til 512 tegn;
- arrays, indlejringsdybde og antal eksporterede attributter begrænses; og
- fejlobjekter beholder deres navn og en afgrænset besked, ikke en vilkårlig objektgraf.
Dette er forsvar i dybden, ikke tilladelse til at logge prompter eller hemmeligheder. En kort brugerangivet streng uden et hemmelighedslignende feltnavn kan stadig blive almindelig logtekst. Programudvidelser bør logge identifikatorer og resultater i stedet for anmodningsbodyer, prompter, dokumenttekst, værktøjsresultater eller udbyderpayloads. Begræns adgangen til logfiler, og anvend en operatørstyret opbevaringspolitik.
Aktivér OpenTelemetry
Libre eksporterer OTLP/HTTP JSON direkte uden at tilføje en afhængighed af en OpenTelemetry-SDK. Peg den på HTTP-basis-URL'en for en indsamler, der accepterer standardsignalstierne:
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer example-collector-token
OTEL_SERVICE_NAME=libre-webui
Eksportøren føjer /v1/traces, /v1/metrics og /v1/logs til basis-URL'en.
OTEL_EXPORTER_OTLP_HEADERS er en kommasepareret liste af key=value-par.
Gem indsamlerens legitimationsoplysninger som installationshemmeligheder, og commit
dem ikke. OTEL_SERVICE_NAME har standardværdien libre-webui.
Når slutpunktsvariablen mangler, gør registrering af spans, målinger og logposter intet, og intet forlader processen. I en teaminstallation eksporterer program- og eksterne workerprocesser uafhængigt, så giv hver proces den indsamlerkonfiguration, den skal bruge. Et særskilt tjenestenavn pr. rolle kan gøre dashboards nemmere at læse.
Eksporterede signaler
| Signal | Hvad Libre registrerer |
|---|---|
| HTTP-serverspans | Metode og sti uden querystreng, svarstatus, varighed, succes-/fejlstatus og anmodnings-ID |
| HTTP-tællere | Monotont antal anmodninger pr. metode og svarstatusklasse |
| Spans for vedvarende jobs | Jobtype, forsøgsnummer, varighed og succes-/fejlstatus |
| Tællere for vedvarende jobs | Monotont antal kørsler pr. jobtype og resultat |
| Logposter | Fortrolighedsfiltrerede advarsels- og fejlbeskeder med loggerområde samt korrelations-ID'er for anmodning/job |
Spans er lokale, afsluttede spans. Libre videresender i øjeblikket ikke en indgående OpenTelemetry-traceparent, opretter ikke træer af over-/underordnede spans på tværs af tjenester og instrumenterer ikke browsergengivelse eller hvert udbyderkald. Modellers token- og mediebrug hører i stedet til de lokale journaler for brugsanalyse og omkostningsstyring.
Leveringsadfærd
Telemetri leveres bevidst uden garanti:
- buffere rummer højst 2.048 spans og 2.048 logposter og dropper den ældste post under pres;
- højst 512 tællerserier bevares;
- eksportøren tømmer cirka hvert femte sekund;
- hver HTTP-eksport har tre sekunders timeout; og
- en indsamlerfejl dropper den batch og får aldrig en programanmodning eller et vedvarende job til at mislykkes.
Eksportøren er derfor ikke en auditlog eller et vedvarende regnskabssystem. Brug den append-only sikkerhedsauditlog til sikkerhedshændelser, SQL-brugsjournalen til omkostninger og indsamlerens egne politikker for opbevaring og alarmering til telemetri.
Fejlfinding
Ingen telemetri ankommer. Bekræft, at OTEL_EXPORTER_OTLP_ENDPOINT findes i
miljøet for præcis den program- eller workerproces, kun indeholder indsamlerens
basis-URL, og at indsamleren accepterer OTLP/HTTP JSON på de tre standardstier.
Indsamleren svarer ikke godkendt. Kontrollér syntaksen for kommaseparerede headere,
og om indsamleren forventer authorization=Bearer ... eller en anden header.
Genstart processen efter ændring af miljøvariabler.
Anmodninger lykkes stadig, mens indsamleren er nede. Det er forventet. Eksportvejen fejler åbent af hensyn til programmets tilgængelighed og gemmer ikke mislykkede batches til nye forsøg.
Et logfelt mangler eller er forkortet. Nøgler, der ligner hemmeligheder, fjernes, og lange eller dybt indlejrede værdier begrænses med vilje. Log en sikker identifikator eller et resumé i stedet for at svække grænsen for fortrolighedsfiltrering.