# 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.

---