# stacker

**Repository Path**: mirrors_arangodb/stacker

## Basic Information

- **Project Name**: stacker
- **Description**: Dump stack traces for a running process with a consistent snapshot and registers
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-02
- **Last Updated**: 2026-01-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Stacker

A multi-architecture stack tracer for Linux processes that supports both x86_64 and ARM64 architectures.

## Features

- **Multi-architecture support**: Works on both x86_64 and ARM64 (aarch64) Linux systems
- **Thread discovery**: Automatically finds and traces all threads in a target process
- **Register dumping**: Shows architecture-specific CPU registers for each thread
- **Stack unwinding**: Walks the call stack using architecture-appropriate methods
- **Symbol resolution**: Resolves addresses to function names, file names, and line numbers using built-in DWARF parsing
- **Minimal process interruption**: Quickly captures stack traces and detaches to minimize impact

## Supported Architectures

- **x86_64**: Full support with x86_64-specific register names and stack walking
- **ARM64 (aarch64)**: Full support with ARM64-specific register names and stack walking

## Dependencies

- Linux kernel with ptrace support
- Rust toolchain

## Building

```bash
cargo build --release
```

The program will automatically compile with the appropriate architecture-specific code based on your target platform.

## Usage

```bash
stacker <SUBCOMMAND> [OPTIONS]
```

### Commands

- **capture**: Capture stack traces into a JSON file
  - **options**: `--pid <pid>`, `--output <path>`
  - **example**:
    ```bash
    stacker capture --pid 1234 --output capture.json
    ```

- **symbolize**: Symbolize a previously captured JSON file
  - **options**: `--input <path>`, `--executable <path>`
  - **example**:
    ```bash
    stacker symbolize --input capture.json --executable /proc/1234/exe
    ```

- **onephase**: Capture and symbolize in one go (no file I/O)
  - **options**: `--pid <pid>`
  - **example**:
    ```bash
    stacker onephase --pid 1234
    ```

#### Notes on symbolization

- **Shared libraries and debug symbols**: If the traced process uses shared libraries, the exact libraries (and ideally their debug symbol packages) must be installed and discoverable during symbolization, especially when symbolizing on a different machine. Otherwise, symbol resolution may be incomplete or missing file/line information.

## Output

The program displays:

1. **Process information**: PID and architecture being traced
2. **Thread discovery**: Number of threads found
3. **Timing information**: How long the process was stopped
4. **Memory maps**: Process memory layout and loaded libraries
5. **Per-thread information**:
   - Thread ID (TID)
   - Thread name (from `/proc/{pid}/task/{tid}/comm`)
   - CPU registers (architecture-specific)
   - Stack trace with symbol information

### Sample Output

```
Stacker v0.1.0 - Multi-architecture stack tracer
Target architecture: x86_64
Attaching to process 1234
Found 3 threads
Process was stopped for: 2.345ms

Symbolizing stack traces...

=== Thread 1 (TID: 1234, Name: 'main') ===
  Registers (x86_64):
    RAX: 0x00007f8b8c0d4000  RBX: 0x0000000000000000  ...
    
  #0: 0x00007f8b8c0d4567 in main at src/main.rs:42
  #1: 0x00007f8b8c0d3456 in std::rt::lang_start at /rustc/.../library/std/src/rt.rs:145
  ...
```

## Architecture-Specific Details

### x86_64
- **Registers**: Shows RAX, RBX, RCX, RDX, RSI, RDI, RBP, RSP, R8-R15, RIP, EFLAGS, segment registers
- **Stack walking**: Uses RBP (frame pointer) to walk the stack frames
- **Calling convention**: Follows x86_64 System V ABI

### ARM64 (aarch64)
- **Registers**: Shows X0-X30, SP, PC, PSTATE
- **Stack walking**: Uses X29 (frame pointer) to walk the stack frames  
- **Calling convention**: Follows ARM64 AAPCS calling convention

## How It Works

1. **Process Attachment**: Uses ptrace to attach to the target process and all its threads
2. **Register Capture**: Reads CPU registers from each thread using `PTRACE_GETREGS`
3. **Stack Walking**: Follows frame pointers to unwind the call stack
4. **Quick Detachment**: Detaches from all threads to minimize process interruption
5. **Symbol Resolution**: Uses built-in DWARF parsing to resolve addresses to human-readable symbols

## Requirements

- Linux operating system
- One of the supported architectures (x86_64 or ARM64)
- Target process with debug symbols for best results
- Sufficient privileges to ptrace the target process

## Limitations

- Requires ptrace permissions (may need to run as root or adjust ptrace_scope)
- Stack unwinding may not work for all calling conventions or optimized code
- Symbol resolution depends on debug information availability
- Currently supports Linux only

## Cross-Compilation

To build for a different architecture:

```bash
# For ARM64 from x86_64
cargo build --target aarch64-unknown-linux-gnu

# For x86_64 from ARM64  
cargo build --target x86_64-unknown-linux-gnu
```

## License

This project is open source. See the source code for details.