plotting

Author: pseusys

.github/workflows/benchmarks.yaml

@@ -90,3 +90,31 @@ jobs:
           path: flamegraphs/
           retention-days: 5
 
+  plotting:
+    name: Generate TYPHOON Example Plots
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v4
+
+      - name: Install Python and matplotlib 🐍
+        run: pip install matplotlib numpy click rich
+
+      - name: Generate flow diagrams 📉
+        env:
+          RUSTFLAGS: "-D warnings"
+          PYTHONPATH: evaluation/src
+        run: |
+          mkdir -p flow-diagrams
+          for example in hello_world multi_flow multi_client long_session heavy_traffic; do
+            python -m typhoon_eval.flow_plot --example "$example" --typhoon-dir typhoon --out-dir "flow-diagrams/${example}" --per-packet || true
+          done
+
+      - name: Upload flow diagrams 📈
+        uses: actions/upload-artifact@v4
+        with:
+          name: flow-diagrams
+          path: flow-diagrams/
+          retention-days: 5
+

.gitignore

@@ -15,3 +15,18 @@ typhoon/.test_keys
 
 evaluation/protocols/wireguard_daita/wg-daita/go.sum
 evaluation/protocols/wireguard_daita/wireguard-go
+
+# Python
+evaluation/**/__pycache__/
+evaluation/**/*.pyc
+evaluation/**/*.pyo
+evaluation/.venv/
+evaluation/dist/
+evaluation/**/*.egg-info/
+
+# Poetry
+evaluation/poetry.lock
+
+# Capture results (pcaps can be hundreds of MB)
+evaluation/results/
+

README.md

@@ -25,6 +25,7 @@ The crate defines the following features:
 - `server`: include TYPHOON server implementation.
 - `client`: include TYPHOON client implementation.
 - `debug`: include [debug diagnostic tools](PROTOCOL.md#debug-mode) (`DebugMode`, `DebugResult`, `run_debug`, `DebugServerConnectionHandler`); requires `client` and `server`.
+- `capture`: emit per-packet JSONL records to the `typhoon::capture` log target at `TRACE` level; enable at runtime with `RUST_LOG=typhoon::capture=trace`.
 - `tokio`: use [tokio](https://tokio.rs/) async runtime.
 - `async-std`: use [async-std](https://async.rs/) async runtime.
 
@@ -98,6 +99,24 @@ TYPHOON_TEST_SERVER_KEY_FAST=server.key cargo bench --bench roundtrip
 
 CI runs benchmarks on every push to `main` and on pull requests that touch `typhoon/**`.
 Results are stored as a workflow artifact (`bench-results`) on each run.
+The CI also generates per-example flamegraph SVGs and per-flow packet structure diagrams
+(stored as `flamegraphs` and `flow-diagrams` artifacts respectively, retained for 5 days).
+
+### Flow capture
+
+The `capture` feature emits per-packet JSONL records (component sizes, direction, flow address)
+to the `typhoon::capture` log target at `TRACE` level.  The `evaluation/` tool can turn these
+into stacked-bar SVG diagrams:
+
+```shell
+# Run an example, capture traffic, generate diagrams
+cd evaluation
+poe plot --example heavy_traffic --out-dir out/
+
+# Or generate from an existing log file
+RUST_LOG=typhoon::capture=trace cargo run --features capture --example hello_world 2>trace.log
+poe plot --log trace.log --out-dir out/
+```
 
 ### Coverage
 

evaluation/.gitignore

@@ -12,6 +12,7 @@ rich               = "^13.0"
 python-on-whales   = "^0.73"
 scapy              = "^2.6"
 numpy              = "^2.0"
+matplotlib         = "^3.9"
 
 [tool.poetry.group.dev.dependencies]
 ruff = "^0.11"
@@ -48,6 +49,10 @@ select = ["E", "F", "I", "UP", "B"]
   cmd  = "python -m typhoon_eval.analysis"
   help = "Analyze captured pcap files — pass --run <YYYYMMDD_HHMMSS> or omit for latest"
 
+  [tool.poe.tasks.plot]
+  cmd  = "python -m typhoon_eval.flow_plot"
+  help = "Generate per-flow packet structure diagrams — pass --example <name> or --log <file>, and --out-dir <dir>"
+
   [tool.poe.tasks.clean]
   shell = "rm -rf results/captures results/logs"
   help  = "Delete all captured pcap files and logs"