Osservabilità
Libre WebUI offre due percorsi di osservabilità rivolti agli operatori:
- log strutturati dell'applicazione, scritti localmente negli output standard e di errore;
- un esportatore OpenTelemetry facoltativo per richieste HTTP, processi permanenti, contatori e record di log di avviso/errore.
Nessuno dei due percorsi invia telemetria al progetto Libre WebUI. OpenTelemetry resta disattivato finché un operatore non configura l'endpoint di un collector. Le pagine amministrative Sistema e Utilizzo sono separate: leggono la diagnostica e l'utilizzo di modelli/provider dal deployment stesso, non da un collector OpenTelemetry.
Log strutturati
Il valore predefinito LOG_FORMAT=text mantiene il consueto output della console suddiviso per ambito. Imposta LOG_FORMAT=json per ottenere un oggetto JSON per riga:
LOG_LEVEL=info
LOG_FORMAT=json
Ogni riga strutturata contiene:
- un timestamp ISO;
- livello e ambito del logger;
- un messaggio;
- l'ID di correlazione della richiesta corrente o del processo permanente, quando esiste; e
- dettagli strutturati e limitati forniti dal chiamante.
Ogni richiesta HTTP riceve un X-Request-Id. Libre accetta un ID in ingresso soltanto se è lungo 8–64 caratteri ed è composto da lettere, cifre, ., _ o -; altrimenti crea un UUID. L'ID viene restituito nella risposta e segue il lavoro asincrono nel contesto dei log. I log di accesso registrano metodo HTTP, percorso, stato e durata, rimuovendo la stringa di query perché i parametri della query possono contenere dati dell'utente o credenziali di breve durata.
LOG_LEVEL accetta silent, error, warn, info oppure debug. Il logging di debug può esporre più dettagli operativi; abilitalo soltanto durante la diagnosi di un problema e proteggi i log risultanti come gli altri dati del deployment.
Confine di rimozione dei dati
I dettagli strutturati e la telemetria esportata passano attraverso lo stesso helper di rimozione e limitazione:
- i campi i cui nomi assomigliano a password, segreti, token, chiavi, autorizzazioni, cookie, credenziali, valori bearer o JWT vengono omessi;
- le stringhe sono limitate a 512 caratteri;
- array, profondità di annidamento e numero di attributi esportati sono limitati; e
- gli oggetti di errore conservano il proprio nome e un messaggio limitato, non un grafo di oggetti arbitrario.
Questa è una difesa in profondità, non un'autorizzazione a registrare prompt o segreti. Una breve stringa fornita dall'utente senza un nome di campo simile a un segreto può comunque diventare normale testo di log. Le estensioni dell'applicazione dovrebbero registrare identificatori e risultati anziché corpi delle richieste, prompt, testo dei documenti, risultati degli strumenti o payload dei provider. Limita l'accesso ai log e applica criteri di conservazione gestiti dall'operatore.
Abilitare OpenTelemetry
Libre esporta direttamente OTLP/HTTP JSON, senza aggiungere una dipendenza dall'SDK OpenTelemetry. Configura l'URL di base HTTP di un collector che accetta i percorsi standard dei segnali:
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer example-collector-token
OTEL_SERVICE_NAME=libre-webui
L'esportatore aggiunge /v1/traces, /v1/metrics e /v1/logs all'URL di base. OTEL_EXPORTER_OTLP_HEADERS è un elenco separato da virgole di coppie key=value. Archivia le credenziali del collector come segreti del deployment; non eseguirne il commit. Il valore predefinito di OTEL_SERVICE_NAME è libre-webui.
Quando la variabile dell'endpoint è assente, la registrazione di span, metriche e log non esegue alcuna operazione e nulla lascia il processo. In un deployment per team, i processi dell'applicazione e quelli dei worker esterni esportano in modo indipendente: fornisci a ogni processo la configurazione del collector che deve usare. Un nome di servizio distinto per ciascun ruolo può rendere più leggibili i dashboard.
Segnali esportati
| Segnale | Dati registrati da Libre |
|---|---|
| Span del server HTTP | Metodo e percorso senza stringa di query, stato della risposta, durata, stato di riuscita/errore e ID della richiesta |
| Contatori HTTP | Conteggio monotono delle richieste per metodo e classe dello stato della risposta |
| Span dei processi permanenti | Tipo di processo, numero del tentativo, durata e stato di riuscita/errore |
| Contatori dei processi permanenti | Conteggio monotono delle esecuzioni per tipo di processo e risultato |
| Record di log | Messaggi di avviso ed errore con dati rimossi, ambito del logger e ID di correlazione di richiesta/processo |
Gli span sono span locali completati. Attualmente Libre non propaga un trace parent OpenTelemetry in ingresso, non crea alberi di span padre/figlio tra servizi e non strumenta il rendering del browser e ogni chiamata ai provider. L'utilizzo di token dei modelli e di contenuti multimediali appartiene invece ai registri locali delle Analisi dell'utilizzo e della Governance dei costi.
Comportamento della distribuzione
La telemetria è intenzionalmente basata sul massimo impegno:
- i buffer contengono al massimo 2,048 span e 2,048 record di log ed eliminano la voce meno recente quando sono sotto pressione;
- vengono conservate al massimo 512 serie di contatori;
- l'esportatore esegue il flush all'incirca ogni cinque secondi;
- ogni esportazione HTTP ha un timeout di tre secondi; e
- un errore del collector elimina il batch e non blocca né causa mai l'errore di una richiesta dell'applicazione o di un processo permanente.
L'esportatore non è quindi un log di audit né un sistema contabile permanente. Usa il log di audit della sicurezza di sola aggiunta per gli eventi di sicurezza, il registro SQL dell'utilizzo per i costi e le funzioni di conservazione e avviso del collector per la telemetria.
Risoluzione dei problemi
Non arriva telemetria. Verifica che OTEL_EXPORTER_OTLP_ENDPOINT sia presente nell'ambiente dell'esatto processo dell'applicazione o del worker, contenga soltanto l'URL di base del collector e che il collector accetti OTLP/HTTP JSON nei tre percorsi standard.
Il collector restituisce un errore di autorizzazione. Controlla la sintassi dell'elenco di intestazioni separato da virgole e verifica se il collector richiede authorization=Bearer ... o un'altra intestazione. Riavvia il processo dopo aver modificato le variabili di ambiente.
Le richieste continuano a riuscire mentre il collector non è disponibile. È il comportamento previsto. Il percorso di esportazione lascia l'applicazione operativa in caso di errore e non conserva i batch non riusciti per riprovarli.
Un campo di log manca o è abbreviato. Le chiavi che sembrano contenere segreti vengono rimosse e i valori lunghi o molto annidati vengono limitati intenzionalmente. Registra un identificatore o un riepilogo sicuro anziché indebolire il confine di rimozione dei dati.