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

# HTML Output Format

Renacer provides HTML output format for generating rich visual trace reports with styled tables, embedded CSS, and interactive features.

> TDD-Verified: All examples validated by `tests/sprint22_html_output_tests.rs`

## Overview

HTML output format generates standalone HTML documents containing syscall trace data in a visually appealing, interactive format:

- Standalone Documents: Self-contained HTML with embedded CSS (no external dependencies)
- Responsive Design: Modern CSS with hover effects and zebra striping
- XSS Prevention: Automatic HTML escaping for security
- Statistics Integration: Combined with `-c` flag for visual statistics tables
- Optional Columns: Timing (-T) and source location (--source) support
- Error Highlighting: Visual distinction for failed syscalls

## Basic Usage

### Generate HTML Report

    renacer --format html -- ls -la > trace.html

Tested by: `test_html_format_flag_accepted`, `test_html_output_basic`

This generates a complete HTML document with:

- Syscall trace table
- Embedded CSS styles
- Responsive layout

### View HTML Report

    # Generate and open in browser
    renacer --format html -- cargo test > report.html
    xdg-open report.html  # Linux
    open report.html      # macOS

Tested by: `test_html_output_basic`

## HTML Document Structure

### Basic HTML Output

    $ renacer --format html -- echo "test" > trace.html

Generated HTML:

    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Renacer Trace Report</title>
        <style>
            /* Embedded CSS styles */
            body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
            table { border-collapse: collapse; width: 100%; }
            th { background-color: #4a90d9; color: white; }
            ...
        </style>
    </head>
    <body>
        <h1>Syscall Trace Report</h1>
        <table>
            <tr><th>Syscall</th><th>Arguments</th><th>Result</th></tr>
            <tr><td class="syscall">write</td><td class="args">1, "test\n", 5</td><td class="result">5</td></tr>
            <tr><td class="syscall">exit_group</td><td class="args">0</td><td class="result">?</td></tr>
        </table>
        <div class="footer">Generated by Renacer - System Call Tracer</div>
    </body>
    </html>

Tested by: `test_html_output_basic`, `test_html_output_contains_syscalls`

## Integration with Flags

### With Statistics Mode (-c)

    renacer --format html -c -- cargo build > build-stats.html

Tested by: `test_html_output_with_statistics`

Output includes:

1. Syscall Trace Table - Individual syscall events
2. Statistics Summary Table - Call counts, timing, errors

    <h2>Statistics Summary</h2>
    <table class="stats-table">
        <tr><th>% time</th><th>seconds</th><th>usecs/call</th><th>calls</th><th>errors</th><th>syscall</th></tr>
        <tr><td>45.23</td><td>0.012345</td><td>1234</td><td>10</td><td>0</td><td class="syscall">read</td></tr>
        <tr><td>32.15</td><td>0.008765</td><td>876</td><td>10</td><td>0</td><td class="syscall">write</td></tr>
    </table>

### With Timing Mode (-T)

    renacer --format html -T -- ./my-app > trace-timing.html

Tested by: `test_html_output_with_timing`

Output includes Duration column:

    <table>
        <tr><th>Syscall</th><th>Arguments</th><th>Result</th><th>Duration</th></tr>
        <tr><td class="syscall">write</td><td class="args">...</td><td>5</td><td class="duration">1234 us</td></tr>
    </table>

### With Filtering (-e)

    renacer --format html -e trace=file -- ./app > file-ops.html

Tested by: `test_html_output_with_filtering`

HTML output includes only filtered syscalls (e.g., `open`, `read`, `write`, `close` for `trace=file`).

### With Source Correlation (--source)

    renacer --format html --source -- ./my-binary > trace-with-source.html

Output includes Source column:

    <table>
        <tr><th>Syscall</th><th>Arguments</th><th>Result</th><th>Source</th></tr>
        <tr><td class="syscall">write</td><td>...</td><td>5</td><td class="source">src/main.rs:42</td></tr>
    </table>

## CSS Styling and Visual Features

### Embedded CSS Styles

HTML output includes embedded CSS for:

- Modern Font Stack: `-apple-system`, `BlinkMacSystemFont`, `Segoe UI`, `Roboto`
- Table Styling: Borders, padding, box-shadow
- Zebra Striping: Alternating row colors (`nth-child(even)`)
- Hover Effects: Row highlighting on mouse hover
- Color Coding:
  - Syscall names: Blue (`#0066cc`)
  - Error results: Red (`#cc0000`)
  - Source locations: Gray (`#888`)

Tested by: `test_html_output_standalone`

### Standalone Output

HTML output is completely standalone with:

- ✅ Embedded CSS (no external stylesheet links)
- ✅ No JavaScript dependencies
- ✅ No external fonts or images
- ✅ Single-file distribution

Tested by: `test_html_output_standalone`

This ensures HTML reports can be:

- Shared via email
- Archived offline
- Opened without internet connection

## Security Features

### XSS Prevention

HTML output automatically escapes special characters to prevent XSS attacks:

    $ renacer --format html -- echo "<script>alert('xss')</script>" > safe.html

Tested by: `test_html_output_escape_special_chars`

Escaped characters:

- `<` → `&lt;`
- `>` → `&gt;`
- `&` → `&amp;`
- `"` → `&quot;`
- `'` → `&#39;`

Example output:

    <td class="args">&lt;script&gt;alert(&#39;xss&#39;)&lt;/script&gt;</td>

The HTML output will display `<script>alert('xss')</script>` as text (safe) instead of executing it as code.

### Security Best Practices

1. Always use `--format html` for untrusted input (syscall arguments from external sources)
2. HTML escaping is automatic (no configuration needed)
3. No inline JavaScript - CSS-only styling
4. Safe to open in any browser without security warnings

## Table Structure

### Basic Table Layout

    <table>
        <tr>
            <th>Syscall</th>
            <th>Arguments</th>
            <th>Result</th>
        </tr>
        <tr>
            <td class="syscall">write</td>
            <td class="args">1, "test", 4</td>
            <td class="result">4</td>
        </tr>
    </table>

Tested by: `test_html_output_has_table_structure`

### Dynamic Columns

Table columns adapt based on flags:

Flags | Columns
--- | ---
(none) | Syscall, Arguments, Result
`-T` | Syscall, Arguments, Result, Duration
`--source` | Syscall, Arguments, Result, Source
`-T --source` | Syscall, Arguments, Result, Duration, Source

### Error Highlighting

Failed syscalls (negative result) are highlighted in red:

    <td class="result result-error">-2</td>  <!-- ENOENT -->
    <td class="result result-error">-13</td> <!-- EACCES -->
    <td class="result">0</td>                <!-- Success -->

CSS:

    .result-error {
        color: #cc0000;
    }

## Practical Examples

### Example 1: Build Performance Analysis

    $ renacer --format html -c -T -- cargo build > build-report.html

Tested by: `test_html_output_with_statistics`, `test_html_output_with_timing`

Use case: Analyze build performance with visual statistics table

Report includes:

- Individual syscall traces with timing
- Statistics summary sorted by time consumption
- Percentage breakdown of I/O operations

### Example 2: Debugging I/O Issues

    $ renacer --format html -e trace=file -T -- ./slow-app > io-trace.html

Tested by: `test_html_output_with_filtering`, `test_html_output_with_timing`

Use case: Focus on file I/O operations with timing

Report shows:

- Only file-related syscalls (open, read, write, close, etc.)
- Duration column for identifying slow I/O
- Easy-to-read table format for non-technical stakeholders

### Example 3: Sharing Trace Results

    $ renacer --format html -c -T --source -- ./app > detailed-trace.html
    # Email detailed-trace.html to team members

Use case: Share comprehensive trace report with team

Benefits:

- Standalone HTML file (no dependencies)
- Professional visual presentation
- Source correlation for debugging
- Statistics summary for overview

## Backward Compatibility

HTML format works alongside existing formats:

    renacer --format json -- ./app > trace.json  # JSON still works
    renacer --format csv -- ./app > trace.csv    # CSV still works
    renacer --format html -- ./app > trace.html  # New HTML format

Tested by: `test_html_output_backward_compatibility`

Default format remains text (strace-compatible).

## Comparison with Other Formats

Feature | Text | JSON | CSV | HTML
--- | --- | --- | --- | ---
Human-readable | ✅ | ❌ | ⚠️ | ✅
Visual styling | ❌ | ❌ | ❌ | ✅
Programmatic parsing | ⚠️ | ✅ | ✅ | ❌
Statistics integration | ✅ | ✅ | ✅ | ✅
Standalone | ✅ | ✅ | ❌ | ✅
Shareable | ✅ | ⚠️ | ⚠️ | ✅
Browser viewable | ❌ | ⚠️ | ❌ | ✅

Use HTML when:

- Sharing reports with non-technical stakeholders
- Creating documentation or presentations
- Need visual distinction (error highlighting, hover effects)
- Archiving reports for later review

Use JSON/CSV when:

- Post-processing with scripts or tools
- Integrating with CI/CD pipelines
- Machine parsing required

## Troubleshooting

### HTML Output Contains Child Process Output

Problem:

    $ renacer --format html -- bash -c "echo test" > trace.html
    # HTML contains "test" text from child process

Solution: HTML is generated after trace completes. Child process output appears before `<!DOCTYPE html>`.

Workaround: Redirect child stderr/stdout:

    renacer --format html -- bash -c "echo test >/dev/null" > clean-trace.html

### HTML Not Rendering Properly

Check:

1. File extension: Ensure file ends with `.html`
2. Browser: Try different browser (Firefox, Chrome, Safari)
3. Encoding: HTML uses UTF-8 charset (line 191 in implementation)

Tested by: `test_html_output_basic`

### Missing Statistics Table

Cause: `-c` flag not provided

Solution:

    renacer --format html -c -- ./app > with-stats.html

Tested by: `test_html_output_with_statistics`

## Performance

- Generation time: <1ms for typical traces (<1000 syscalls)
- File size: ~2-5KB base HTML + ~50-100 bytes per syscall
- Browser performance: Tested up to 10,000 rows (smooth scrolling)

Scalability:

- ✅ <1000 syscalls: Excellent performance
- ✅ 1K-10K syscalls: Good performance (some browser lag on old hardware)
- ⚠️ >10K syscalls: Consider filtering or using CSV for analysis

## Summary

HTML output format provides:

- ✅ Visual trace reports with modern CSS styling
- ✅ Standalone HTML (no external dependencies)
- ✅ XSS prevention via automatic HTML escaping
- ✅ Statistics integration with `-c` flag
- ✅ Responsive design with hover effects and color coding
- ✅ Security-first approach (no JavaScript, safe for untrusted input)
- ✅ Shareable single-file reports
- ✅ Professional presentation for non-technical audiences

All examples tested in: `tests/sprint22_html_output_tests.rs`

## Related

- JSON Output Format - Machine-readable output
- CSV Output Format - Spreadsheet-compatible output
- Statistics Mode - Call counts and timing
- HTML Reports Example - Practical use cases