Output Formats - The Renacer Book - Pure Rust System Call Tracing
Description: A comprehensive guide to renacer: syscall tracing, DWARF correlation, and performance analysis

# Output Formats

Overview of Renacer's output format system and when to use each format.

## Synopsis

    renacer --format <FORMAT> [OPTIONS] -- <command>

Available Formats:

- `text` - Human-readable strace-like output (default)
- `json` - Machine-parseable JSON for automation
- `csv` - Spreadsheet format for Excel/LibreOffice
- `html` - Interactive visual reports with charts

## Format Overview

Format | Use Case | Human-Readable | Machine-Parseable | Pipe-Friendly
--- | --- | --- | --- | ---
Text | Terminal debugging | ✅ | ❌ | ✅
JSON | Automation, scripting | ❌ | ✅ | ✅
CSV | Spreadsheet analysis | ⚠️ Partial | ✅ | ✅
HTML | Reports, presentations | ✅ | ❌ | ❌

## Text Format (Default)

### Description

Human-readable strace-compatible output optimized for terminal viewing.

### When to Use

- Quick debugging sessions
- Real-time monitoring
- Terminal output (`less`, `grep`)
- Compatibility with strace workflows

### Example

    renacer -- ls /tmp

Output:

    execve("/usr/bin/ls", ["ls", "/tmp"], ...) = 0
    openat(AT_FDCWD, "/tmp", O_RDONLY|O_DIRECTORY) = 3
    getdents64(3, /* 42 entries */, 32768) = 1344
    write(1, "file1.txt\nfile2.txt\n", 20) = 20
    close(3) = 0
    exit_group(0) = ?

Features:

- strace-compatible syntax
- Color-coded output (when terminal supports it)
- Truncated long strings for readability
- Error values highlighted

See Text Format Specification for complete details.

## JSON Format

### Description

Structured JSON output for machine parsing and automation.

### When to Use

- Automated analysis scripts
- Integration with monitoring systems
- Post-processing with `jq`, Python, Node.js
- Data pipelines and ETL workflows

### Example

    renacer --format json -- ls /tmp | jq '.'

Output:

    {
      "command": ["ls", "/tmp"],
      "pid": 12345,
      "syscalls": [
        {
          "name": "openat",
          "args": {
            "dirfd": "AT_FDCWD",
            "pathname": "/tmp",
            "flags": "O_RDONLY|O_DIRECTORY"
          },
          "return_value": 3,
          "duration_ns": 12456,
          "timestamp": "2025-11-19T10:30:45.123456Z"
        }
      ],
      "statistics": {
        "total_syscalls": 42,
        "total_duration_ms": 5.2
      }
    }

Features:

- Full syscall details (no truncation)
- Structured arg parsing
- Timestamp precision (nanoseconds)
- Compatible with modern data tools

Common Queries:

    # Count syscalls by type
    jq '.syscalls | group_by(.name) | map({name: .[0].name, count: length})' trace.json

    # Find slow syscalls (>1ms)
    jq '.syscalls[] | select(.duration_ns > 1000000)' trace.json

    # Extract file operations
    jq '.syscalls[] | select(.name | test("open|read|write"))' trace.json

See JSON Format Specification for schema details.

## CSV Format

### Description

Comma-separated values for spreadsheet analysis and statistical tools.

### When to Use

- Excel/LibreOffice analysis
- Statistical analysis (R, MATLAB)
- Database import (PostgreSQL, MySQL)
- Pivot tables and charts

### Example

    renacer --format csv -- ls /tmp > trace.csv

Output:

    syscall,args,return_value,duration_ns,timestamp
    openat,"AT_FDCWD,/tmp,O_RDONLY|O_DIRECTORY",3,12456,2025-11-19T10:30:45.123456Z
    getdents64,"3,/*42 entries*/,32768",1344,8923,2025-11-19T10:30:45.135790Z
    write,"1,file1.txt\nfile2.txt\n...,20",20,1234,2025-11-19T10:30:45.144713Z
    close,3,0,892,2025-11-19T10:30:45.145605Z

Features:

- Standard CSV format (RFC 4180)
- UTF-8 encoding
- Proper quoting and escaping
- Header row included

Excel Analysis:

1. Open in Excel/LibreOffice
2. Create Pivot Table on `syscall` column
3. Analyze duration statistics (SUM, AVG, MAX)
4. Generate charts (histogram, timeline)

See CSV Format Specification for complete details.

## HTML Format (Sprint 22)

### Description

Interactive visual reports with embedded charts and analysis.

### When to Use

- Presentations and demos
- Sharing results with non-technical stakeholders
- Visual debugging and exploration
- Archiving trace sessions

### Example

    renacer --format html -c -- ls /tmp > report.html
    # Open in browser: firefox report.html

Output Features:

- Interactive syscall table - Sortable, filterable
- Timeline visualization - Gantt-style execution flow
- Statistics charts - Duration histograms, call frequency
- Source correlation - Links to file:line (if `--source` used)
- Responsive design - Mobile-friendly

Screenshot:

    ┌────────────────────────────────────────┐
    │  Renacer Report: ls /tmp              │
    ├────────────────────────────────────────┤
    │  Summary                                │
    │  • Total Syscalls: 42                  │
    │  • Duration: 5.2ms                     │
    │  • Process Tree: 1 process             │
    ├────────────────────────────────────────┤
    │  [Chart: Syscall Frequency]            │
    │  ████████ openat (15)                  │
    │  ██████ read (10)                      │
    │  ████ write (7)                        │
    ├────────────────────────────────────────┤
    │  [Interactive Table]                   │
    │  | Syscall | Duration | Return |       │
    │  |---------|----------|--------|       │
    │  | openat  | 12.4μs   | 3      |       │
    │  | read    | 8.9μs    | 256    |       │
    └────────────────────────────────────────┘

See HTML Format Specification for complete implementation.

## Format Selection Guide

### Quick Decision Tree

    Need human-readable output?
    ├─ Yes → Terminal or presentation?
    │  ├─ Terminal → TEXT (default)
    │  └─ Presentation → HTML
    └─ No → Data processing tool?
       ├─ Scripting (jq, Python) → JSON
       └─ Spreadsheet/Stats → CSV

### By Use Case

#### Debugging in Terminal

Best Format: `text` (default)

    renacer -- ./myapp | grep "openat"
    renacer -- ./myapp | less

#### Automated Monitoring

Best Format: `json`

    renacer --format json -- ./myapp | \
      jq '.syscalls[] | select(.name == "openat" and .return_value < 0)'

#### Statistical Analysis

Best Format: `csv`

    renacer --format csv -c -- ./myapp > trace.csv
    # Import into Excel, create pivot table

#### Team Sharing

Best Format: `html`

    renacer --format html -c -- ./myapp > report.html
    # Email report.html to team

## Combining with Other Features

### Filtering + JSON

    # Trace file operations, output JSON
    renacer --format json -e trace=file -- ls | jq '.syscalls[] | .name'

### Statistics + CSV

    # Generate statistics in CSV format
    renacer --format csv -c -- ./myapp > stats.csv

### DWARF + HTML

    # Source correlation with interactive HTML
    renacer --format html --source -c -- ./myapp > report.html

### Multi-process + JSON

    # Trace fork/exec tree, JSON output
    renacer --format json -f -- make > build-trace.json

## Format Comparison

### Data Completeness

Feature | Text | JSON | CSV | HTML
--- | --- | --- | --- | ---
Syscall name | ✅ | ✅ | ✅ | ✅
Arguments | ⚠️ Truncated | ✅ Full | ⚠️ Truncated | ✅ Full
Return value | ✅ | ✅ | ✅ | ✅
Duration | ⚠️ Optional | ✅ | ✅ | ✅
Timestamp | ❌ | ✅ | ✅ | ✅
Source location | ⚠️ Inline | ✅ | ✅ | ✅ Linked

### Processing Speed

Format | Generate Speed | Parse Speed | File Size
--- | --- | --- | ---
Text | Fastest | N/A (human) | Smallest
JSON | Fast | Fast | Medium
CSV | Fast | Fastest | Small
HTML | Slow | N/A (browser) | Largest

### Tooling Support

Format | Tools
--- | ---
Text | `grep`, `awk`, `sed`, `less`, `vim`
JSON | `jq`, Python (`json`), Node.js, Ruby
CSV | Excel, LibreOffice, R, pandas, SQL
HTML | Web browsers (Chrome, Firefox, Safari)

## Output Redirection

### Stdout (Default)

    # Print to terminal
    renacer --format json -- ls

    # Pipe to another tool
    renacer --format json -- ls | jq '.syscalls | length'

    # Save to file
    renacer --format html -- ls > trace.html

### Stderr for Errors

Renacer writes errors to `stderr`, so output format is clean:

    # Errors go to stderr, JSON goes to stdout
    renacer --format json -- nonexistent_command > trace.json
    # Error: Command not found (on stderr)
    # trace.json is empty

## Performance Considerations

### Format Overhead

Format | Overhead vs Text | Reason
--- | --- | ---
Text | 0% (baseline) | Direct write
JSON | +5-10% | Serialization, escaping
CSV | +3-7% | Quoting, escaping
HTML | +20-30% | Template rendering, charts

Recommendation: Use `text` for minimal overhead, `json`/`csv` for automation, `html` for reports.

### Large Trace Handling

For very large traces (100K+ syscalls):

1. Use streaming formats (`text`, `csv`) instead of buffered (`json`, `html`)
2. Filter syscalls (`-e trace=...`) to reduce volume
3. Use statistics mode (`-c`) for summary instead of full trace

## Format Specification Links

- Text Format - strace-compatible text output
- JSON Format - JSON schema and examples
- CSV Format - CSV specification
- HTML Format - HTML template and interactivity

## Related

- CLI Reference - `--format` flag documentation
- Statistics Mode - Use with `-c` flag
- DWARF Correlation - Source locations in output