CLI Reference

Complete command-line interface documentation for Renacer.

Synopsis

renacer [OPTIONS] [-- <COMMAND>...]
renacer validate [VALIDATE_OPTIONS] [-- <COMMAND>...]

Subcommands

validate

Golden trace validation for regression detection. See Golden Trace Validation.

Generate baseline:

renacer validate --generate ./golden -- echo "hello"

Validate against baseline:

renacer validate --baseline ./golden -- echo "hello"

Options:

Exit Codes:

Description

Renacer is a pure Rust system call tracer with source correlation capabilities. It uses ptrace to intercept syscalls and optionally correlates them with source code locations using DWARF debug information.

Key Features:

• DWARF-based source correlation
• Advanced filtering (literals, classes, negation, regex)
• Multiple output formats (text, JSON, CSV, HTML)
• Statistical analysis with percentiles
• ML-based anomaly detection
• Multi-process tracing (fork following)
• Transpiler source mapping

Arguments

<COMMAND>...

Command to trace (everything after --)

Example:

renacer -- ls -la

Note: Must be specified after all options and separated by --

Options

Core Tracing Options

-s, --source

Enable source code correlation using DWARF debug info

Sprint: 13 Requirements: Binary compiled with -g flag Example:

renacer --source -- ./myapp

Output:

openat(...) = 3  [main.c:42 in read_config()]
read(3, ...) = 256  [main.c:43 in read_config()]

See DWARF Source Correlation

-T, --timing

Show time spent in each syscall

Example:

renacer --timing -- ls

Output:

openat(...) = 3  <0.000234>

-c, --summary

Show statistics summary (syscall counts and timing) instead of individual calls

Sprint: 19 (enhanced with percentiles) Example:

renacer -c -- ls

Output:

% time     calls    errors syscall
------ --------- --------- ----------------
 45.23       123         0 read
 23.45        45         0 write
  8.12        12         0 openat

See Statistics Mode

Filtering Options

-e, --expr <EXPR>

Filter syscalls to trace using advanced filter syntax

Sprints: 14 (classes), 15 (negation), 16 (regex)

Syntax:

• Literals: -e trace=open,read,write
• Classes: -e trace=file (see Syscall Classes)
• Negation: -e trace=file,!openat (see Negation Operator)
• Regex: -e 'trace=/^open.*/' (see Regex Patterns)

Examples:

# Trace specific syscalls
renacer -e trace=open,read,write -- ls

# Trace all file operations
renacer -e trace=file -- ls

# Trace file ops except openat
renacer -e trace=file,!openat -- ls

# Trace syscalls starting with "open"
renacer -e 'trace=/^open.*/' -- ls

See Filter Syntax

Output Options

--format <FORMAT>

Output format (text, json, csv, html)

Default: text Sprints: 22 (HTML)

Values:

• text - Human-readable text format (default, strace-like)
• json - JSON format for machine parsing
• csv - CSV format for spreadsheet analysis
• html - HTML format with interactive visualizations (Sprint 22)

Examples:

# JSON output
renacer --format json -- ls | jq '.'

# CSV for Excel
renacer --format csv -- ls > trace.csv

# HTML report
renacer --format html -- ls > report.html

See Output Formats

Process Management

-p, --pid <PID>

Attach to running process by PID (mutually exclusive with command)

Example:

renacer -p $(pgrep myapp)

Note: May require elevated privileges depending on /proc/sys/kernel/yama/ptrace_scope

-f, --follow-forks

Follow forks (trace child processes)

Sprint: 18 Example:

renacer -f -- make

Output:

[12345] openat(...) = 3
[12346] execve("/bin/gcc", ...) = 0  ← child process
[12345] waitpid(12346, ...) = 12346

See Multi-Process Tracing

Advanced Analysis

--function-time

Enable function-level timing with DWARF correlation

Sprint: 13 Requires: --source or automatic DWARF detection Example:

renacer --function-time -- ./myapp

Output:

Function: read_config (config.c:42)
  openat: 2.3ms
  read: 45.8ms
  close: 0.1ms
  Total: 48.2ms

See Function Profiling

--stats-extended

Enable extended statistics with percentiles and anomaly detection

Sprint: 19-20 Requires: -c flag Example:

renacer -c --stats-extended -- ./myapp

Output:

read: p50=1.2ms, p95=3.4ms, p99=8.7ms
  Anomalies: 12 calls >3σ (Z-score method)

See Percentile Analysis, Anomaly Detection

Anomaly Detection

--anomaly-threshold <SIGMA>

Anomaly detection threshold in standard deviations

Default: 3.0 Sprint: 20 Example:

renacer -c --stats-extended --anomaly-threshold 2.5 -- ./myapp

--anomaly-realtime

Enable real-time anomaly detection

Sprint: 20 Example:

renacer --anomaly-realtime -- ./myapp

See Real-Time Anomaly Detection

--anomaly-window-size <SIZE>

Sliding window size for real-time anomaly detection

Default: 100 Example:

renacer --anomaly-realtime --anomaly-window-size 50 -- ./myapp

HPU Acceleration

--hpu-analysis

Enable HPU-accelerated analysis (GPU/TPU if available)

Sprint: 21 Requires: NumPy, SciPy, scikit-learn (Python) Example:

renacer --format json --hpu-analysis -- ./myapp

See HPU Acceleration

--hpu-cpu-only

Force CPU backend (disable GPU acceleration)

Example:

renacer --hpu-analysis --hpu-cpu-only -- ./myapp

Machine Learning

--ml-anomaly

Enable ML-based anomaly detection using Aprender

Sprint: 23 Requires: Aprender library Example:

renacer --format json --ml-anomaly -- ./myapp

See Machine Learning

--ml-clusters <N>

Number of clusters for ML anomaly detection

Default: 3 Min: 2 Example:

renacer --ml-anomaly --ml-clusters 5 -- ./myapp

--ml-compare

Compare ML results with z-score anomaly detection

Example:

renacer -c --stats-extended --ml-anomaly --ml-compare -- ./myapp

Transpiler Source Mapping

--transpiler-map <FILE>

Path to transpiler source map JSON file

Sprint: 24-28 (5-phase implementation) Example:

renacer --transpiler-map out.map -- ./transpiled_app

See CHANGELOG for 5-phase details

--show-transpiler-context

Show verbose transpiler context (Python/Rust, C/Rust correlation)

Sprint: 25 Example:

renacer --transpiler-map out.map --show-transpiler-context -- ./app

--rewrite-stacktrace

Rewrite stack traces to show original source locations

Sprint: 26 Example:

renacer --transpiler-map out.map --rewrite-stacktrace -- ./app

--rewrite-errors

Rewrite compilation errors to show original source locations

Sprint: 27 Example:

renacer --transpiler-map out.map --rewrite-errors -- cargo build

Debugging

--profile-self

Enable self-profiling to measure Renacer's own overhead

Example:

renacer --profile-self -- ls

Output:

Renacer overhead: 2.3ms (14.5% of total time)

--debug

Enable debug tracing output to stderr

Example:

renacer --debug -- ls 2> debug.log

Informational

-h, --help

Print help message (use -h for summary, --help for detailed)

Example:

renacer --help

-V, --version

Print version

Example:

renacer --version
# Output: renacer 0.4.1

Common Workflows

Basic Tracing

# Trace a command
renacer -- ls -la

# Attach to running process
renacer -p 1234

# Follow forks (trace child processes)
renacer -f -- make

With DWARF Correlation

# Enable source correlation
renacer --source -- ./myapp

# Function profiling
renacer --function-time -- ./myapp

# Both source + function profiling
renacer --source --function-time -- ./myapp

Filtering

# Trace specific syscalls
renacer -e trace=open,read,write -- ls

# Trace all file operations
renacer -e trace=file -- ls

# Exclude specific syscalls
renacer -e trace=file,!openat -- ls

# Regex patterns
renacer -e 'trace=/^open.*/' -- ls

Statistics & Analysis

# Basic statistics
renacer -c -- ls

# Extended statistics with percentiles
renacer -c --stats-extended -- ./myapp

# Anomaly detection
renacer -c --stats-extended --anomaly-threshold 2.5 -- ./myapp

# Real-time anomaly monitoring
renacer --anomaly-realtime -- ./myapp

Output Formats

# JSON for jq/Python
renacer --format json -- ls | jq '.syscalls[] | select(.name == "openat")'

# CSV for Excel
renacer --format csv -- ls > trace.csv

# HTML report
renacer --format html -c -- ls > report.html

Exit Codes

See Exit Codes for detailed codes.

Related

• Filter Syntax - Complete filtering reference
• Output Formats - Format specifications
• Tracing Options - Detailed tracing flags
• Analysis Flags - Advanced analysis options