feat: add CSV/JSON structured output to nvlink_monitor

[staryxchen]

Summary

First of the feature-enhancement batch. Adds machine-readable output to nvlink_monitor via -f, --format text|csv|json, so its output can be consumed by scripts for post-analysis (diffing against nvlink_bw_test throughput, computing steady-state averages, plotting). This was the highest-value item in the earlier optimization review.

Changes

New --format flag (monitor/arg_parser.{h,cpp})

• OutputFormat enum (Text/CSV/JSON), default Text.
• Parses -f/--format text|csv|json; invalid values and missing values rejected with ok=false.

Formatters (monitor/nvlink_monitor.{h,cpp})

• CSV (formatCsvResult): header timestamp,interval_s,gpu_id,link_id,tx_gibps,rx_gibps emitted once, then one row per (gpu, link) per sample, plus a per-GPU total row (link_id=total) so a GPU with no active links still appears. ISO 8601 timestamps (no spaces, no quoting needed).
• JSON (formatJsonResult): JSONL — one self-contained JSON object per sample with per-GPU totals and per-link arrays. Streaming-friendly for continuous mode (no array wrapper, each line parseable independently).
• Dispatch in runContinuousMonitoring/runSingleMonitoring switches on outputFormat. --verbose only affects the text path; CSV/JSON always emit per-link data.
• Constructor takes OutputFormat; printHelp updated with the new flag and examples.

Status messages → stderr

All diagnostic/status output (GPU discovery, "Starting continuous monitoring", SCHED_FIFO notice, "Received stop signal", warnings) is now written to stderr instead of stdout. This follows Unix convention and keeps CSV/JSON on stdout clean when piping/redirecting:

./build/nvlink_monitor -f csv 2>/dev/null | awk -F, '$4=="total"{print}'

In text mode the terminal UX is unchanged (stdout + stderr both reach the terminal).

Tests (test/test_arg_parser.cpp)

+7 tests (66 total, was 59): default text, explicit text, -f csv, --format csv, --format json, invalid rejected, missing value rejected; CombinedOptions extended to cover --format csv.

Docs (README.md)

Documented --format with CSV/JSON examples and the stderr-for-status convention.

Verification

• make check-format — clean
• make test — 66/66 pass
• make monitor — builds with -Wall -Wextra, no warnings
• Smoke-tested on an 8x H20 system: CSV and JSON single-mode samples produce well-formed output, status on stderr, clean data on stdout

Files changed

 README.md                  |  19 +++++
 monitor/arg_parser.cpp     |  19 +++++
 monitor/arg_parser.h       |   8 ++
 monitor/nvlink_monitor.cpp | 148 +++++++++++++++++++++++++++++++++++++++-----
 monitor/nvlink_monitor.h   |  33 +++++++--
 test/test_arg_parser.cpp   |  53 +++++++++++++++-
 6 files changed, 250 insertions(+), 30 deletions(-)