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

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

Processing Speed

Tooling Support

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

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