Per controllare un'installazione in funzione si usa Settings, l'area amministrativa della chat web. Metnos può anche produrre un rendiconto HTML da aprire come file locale: è una fotografia tecnica del momento in cui viene generata, non una seconda versione di Settings.

1. Da dove cominciare

Puoi chiedere direttamente a Metnos:

Mostrami dove posso controllare gli ultimi turni e lo stato dei servizi.

Il percorso più semplice passa dalla chat web: Settings > Attività > Turni per le richieste recenti e Settings > Sistema > Servizi per i servizi configurati. Se stai parlando con Metnos da Telegram, devi comunque aprire queste pagine nel browser: Telegram non contiene l'area amministrativa.

API, registri e file servono invece per una diagnosi tecnica. Il rendiconto statico descritto più avanti appartiene a questo secondo caso e non è il percorso ordinario per chi usa la chat.

2. I due strumenti

Non sono due viste dello stesso strumento. Settings usa pagine e dati propri; il generatore statico viene avviato soltanto dalla riga di comando e il server HTTP non lo usa.

3. Settings nella chat

La pagina iniziale di Settings riassume versione e tempo di attività, turni delle ultime 24 ore, proposte, executor, scheduler, firme Safety e utenti. Le pagine di dettaglio separano le diverse domande operative:

Il registro in runtime/ui_surfaces.py descrive in modo canonico le pagine visibili e il percorso per raggiungerle. Il Tutor usa lo stesso registro; per questo una modifica strutturale dell'interfaccia richiede di aggiornare anche la guida di navigazione e l'indice del Tutor.

Monitor: richieste e prestazioni dei modelli

Le sezioni della barra laterale sono richiudibili; quella della pagina corrente si apre automaticamente. Monitor > Panoramica mostra velocità e durata complessiva delle richieste nel tempo; Richieste permette di aprire una singola query e le sue chiamate; Prestazioni modelli confronta le identità logiche e fisiche, con sei grafici nell'ordine: velocità della chiamata, durata media della chiamata, prefill (PP), generazione (TG), token in ingresso e token in uscita. La durata media, in secondi, è la media aritmetica delle durate complete osservate per modello e intervallo; i tempi mancanti sono esclusi, gli zeri osservati sono conservati e gli intervalli senza misure restano vuoti. Sono disponibili filtri per periodo, canale e origine, e l'esportazione JSON della vista selezionata. Origine è impostata su Tutti: include attività interattive, in background e di test, oltre alle chiamate non attribuite nelle statistiche dei modelli. Selezionando un'origine, la vista viene limitata a quell'origine.

La velocità della chiamata LLM divide i token di uscita per il tempo dall'inizio alla fine della chiamata, comprendendo prefill, generazione, coda e trasporto. La media è ponderata per la durata: somma dei token divisa per somma dei tempi delle chiamate valide. La velocità e2e della richiesta divide i token di uscita per il tempo della richiesta. Il tempo attivo esclude l'attesa della persona; il tempo complessivo la include. Prefill e generazione usano esclusivamente i tempi comunicati dal fornitore. Token o tempi mancanti restano sconosciuti e le medie delle velocità usano somme di token e tempi validi.

Il pannello richiudibile Come sono calcolate le misure spiega anche i termini usati: copertura delle misure nei modelli, chiamate rilevate/attese nelle richieste, campioni validi/totali, media, mediana e 95° percentile, insieme a token, fasi PP/TG e qualità dei dati. Un rapporto come 8/10 è accompagnato da esempi; la completezza dei token e dei tempi è distinta dal conteggio delle chiamate rilevate. La tabella dei modelli mostra anche il Prompt medio in token: somma dei token in ingresso noti divisa per il numero di chiamate con conteggio noto, nel periodo filtrato e secondo il raggruppamento logico/fisico scelto. Include l'intero prompt, con istruzioni, cronologia e strumenti presenti; i token in cache sono inclusi quando fanno parte del conteggio del fornitore. Le chiamate senza conteggio sono escluse dalla media; sotto il valore compare il rapporto fra chiamate con conteggio noto e chiamate rilevate. L'intestazione della durata mediana va a capo per contenere la larghezza della tabella; i valori numerici restano allineati.

I grafici si aggiornano ogni cinque secondi mentre la pagina è visibile. I grafici mostrano punti separati; colori distinti identificano le stesse serie in tutti i grafici. Le legende usano punti pieni degli stessi colori, senza tratti o tratteggi. Date e ore usano giorno/mese e orario UTC; il valore completo è disponibile passando sul dato. Un buffer di 128 eventi per processo consegna le misure a un thread di scrittura senza attendere il disco. Eventi persi, dati incompleti e raccolta non aggiornata sono indicati nella pagina. La raccolta conserva identificativi e misure, senza domande, risposte o credenziali; l'accesso richiede il ruolo amministrativo.

Ogni schermata Monitor ricorda nel browser i filtri applicati, il periodo, il raggruppamento dei modelli e le serie selezionate. Le preferenze sono separate per utente autenticato e schermata e restano disponibili dopo un riavvio, usando lo stesso browser. I periodi relativi, come le ultime 24 ore, vengono ricalcolati all'apertura; un intervallo personalizzato conserva le date. Un collegamento con parametri espliciti prevale sulle preferenze salvate. Le impostazioni vengono salvate dopo un caricamento riuscito, senza scritture durante i normali aggiornamenti automatici. Se il browser impedisce il salvataggio, la pagina lo segnala e resta utilizzabile.

Aggregazioni nel database e storico di 90 giorni

Il raccoglitore scrive i dati analitici direttamente in SQLite, nel thread separato dalla chiamata LLM. Le SELECT statistiche applicano periodo e filtri prima di raggruppare per intervallo, fornitore, nome logico e modello fisico. Non esiste un limite di 10.000 campioni per i riepiloghi: alla pagina arrivano solo aggregati e al massimo 200 righe di dettaglio per consultazione. I grafici hanno al massimo 500 intervalli e 12 serie selezionate; nascondere una serie o cambiare pagina non cambia i riepiloghi del periodo filtrato.

Ogni punto dei grafici dei token mostra la media per chiamata dei conteggi noti, mentre schede e tabelle mantengono anche i totali. La durata delle chiamate usa la media; la durata delle richieste usa mediana e 95° percentile a rango più vicino, calcolati su tutti i campioni validi. Le velocità usano la somma dei token divisa per la somma dei tempi validi. SQLite esegue gli ordinamenti dei percentili con temporanei su disco e una cache di 4 MiB per connessione, senza caricare lo storico in liste Python.

La finestra ciclica conserva 90 giorni di dati analitici. Al massimo una volta all'ora, alla prima scrittura o consultazione utile, una transazione elimina richieste chiuse, segmenti, chiamate e revisioni senza attività negli ultimi 90 giorni. Le pagine liberate vengono riutilizzate, senza una compattazione completa a ogni cancellazione. Richieste aperte e catene con attività recente rimangono fino alla scadenza dell'intera catena. Un vecchio evento importato non ripristina dati già scaduti. I vecchi JSONL vengono importati in gruppi limitati, con un avviso finché rimangono byte da acquisire; il nuovo raccoglitore non li incrementa. I contatori cumulativi di salute rimangono separati dai dati analitici.

4. Il rendiconto HTML statico

Il generatore legge le sorgenti locali e compone un unico documento con gli stili incorporati, senza JavaScript e senza collegamenti in tempo reale con il server. Le sezioni appaiono in questo ordine: test, Mnestoma, associazioni, turni recenti, decisioni del Vaglio e scheduler.

Ogni raccoglitore gestisce separatamente una sorgente non disponibile. La pagina può quindi essere prodotta anche quando una sezione è vuota o in errore. Questo comportamento rende leggibile una fotografia parziale, ma non trasforma l'assenza di dati in prova del buon funzionamento del componente.

Il documento generato usa attualmente etichette italiane e lang="it". Non è una superficie localizzata della chat e non va presentato come tale.

5. Dati raccolti dal rendiconto

I limiti sono fissi nel generatore e non si possono cambiare dalla riga di comando: al massimo cinque file di turni, tre file del Vaglio e un numero limitato di righe o eventi per sezione. Il rendiconto serve quindi a orientare la diagnosi, non a calcolare totali completi.

6. Accesso, utenti e riservatezza

• Settings è una vista amministrativa dell'installazione. Il middleware ammette soltanto il ruolo admin; i riepiloghi possono comprendere più utenti. Non è una vista personale del singolo utente.
• Il rendiconto statico è anch'esso complessivo. Può contenere richieste, estratti delle risposte, identificativi dei mittenti e metadati delle associazioni appartenenti a utenti diversi.
• L'escape HTML non è un controllo di accesso. Il generatore sottopone a escape i testi dinamici prima di inserirli nel documento, ma il contenuto rimane leggibile a chi può aprire il file.
• L'oscuramento a monte non è una garanzia assoluta. I registri possono rimuovere credenziali riconosciute, ma il rendiconto va comunque trattato come dato riservato.
• Il file non imposta permessi propri. Eredita directory, proprietario e umask del processo che lo genera; non va collocato in una directory servita pubblicamente.
• Una fotografia resta sul disco. Rigenerarla sovrascrive il percorso scelto, ma non elimina copie spostate, backup o file prodotti con un altro --out.

7. Generazione e durata

Dalla radice dell'installazione, usando l'ambiente Python di Metnos:

PYTHONPATH=runtime ./.venv/bin/python -m observability render
PYTHONPATH=runtime ./.venv/bin/python -m observability render --out /percorso/scelto/dashboard.html

Il percorso predefinito è PATH_WORKSPACE/dashboard/index.html. Il comando restituisce il percorso scritto e termina. Non esiste un aggiornamento periodico incorporato: ora di generazione e contenuto restano invariati finché il comando non viene eseguito di nuovo.

Il file è un prodotto derivato. Per eliminarlo si può rimuovere il solo percorso di uscita dopo aver verificato che non sia usato da altri processi; le sorgenti operative non vengono eliminate con esso.

8. Verifiche e fonti canoniche

Le prove mirate del generatore statico sono in tests/runtime/runtime/test_observability.py. Verificano, fra l'altro, che nomi degli executor, richieste e risposte non possano introdurre markup attivo nel file. Le prove HTTP ed end-to-end controllano separatamente le pagine amministrative: non si usa un conteggio fisso, destinato a diventare obsoleto.

• runtime/http_routes_admin.py — dati e azioni delle pagine Settings;
• runtime/http_auth.py — confine di autenticazione delle rotte /admin;
• runtime/ui_surfaces.py — registro editoriale delle superfici visibili;
• runtime/observability.py — generatore del rendiconto statico;
• runtime/config.py — percorsi canonici dell'installazione.