S1005403_RisCC/doc/manual/07_strumenti_di_debug.md

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):

dumpcap -i 1 -f "udp port 55000" -w sync_capture.pcapng

• Esempio estrazione timestamp e payload (estrarre solo pacchetti contenenti marker):

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.

---