252 lines
19 KiB
Markdown
252 lines
19 KiB
Markdown
# 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:
|
||
* `<timestamp>_<scenario>.trail.csv` — file trail delle posizioni (simulated/real).
|
||
* `<timestamp>_<scenario>.latency.csv` — file delle latenze campionate.
|
||
* `<timestamp>_<scenario>.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:<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 `<timestamp>_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:<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.
|
||
|
||
--- |