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

# Quick Start

This guide will get you tracing syscalls in under 5 minutes.

## Your First Trace

The simplest way to use renacer is to trace a command:

    renacer -- ls

You'll see output like:

    openat(AT_FDCWD, "/etc/ld.so.cache", O_RDONLY|O_CLOEXEC) = 3
    openat(AT_FDCWD, "/lib/x86_64-linux-gnu/libc.so.6", O_RDONLY|O_CLOEXEC) = 3
    openat(AT_FDCWD, ".", O_RDONLY|O_NONBLOCK|O_CLOEXEC|O_DIRECTORY) = 3
    getdents64(3, [...], 32768) = 1024
    write(1, "file1.txt\nfile2.txt\n", 20) = 20
    exit_group(0) = ?

Each line shows:

- Syscall name (e.g., `openat`, `write`)
- Arguments (e.g., file paths, flags, buffers)
- Return value (e.g., file descriptor `3`, byte count `20`)

## Filter Syscalls

Show only file operations:

    renacer -e trace=file -- cat /etc/hostname

Output shows only file-related syscalls (openat, read, close):

    openat(AT_FDCWD, "/etc/hostname", O_RDONLY) = 3
    read(3, "my-hostname\n", 4096) = 12
    close(3) = 0

## Get Statistics

Use `-c` to see summary statistics:

    renacer -c -- echo "test"

Output:

    % time     seconds  usecs/call     calls    errors syscall
    ------ ----------- ----------- --------- --------- ----------------
     45.23    0.000123         123         1         0 write
     32.15    0.000087          87         1         0 openat
     22.62    0.000062          62         1         0 close
    ------ ----------- ----------- --------- --------- ----------------
    100.00    0.000272                     3         0 total

## Export to JSON

Machine-readable output for integration:

    renacer --format json -- echo "test" > trace.json

The JSON contains structured syscall data:

    {
      "pid": 12345,
      "syscall": "write",
      "args": ["1", "\"test\\n\"", "5"],
      "return_value": 5,
      "timestamp": 1634567890.123456
    }

## Common Use Cases

### Debug Slow Operations

    # Show timing for each syscall
    renacer -T -- slow-program

### Monitor Specific Syscalls

    # Only show read and write calls
    renacer -e trace=read,write -- my-app

### Exclude Syscalls

    # Show all syscalls except close
    renacer -e trace=!close -- my-app

### Export to CSV

    # Create spreadsheet-friendly output
    renacer --format csv -c -- my-app > stats.csv

## What's Next?

- Basic Tracing - Learn tracing fundamentals
- Filtering Syscalls - Advanced filtering techniques
- Function Profiling - Find performance bottlenecks
- Anomaly Detection - Detect unusual behavior

All examples in this guide are validated by the test suite in `tests/sprint*.rs`.