# Capitolo 7: Strumenti di Debug Il Radar Target Simulator include strumenti avanzati progettati specificamente per il debug e la diagnostica a basso livello. Questi strumenti sono accessibili dal menu `Debug` della finestra principale. ## 7.1. SFP Packet Inspector (`SfpDebugWindow`) Questa è la finestra di debug più potente dell'applicazione, dedicata all'ispezione e all'interazione con il protocollo SFP (Simple Fragmentation Protocol). Permette di monitorare il traffico di rete, inviare comandi manuali e ispezionare il contenuto dei payload ricevuti. *(Placeholder per l'immagine)* **Descrizione dell'Immagine:** `finestra_debug_sfp_ris.png` *Qui ti aspetti uno screenshot della finestra `SfpDebugWindow`. Deve avere la scheda "RIS" selezionata per mostrare le tabelle più importanti.* *Evidenzia:* 1. *La sezione superiore con i controlli di connessione e il "Simple Target Sender".* 2. *La scheda "Raw" con un dump esadecimale di un pacchetto.* 3. *La scheda "RIS" con le due tabelle: "Scenario" a sinistra e "Targets" a destra.* 4. *La scheda "History" con l'elenco dei pacchetti ricevuti.* --- ### 7.1.1. Panoramica della Finestra La finestra è suddivisa in tre aree principali: 1. **Controlli Superiori:** * **Connessione:** Permette di stabilire o interrompere una connessione SFP indipendente da quella della finestra principale, utile per il debug isolato. * **Simple Target Sender:** Un'interfaccia rapida per inviare un singolo comando `tgtset` o un payload JSON per un target con parametri definiti al volo. È estremamente utile per testare la risposta del radar a uno stimolo specifico senza caricare un intero scenario. I pulsanti nelle schede "CMD" e "JSON" permettono di inviare comandi rapidi come il reset. * **Script to send:** Un campo per inviare comandi testuali arbitrari. 2. **Pannello a Schede (Notebook):** Il cuore della finestra, permette di ispezionare i dati ricevuti sotto diverse forme. 3. **Barra di Stato (non mostrata):** Fornisce informazioni aggiuntive. ### 7.1.2. Interpretazione delle Schede * **Scheda `Raw`:** Mostra un dump esadecimale completo dell'ultimo pacchetto SFP ricevuto. Visualizza l'header SFP decodificato campo per campo (inclusi flag, flow ID, TID) e il corpo del payload in formato esadecimale e ASCII. È lo strumento fondamentale per il debug a livello di protocollo. * **Scheda `Log`:** Un'area di log dedicata agli eventi specifici della finestra di debug. * **Scheda `RIS`:** **La scheda più importante per l'analisi dei dati reali.** Quando l'applicazione riceve un payload di stato dal sistema radar (tipicamente con Flow ID 'R'), questa scheda lo decodifica e lo visualizza in due tabelle: * **Tabella `Scenario`:** Mostra i dati globali della piattaforma/ownship inviati dal radar (posizione, velocità, heading, altitudine, modalità operativa, etc.). * **Tabella `Targets`:** Elenca tutti i target (tipicamente fino a 32) e il loro stato come riportato dal radar. Per ogni target, visualizza flag, heading e posizione `(x, y, z)` in coordinate assolute. * **Scheda `History`:** Tiene traccia degli ultimi pacchetti SFP ricevuti, mostrando timestamp, Flow ID, TID e dimensione. Selezionando una riga, il contenuto completo di quel pacchetto viene visualizzato nella scheda `Raw`, permettendo di analizzare pacchetti passati. * **Schede `MFD`/`SAR`/`BIN`/`JSON`:** Queste schede sono "payload-aware". Quando viene ricevuto un payload con il Flow ID corrispondente, il suo contenuto viene visualizzato in un formato appropriato: * `MFD`/`SAR`: Tentano di renderizzare il payload come un'immagine. * `BIN`: Mostrano un dump esadecimale. * `JSON`: Formattano e visualizzano il payload come un albero JSON. Altre funzionalità di debug SFP * **Parsing avanzato degli header:** L'inspector decodifica ora in modo dettagliato l'header SFP campo per campo (inclusi flag, flow ID, TID e altri campi del protocollo) per facilitare l'analisi a basso livello. * **Supporto `ris_status` e campi addizionali:** I payload di tipo RIS possono contenere campi estesi (es. `rcs`, `amplitude`) o messaggi di stato specifici (`ris_status`) che vengono interpretati e visualizzati nella scheda `RIS` quando presenti. * **Raw vs Simplified:** È possibile scegliere fra una vista `raw` (dump esadecimale completo) e una vista `simplified` che mostra i campi più rilevanti in forma tabellare per una lettura rapida. * **Visualizzazione in Coordinate Polari (RIS - Polar):** Nella scheda `RIS` è disponibile anche una vista che mostra i dati dei target in coordinate polari (range, azimut, altitudine). Questa rappresentazione è utile per confrontare rapidamente le misure radar con le coordinate polari usate nella definizione degli scenari. * **IO trace CSV:** Se abilitato (flag di debug in `settings.json` o tramite l'interfaccia di debug), l'applicazione può salvare tracce I/O e latenze in file CSV per analisi esterne. I file CSV di debug vengono creati per default nella cartella `Temp/` a meno di diversa configurazione. ## 7.2. Pannello Livelli di Log (`LoggerPanel`) Accessibile da `Debug -> Logger Levels...`, questa finestra permette di controllare dinamicamente, a runtime, il livello di verbosità dei log per ogni singolo modulo dell'applicazione. *(Placeholder per l'immagine)* **Descrizione dell'Immagine:** `pannello_logger.png` *Qui ti aspetti uno screenshot della finestra `LoggerPanel`.* *Evidenzia:* 1. *La lista dei logger disponibili a sinistra.* 2. *Il campo "Filter" in alto a sinistra.* 3. *Il menu a tendina "Level" a destra per selezionare il livello (DEBUG, INFO, etc.).* 4. *Il pulsante "Apply".* --- * **Scopo:** È uno strumento indispensabile per il debug. Se si sospetta un problema in un modulo specifico (es. `sfp_transport`), si può aumentare il suo livello di log a `DEBUG` per ottenere informazioni estremamente dettagliate, senza essere sommersi dai log degli altri moduli. * **Funzionamento:** 1. La lista a sinistra mostra tutti i logger registrati nell'applicazione. 2. Si seleziona il logger di interesse. 3. Si sceglie il livello di log desiderato dal menu a tendina (`DEBUG` per la massima verbosità, `INFO` per il normale funzionamento, `WARNING` o `ERROR` per visualizzare solo i problemi). 4. Si preme `Apply`. La modifica ha effetto immediato. * **Persistenza:** Le modifiche ai livelli di log vengono salvate in un file `logger_prefs.json`, in modo da essere mantenute tra un'esecuzione e l'altra dell'applicazione. ## 7.3. Profiling e analisi delle prestazioni L'applicazione include inoltre un sistema di profilazione pensato per analizzare le prestazioni di alcune funzionalità core eseguite continuamente durante la comunicazione con il server (invio/ricezione pacchetti, elaborazione del payload, aggiornamento display). Questo strumento è utile per individuare colli di bottiglia e per validare l'impatto delle ottimizzazioni. - **Cosa misura:** tempi di round-trip e latenza delle operazioni SFP, durata delle routine di parsing/dispatch, tempi di aggiornamento grafico (es. draw del PPI) e latenza tra messaggi di sincronizzazione (SYNC). - **Output:** I dati di profilazione possono essere salvati in formato CSV per analisi esterne. Per convenzione i file di report vengono collocati nella cartella `Temp/` o in una directory configurata dall'utente. I CSV includono timestamp, nome dell'operazione e durata in millisecondi. - **Integrazione esterna:** È possibile correlare i report di profilazione con catture packet (PCAP) analizzate con Wireshark per ottenere una visione combinata di traffico di rete e tempi di elaborazione lato applicazione. Alcuni strumenti ausiliari presenti nel repository aiutano a generare marker compatibili con Wireshark. - **Come attivarlo:** Il profiling è abilitabile tramite l'interfaccia di debug o tramite un flag di configurazione (es. sezione `debug` in `settings.json`). Quando attivato, l'overhead è minimizzato e i dati vengono raccolti in modo incrementale. Configurazione e nomi delle impostazioni * **Opzioni di debug/IO-trace (chiavi `DEBUG_CONFIG` / `settings.json`):** * `enable_io_trace` (bool): abilita la scrittura dei CSV con le posizioni inviate e ricevute. * `io_trace_sent_filename` (string): nome file di default per le posizioni inviate (default: `sent_positions.csv`). * `io_trace_received_filename` (string): nome file di default per le posizioni ricevute (default: `received_positions.csv`). * `temp_folder_name` (string): cartella temporanea in cui vengono creati i file CSV prima dello spostamento in `archive_simulations/` (default: `Temp`). * **Profiling delle prestazioni:** * `enable_performance_profiling` (bool): se `True` il `PayloadRouter` raccoglie campioni di prestazione interni (parse_ms, hub_ms, archive_ms, listener_ms, clock_ms) che vengono poi esportati. Produzione dei file * I file di IO-trace (posizioni inviate / ricevute) sono prodotti nella cartella indicata da `temp_folder_name` (default `Temp`) e hanno i nomi configurati nelle chiavi precedenti. * Al termine della simulazione lo `SimulationArchive` finalizza i file temporanei e li rinomina spostandoli nella cartella `archive_simulations/` con suffissi standard: * `_.trail.csv` — file trail delle posizioni (simulated/real). * `_.latency.csv` — file delle latenze campionate. * `_.perf.csv` — file delle performance (generato se `enable_performance_profiling` era attivo durante la sessione). Nota: i nomi dei file e la cartella temporanea possono essere personalizzati tramite `settings.json` e `DEBUG_CONFIG`. Nota: il profiling è pensato per l'uso in ambiente di laboratorio o sviluppo; non è consigliato abilitarlo in scenari di produzione a causa dell'overhead aggiuntivo e della possibile generazione di grandi volumi di dati. ## 7.4. Sync Tool (Strumento di Misura Latenza) Lo `SyncTool` è uno strumento di debug pensato per misurare e riportare la latenza di rete e delle pipeline applicative tra il simulator e il server radar. Viene usato per raccogliere una serie di campioni temporali correlati tra il client e il server, per calcolare RTT (round-trip time), offset di clock e, quando possibile, la latency unidirezionale stimata. *(Placeholder per l'immagine)* **Descrizione dell'Immagine:** `sync_tool.png` *Screenshot della finestra `SyncTool` che mostra i controlli di avvio/test, un grafico temporale dei campioni di latenza, una tabella con gli ultimi campioni e i pulsanti di export.* ### Cosa fa - Invia messaggi di tipo `SYNC` (o un pacchetto di ping custom) al server e attende la risposta. - Se il server include un timestamp nel payload di risposta, il tool raccoglie sia il timestamp locale che quello server-side per calcolare il clock offset e stimare la latenza one-way. - Calcola RTT per ogni scambio e produce statistiche aggregate (media, mediana, deviazione standard, percentili). - Salva un report CSV con tutti i campioni e permette l'esportazione immediata per analisi esterne o per correlazione con catture PCAP. ### Come lo fa (meccanismo e dettagli tecnici) - Sequenza di test: il tool invia N messaggi `SYNC` numerati (configurabili) a intervalli configurabili (es. 100 ms). - Misurazioni raccolte per ciascun pacchetto: - `local_send_ts`: timestamp locale di invio (epoch ms). - `server_ts`: timestamp fornito dal server nella risposta (se disponibile). - `local_recv_ts`: timestamp locale di ricezione (epoch ms). - `seq`: identificatore di sequenza del test. - `rtt_ms`: tempo di andata/ritorno in ms = `local_recv_ts - local_send_ts`. - `clock_offset_ms`: se `server_ts` è presente, offset stimato = `server_ts - (local_send_ts + local_recv_ts)/2`. - Calcolo aggregato: il tool calcola media/mediana/std/p95/p99 su `rtt_ms` e fornisce una stima affidabile dell'instabilità di rete durante il test. - Correlazione PCAP: il tool può inserire nei log un marcatore (es. `SYNC-SEQ:`) che facilita la ricerca dei pacchetti corrispondenti in una cattura PCAP con Wireshark. ### Interfaccia (campi principali) - **Target / Endpoint:** selezione dell'endpoint SFP o del communicator da testare. - **Count:** numero di ping da inviare (default 100). - **Interval (ms):** intervallo tra i ping (default 100 ms). - **Payload size:** dimensione del campo opzionale da inviare (per test di frammentazione). - **Start / Stop:** pulsanti per avviare o interrompere il test. - **Export CSV:** esporta il report completo in `Temp/` oppure copia in percorso scelto dall'utente. - **Grafico:** visualizzazione temporale dei valori RTT e/o offset, utile per individuare jitter o spike. ### Output e formato CSV di esempio Per comodità il CSV prodotto ha intestazioni chiare; un esempio di riga: ``` local_send_ts,local_recv_ts,server_ts,seq,rtt_ms,clock_offset_ms 1700832000000,1700832000105,1700832000008,1,105,8 1700832000100,1700832000207,1700832000105,2,107,5 ``` Il file per default viene creato nella cartella temporanea (`Temp/`) e, se richiesto, può essere salvato o inserito nell'`archive_simulations/` con un nome del tipo `_sync_latency.csv`. ### Note operative e consigli - Eseguire il test in condizioni il più possibile ripetibili (stesso network path, poca attività concorrente) per ottenere valori consistenti. - Se il server non fornisce timestamp, il tool può comunque misurare RTT ma non può stimare l'offset di clock one-way. - Per analisi dettagliate, abbinare il report CSV con una cattura PCAP del test e usare il marcatore `SYNC-SEQ` per correlare i pacchetti. - Non abilitare test con payload molto grandi su reti di produzione senza autorizzazione: possono disturbare i dispositivi intermedi (frammentazione, MTU). ### Esempio di uso rapido 1. Selezionare l'endpoint SFP desiderato nella tendina `Target`. 2. Impostare `Count=200` e `Interval=50` per un test con maggior risoluzione. 3. Premere `Start` e attendere il completamento. 4. Esportare il CSV e aprirlo con Excel o uno script Python per analizzare percentili e anomalie. ### Integrazione con gli altri strumenti di debug - Il `SyncTool` complementa la profilazione interna (`enable_performance_profiling`) fornendo una vista puntuale della latenza di rete end-to-end. - I CSV del `SyncTool` possono essere caricati nel `PerformanceAnalysisWindow` per confrontare i tempi di rete con i tempi di elaborazione applicativa. --- ## 7.5. External Profiler (Profiler Esterno) L'`ExternalProfiler` è uno strumento di debug che permette di inoltrare dati di profilazione e marker temporali verso strumenti esterni (es. Wireshark, strumenti di logging remoti, sistemi di raccolta packet) e di ricevere dati da altri endpoint di profilazione. È pensato per integrare la profilazione applicativa interna con l'analisi a livello di rete e con tool di terze parti. *(Placeholder per l'immagine)* **Descrizione dell'Immagine:** `external_profiler.png` *Screenshot della finestra `ExternalProfilerWindow` che mostra i campi di configurazione (IP/Port, Protocollo, Enable Forwarding), lo stato della connessione, e pochi campioni in streaming.* ### Concetto e scopo - **Concetto:** l'`ExternalProfiler` invia (o riceve) pacchetti di profilazione serializzati (tipicamente JSON su UDP/TCP) verso un collector esterno. Questi pacchetti contengono marker temporali, identificatori di sequenza, e talvolta payload con campioni di durata (es. parse_ms, hub_ms, archive_ms) o eventi speciali (es. `SYNC-SEQ`). - **Scopo:** permettere la correlazione tra il comportamento interno dell'applicazione (tempi di parsing/dispatch/archive) e il traffico di rete osservabile esternamente; abilitare strumenti di analisi avanzata che non sono integrati nell'app (es. visualizzazione PCAP in Wireshark, aggregatori di metriche, ELK stack). ### Come funziona (flusso) 1. L'utente abilita il forwarding dalla finestra `ExternalProfilerWindow` e configura l'endpoint (IP/porta, protocollo UDP/TCP). 2. Durante l'esecuzione, il `PayloadRouter` o il `SimulationController` invia pacchetti di profiling all'endpoint configurato; ciascun pacchetto può contenere: - `timestamp` (epoch ms o epoch s + fractional), `seq` (sequenza), `type` (es. `perf_sample`, `sync_marker`), e un payload JSON con i campi di tempo. 3. L'endpoint esterno riceve i pacchetti e li registra in un file PCAP/PCAPNG (se catturato come traffico di rete) oppure in un sink di logging. 4. L'utente può poi correlare i CSV `.perf.csv` generati internamente con la cattura PCAP, utilizzando i timestamp/seq presenti in entrambi i flussi. ### Configurazione tipica - **Protocollo:** UDP (consigliato per basso overhead) o TCP (affidabilità maggiore). - **Host / Port:** indirizzo del collector (es. `192.168.1.10:55000`). Il `ExternalProfilerWindow` espone questi campi come input utente. - **Forwarding Options:** includere o escludere payload voluminosi, abilitare compressione (se supportata), abilitare marcatore `SYNC-SEQ` per correlazione. ### Strumenti terzi consigliati e come usarli 1) Wireshark (GUI) - **Cattura:** avviare una cattura sull'interfaccia di rete corretta; se si conosce la porta UDP/TCP del profiler, impostare un capture filter per ridurre il traffico catturato ad es. `udp port 55000`. - **Display filter:** per isolare i messaggi del profiler usare ad es. `udp.port == 55000` oppure `frame contains "SYNC-SEQ"` per trovare i marker testuali. - **Time display:** impostare `View -> Time Display Format -> Date and Time of Day` o `Seconds Since Beginning of Capture` a seconda del tipo di correlazione che si desidera fare. Per confrontare con CSV epoch, usare `frame.time_epoch` (visibile quando si esportano i campi). - **Esportazione timestamp:** `File -> Export Packet Dissections -> As CSV...` e includere il campo `frame.time_epoch` e il campo contenente i dati del payload (es. `data`) per allineare i record con il CSV applicativo. - **Ricerca avanzata:** usare `Find Packet` con la stringa `SYNC-SEQ:` per trovare il pacchetto corrispondente. - **Statistiche / Grafici:** `Statistics -> IO Graphs` o `Statistics -> Flow Graph` per visualizzare andamento temporale, spike e ritardi. 2) dumpcap / tshark (CLI) - Esempio cattura (salva in `sync_capture.pcapng` filtrando per porta UDP): ```powershell dumpcap -i 1 -f "udp port 55000" -w sync_capture.pcapng ``` - Esempio estrazione timestamp e payload (estrarre solo pacchetti contenenti marker): ```powershell tshark -r sync_capture.pcapng -Y 'frame contains "SYNC-SEQ"' -T fields -e frame.time_epoch -e data > sync_packets.txt ``` Nota: sostituire `-i 1` con l'indice dell'interfaccia corretta; sostituire `55000` con la porta configurata. 3) Correlazione automatica - Una volta ottenuti i due file (CSV interno `.perf.csv` o report `sync_latency.csv` e la cattura PCAP/CSV dei pacchetti), allineare i record usando il campo `frame.time_epoch` (epoch in secondi con frazione). Se i timestamp interni sono in millisecondi dall'epoch, convertirli in secondi (dividere per 1000) oppure convertire i timestamp PCAP in ms. - Se i clock non sono sincronizzati, usare i marker di `SYNC-SEQ` per calcolare l'offset tra i due timeline e correggere i valori prima della correlazione. ### Buone pratiche - Usare UDP per ridurre l'impatto sul timing (meno overhead), ma ricordare che i pacchetti UDP possono andare persi: segnare quindi i `seq` per identificare perdite. - Abilitare la compressione o limitare i payload se si cattura su reti con limite di banda. - Tenere conto dell'overhead aggiunto dal forwarding: i pacchetti di profilazione dovrebbero essere piccoli e numerosi solo se necessario. ---