Skip to content

Add a trace JSONL pretty-printer CLI helper #39

Description

@madeinplutofabio

Summary

Add a small CLI tool that takes a per-call NCP trace file (<trace_id>.jsonl) and prints a human-readable timeline. Raw JSONL is hard to skim when debugging a graph run; a pretty-printer is a frequent adopter pain point.

Why this is a good first issue

  • Self-contained: one new directory under tools/ or a single script.
  • Either Python (stdlib only) or Rust is acceptable. Pick the language you are comfortable with.
  • Acceptance criteria are concrete and testable.
  • No protocol-level or runtime-internal knowledge required. Just JSON parsing and formatting.

Acceptance criteria

  • New tool at tools/trace-pretty/ (Rust binary) OR tools/trace_pretty.py (Python stdlib).
  • Takes a path to a .jsonl trace file as positional arg.
  • Reads the file, parses each line as JSON, prints a human-readable timeline. Suggested columns: step | node_id | brick_id | result_type | latency_ms.
  • Prints a summary footer: total steps, total latency, count by result_type.
  • Exits 0 on success, non-zero on file-not-found or malformed line.
  • README in the tool's directory explains the trace format briefly plus shows example output against a real trace from examples/graphs/echo-pipeline/.

Out of scope

  • Real-time tailing (tail -f mode).
  • HTML or web rendering.
  • Cross-trace aggregation.

Where to read

  • runtime/src/trace.rs for the JSONL record shapes (runtime_info, invoke).
  • spec/ncp-v0.2.3.md §11 (Tracing) for the canonical schema.
  • A real example trace: run ncp-mcp-server with --trace-dir and perform a tools/call via examples/mcp/ci_smoke.py or the manual smoke recipe in examples/mcp/echo-pipeline-mcp-smoke.md.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:traceTracing infrastructure (TraceSink, JSONL format, tooling)good first issueGood for newcomers

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions