Diagnostica di sistema e analisi dell'utilizzo

Libre WebUI offre agli amministratori due viste in tempo reale dell'istanza: una pagina Sistema con la diagnostica dell'host e del runtime e una pagina Utilizzo con l'analisi dell'utilizzo dei modelli e dei provider. Entrambe sono riservate agli amministratori nel backend e nell'interfaccia. La lettura delle due pagine resta all'interno del deployment; la telemetria esterna facoltativa segue invece un percorso di osservabilità separato e configurato dall'operatore.

Puoi raggiungerle dalle voci amministrative nella barra laterale, dalle scorciatoie per amministratori nel menu delle schede oppure direttamente agli indirizzi /system e /usage. Gli utenti non amministratori non possono aprire le due pagine e le schede di amministrazione vengono chiuse se un account connesso perde il ruolo admin.

Diagnostica di sistema

La pagina Sistema (/system) mostra:

Host: nome host, piattaforma, versione del kernel, architettura, tempo di attività, numero di CPU logiche, modello della CPU, carico medio e rilevamento della probabile esecuzione in container. Non è disponibile una percentuale di utilizzo della CPU; il carico della CPU corrisponde soltanto al carico medio.
Runtime: versione dell'applicazione, versione di Node.js, ID del processo, tempo di attività del processo e directory di lavoro.
Memoria: memoria totale, libera e usata dell'host, insieme ai valori RSS e heap del processo.
File system: capacità e utilizzo del file system di runtime (/) e della directory dei dati (DATA_DIR).
Rete: nomi e indirizzi delle interfacce, con contatori dei byte ricevuti/trasmessi su Linux.
Docker: versione del motore, sistema operativo dell'host, kernel, CPU e memoria comunicati dal motore, oltre ai conteggi dei container e a un elenco ridotto, quando il socket Docker è disponibile.

La pagina viene aggiornata ogni 30 secondi mentre la relativa scheda è attiva e dispone di un pulsante per l'aggiornamento manuale. L'endpoint del backend è GET /api/system, protetto da autenticazione, ruolo di amministratore attivo e limite per utente di 120 richieste ogni 15 minuti. Le risposte non vengono mai memorizzate nella cache (Cache-Control: no-store) e ogni richiesta raccoglie valori aggiornati.

Dipendenza dal socket Docker

La sezione Docker risolve il proprio endpoint nello stesso modo del runtime Work e del terminale interattivo: WORK_DOCKER_SOCKET, se impostato (sempre un percorso di socket Unix locale); in alternativa DOCKER_HOST, ovvero un URL unix:// o un endpoint tcp:// HTTP semplice, ad esempio un proxy filtrato dell'API Docker; altrimenti /var/run/docker.sock. Gli endpoint ssh:// e npipe:// e gli endpoint tcp:// con verifica TLS abilitata non vengono interrogati intenzionalmente. Le richieste sono esclusivamente operazioni GET di sola lettura sul motore (versione, informazioni ed elenco dei container), con timeout di 4 secondi e dimensione della risposta limitata; l'elenco dei container è limitato a 100 voci.

Senza un socket utilizzabile, il resto della pagina continua a funzionare: il pannello Docker indica il motivo dell'indisponibilità, ovvero socket non montato, montato ma illeggibile, daemon irraggiungibile o endpoint remoto, anziché far fallire l'intera richiesta.

Informazioni mostrate dalla pagina e relativi destinatari

L'elenco dei container è ridotto intenzionalmente: ID breve, nome, immagine, stato e ora di creazione. Variabili di ambiente, etichette, mount, comandi dei container e payload di ispezione non vengono mai inclusi e nella risposta non appare alcuna credenziale.

La pagina mostra comunque dettagli reali dell'infrastruttura: nome host, directory di lavoro, indirizzi IP interni e nomi e immagini di tutti i container sull'host Docker, non soltanto quelli di Libre WebUI. Ciò è coerente con il modello di fiducia: in un deployment Docker, ogni amministratore di Libre WebUI è già di fatto un amministratore dell'host (vedi Docker). Assegna il ruolo admin di conseguenza.

Analisi dell'utilizzo

La pagina Utilizzo presenta grafici del lavoro di modelli e provider attribuito agli utenti. La misurazione avviene a ogni confine di esecuzione supportato e al momento comprende:

chiamate alle chat Ollama locali, incluse la chat nativa e le chiamate Work basate su Ollama;
chiamate alle chat degli agenti CLI installati e chiamate del motore Strands;
chat basate su plugin, con e senza streaming;
embedding, generazione di immagini, trascrizione vocale, sintesi vocale, audio e video basati su plugin; e
chiamate Work basate su plugin.

Le operazioni in background prive di un utente proprietario non vengono assegnate intenzionalmente a un account sintetico e pertanto non vengono misurate. Una chiamata viene comunque registrata se non riesce o viene annullata.

Ogni evento registra:

ID del provider/plugin e uno snapshot del nome visualizzato (ollama e agent-cli:* usano lo stesso registro dei provider plugin)
funzionalità (chat, embedding, image, stt, tts, audio, video)
modello
stato: success, error o cancelled (uno stream interrotto viene conteggiato come annullato)
conteggi dei token, soltanto quando il provider ha restituito metadati sull'utilizzo
contatori di unità appropriati alla funzionalità (caratteri per TTS, immagini, input degli embedding, processi per i video, byte per l'audio)
durata complessiva e timestamp
ID dell'utente che ha effettuato la richiesta

Non viene archiviato altro. Prompt, risposte, endpoint dei provider, credenziali e corpi degli errori dei provider non vengono mai scritti nella tabella di utilizzo: una chiamata non riuscita viene registrata soltanto come status = 'error'. Gli eventi risiedono nel database dell'applicazione selezionato (SQLite in modalità individuale, PostgreSQL in modalità team) e vengono conservati per 400 giorni; le righe più vecchie vengono eliminate in modo opportunistico in fase di scrittura, al massimo una volta al giorno. La misurazione è intenzionalmente basata sul massimo impegno e non può mai causare l'errore di una richiesta a un modello o provider.

La pagina offre intervalli di 7, 30 e 90 giorni tramite un unico endpoint riservato agli amministratori, GET /api/plugins/usage?days=<1..365> (valore predefinito 30). Mostra chiamate totali, token comunicati, percentuale di successo, latenza media e la quota di chiamate che ha comunicato l'uso dei token. La lettura della pagina è di sola lettura e usa il registro di utilizzo già presente nel deployment.

Utilizzo degli agenti

La sezione Agenti nella parte superiore (Chiamate agli agenti CLI e al motore Strands) mostra separatamente Claude Code, Codex, OpenCode, Pi e Strands. Per ciascuno riporta chiamate, token dichiarati, chiamate fallite o annullate, durata media e fino a 20 modelli più usati. I totali comprendono tutte le chiamate corrispondenti nel periodo selezionato, indipendentemente dai limiti delle tabelle generali di provider e modelli. Sono sottoinsiemi dei totali della pagina, non eventi fatturabili aggiuntivi.

Un agente privo di record mostra Nessuna chiamata registrata in questo periodo: ciò non indica se la CLI è installata o autenticata. Le chiamate senza metadati sui token mostrano Token non riportati; i contatori mancanti non vengono stimati. La pagina si aggiorna ogni 20 secondi quando è visibile e offre un aggiornamento manuale.

L’utilizzo CLI registra una singola invocazione e i contatori comunicati dalla CLI. Gli snapshot cumulativi sostituiscono quelli precedenti e i rapporti ripetuti per passaggio vengono deduplicati. Cache e ragionamento vengono combinati secondo il protocollo di ogni CLI, senza conteggiare due volte i sottoinsiemi. Invocazioni annullate e risposte parziali con uscita non riuscita conservano l’esito effettivo.

Le chiamate di Strands sono attribuite all’agente Strands. Il motore non ha un proprio provider di modelli; ogni chiamata al modello che effettua passa per i provider Ollama o plugin di Libre WebUI. Le chiamate esterne a LWUI non vengono importate. I record precedenti senza contatori dei token restano non misurati.

L’endpoint espone questa suddivisione limitata in agents, includendo tutti e cinque i nomi supportati anche quando i contatori sono zero. Leggerla non rileva modelli CLI, non avvia agenti e non contatta provider. I server precedenti privi di questo campo possono mostrare le voci agente registrate nella suddivisione per provider; le voci assenti su tali server non vengono presentate come utilizzo zero confermato.

Esplorare modelli e provider

I colori dei modelli collegano il grafico giornaliero, il calendario annuale delle attività, la tabella dei modelli e le barre dei provider. Ai colori si accompagnano nomi dei modelli, valori e indicatori di selezione. Il calendario delle attività copre sempre gli ultimi 365 giorni, indipendentemente dall'intervallo selezionato; il colore di ogni giorno indica il modello più usato.

Il grafico giornaliero passa tra Chiamate e Token. Passa il puntatore su un modello nella legenda o portaci il focus da tastiera per seguirne la linea. Seleziona il modello per mantenerlo evidenziato, riselezionalo per rilasciarlo oppure scegli Mostra tutti i modelli per reimpostare. Anche la tabella dei modelli offre un'azione di evidenziazione. L'evidenziazione cambia solo l'enfasi e conserva i totali giornalieri, i valori della tabella e i totali dei provider.

Sposta il puntatore sul grafico oppure usa Esplora l’utilizzo giornaliero per ispezionare il totale di un giorno e la sua ripartizione per modello. Il cursore giornaliero supporta la tastiera: le frecce spostano tra i giorni e Home/Fine raggiungono il primo e l'ultimo. I bucket giornalieri e le relative etichette usano UTC.

Per impostazione predefinita il grafico mostra i 12 nomi di modello con più chiamate nel periodo selezionato, anche nella vista dei token. Ogni modello resta comunque ispezionabile singolarmente: porta il focus o seleziona un modello nella tabella o nei dettagli del provider per caricarne la linea giornaliera esatta, anche quando è fuori da quei 12. Un messaggio di caricamento indica il modello richiesto mentre viene recuperata la sua cronologia.

La linea di un modello aggiuntivo viene separata da Altri modelli e il gruppo residuo esclude le sue chiamate, i token comunicati e gli errori. Il grafico contiene al massimo 13 linee di modello nominate più il gruppo residuo e i loro valori giornalieri restano coerenti con gli stessi totali. Scegli Mostra tutti i modelli per tornare alla vista predefinita.

Le linee giornaliere uniscono le chiamate con lo stesso nome di modello registrato tra i provider. La tabella dei modelli mantiene voci distinte per provider/modello, quindi lo stesso modello può comparire sotto più di un provider. I modelli nominati mantengono colori individuali nella tabella e nelle barre dei provider, compresi quelli fuori dal grafico predefinito.

I dettagli dei provider mostrano la quota di richieste di ciascun provider, una barra suddivisa per modello, i token comunicati, le chiamate fallite o annullate e il tempo medio di risposta. La distribuzione delle funzionalità resta disponibile sotto le ripartizioni per modello e per provider.

I totali dei token comprendono soltanto le chiamate per cui il provider ha comunicato metadati sull'utilizzo. La percentuale di copertura rende visibile una comunicazione parziale; i conteggi mancanti non vengono mai stimati dalle richieste né da un altro modello. Un periodo senza token comunicati mostra una spiegazione nella vista Token e la sua cronologia delle richieste resta disponibile in Chiamate.

L'endpoint include i punti giornalieri per modello in modelSeries. Un parametro di query facoltativo model richiede un nome di modello registrato esatto accanto ai 12 predefiniti, ad esempio GET /api/plugins/usage?days=30&model=<encoded-model-name>. È lo stesso endpoint riservato agli amministratori e di sola lettura: interroga il registro di utilizzo locale e non contatta mai un provider di modelli per recuperare la cronologia.

Un parametro facoltativo to fissa il limite finale della richiesta a un timestamp Unix in millisecondi. Richiede model e accetta soltanto un intero sicuro non negativo non successivo all'ora corrente del server. Il browser invia il valore range.to della panoramica quando carica un singolo modello, preservandone i limiti UTC di giorno e di anno ed escludendo le chiamate successive a quel timestamp. Senza to, l'endpoint usa l'ora corrente.

Il caricamento di un modello lascia invariati schede, tabella, totali dei provider e colori della panoramica. La sua linea giornaliera viene aggiunta soltanto quando i limiti temporali e i totali giornalieri della risposta corrispondono a quella panoramica. Il limite temporale non congela il database: se backfill storici o eliminazioni cambiano quei totali, il browser aggiorna la panoramica prima di mostrare la linea del modello.

Se un server più vecchio omette modelSeries, il grafico mostra la serie aggregata Tutti i modelli con una spiegazione che la ripartizione per modello non è disponibile. La tabella dei modelli resta disponibile; il browser non deduce la cronologia giornaliera per modello dai totali del periodo o dal calendario annuale.

Non esiste un interruttore per disabilitare la misurazione. Poiché i dati vengono aggregati tra gli account, la loro consultazione è riservata agli amministratori.

La pagina Utilizzo riporta chiamate, unità, token, latenza e risultati. Aggiungi la governance dei costi quando per tali eventi servono tariffe con validità temporale, ripartizioni della spesa, budget, avvisi o esportazione contabile. Gli eventi senza una tariffa corrispondente o senza utilizzo comunicato dal provider restano visibilmente senza prezzo anziché essere considerati gratuiti.

Attribuzione OpenRouter

Dalla versione 0.18.0, le richieste a OpenRouter identificano l'applicazione tramite le intestazioni di attribuzione delle app di OpenRouter (HTTP-Referer: https://librewebui.org, un titolo dell'applicazione e indicazioni sulla categoria). Queste intestazioni vengono inviate soltanto quando la richiesta è diretta a https://openrouter.ai, mai a una route personalizzata o self-hosted, e non aggiungono nulla ai dati archiviati localmente.