DOCSEARCHbyAlgolia
Submit Docs

witr Causality Tracing Tool

repository·main·Indexed 12 days ago

https://github.com/pranshuparmar/witr

A causality tracing tool that helps developers and system administrators understand the origin of running processes, ports, containers, or files by tracing the exact chain of command that started them. It features a TUI for real-time exploration of processes, ports, containers, and file locks, and supports Linux, macOS, Windows, and FreeBSD.

Tokens
7K
Snippets
24
Records
32
Agent score
97%

What's inside witr

  1. Overview of witr

    main

    What is witr?

    witr is a causality tracing tool designed to answer the question: "Why is this running?"

    While standard system tools like ps, top, lsof, ss, systemctl, or docker ps show you what is currently running, they require you to manually correlate data to understand the cause. witr automates this by explicitly tracing the chain of causality. It identifies how a process, port, container, or file was started and which chain of systems (e.g., supervisors, containers, services, or shells) is responsible for its existence.

    Key Capabilities:

    • Trace Causality: Trace any process, port, container, or file back to its exact origin.
    • Multiple Output Formats: Provides human-readable output, machine-readable JSON, or an interactive TUI (Terminal User Interface).
    • Cross-Layer Visibility: Uncovers indirect or non-obvious startup chains across different layers of the system.

  2. How witr works: The Process Question Concept

    main

    witr operates on the core concept that everything is a process question.

    Regardless of whether you query a port, a service, a container, or a command, witr maps these entities back to PIDs. Once a PID is identified, witr builds a causal chain to explain the process's existence by answering:

    1. What is running?
    2. How did it start?
    3. What is keeping it running?
    4. What context does it belong to?

  3. Format and filter witr output

    main

    You can customize the witr output for different use cases, such as scripting, debugging, or visual inspection:

    • Visualizing Ancestry: Use --tree to show the process hierarchy as a tree, or --short to show only the ancestry line.
    • Filtering Content: Use --warnings to show only suspicious environment variables, arguments, or parents. Use --env to display only the process's environment variables.
    • Machine-Readable Formats: Use --json for JSON output or --short for single-line output suitable for scripts.
    • Display Modes: Use --verbose for extended information (memory, I/O, file descriptors) or -i, --interactive for a TUI (Terminal User Interface).
    • Output Styling: Use --no-color to disable colorized output for CI/CD or piping.
    # Show the full process ancestry (who started whom)
witr postgres --tree

# Show only warnings (suspicious env, arguments, parents)
witr docker --warnings

# Display only environment variables of the process
witr node --env

# Short, single-line output (useful for scripts)
witr sshd --short

# Disable colorized output (CI or piping)
witr redis --no-color

# Output machine-readable JSON
witr chrome --json

# Show extended process information (memory, I/O, file descriptors)
witr mysql --verbose

# Combine flags: inspect port, show environment variables, output JSON
witr --port 8080 --env --json

  4. Quick Install witr via script

    main

    For a fast setup, use the official installation scripts. These scripts automatically detect your OS and architecture, download the latest binary, and install it to standard system paths.

    Unix (Linux, macOS & FreeBSD): Installs the binary to /usr/local/bin/witr and the man page to /usr/local/share/man/man1/witr.1. You can override the default path using the INSTALL_PREFIX environment variable.

    Windows (PowerShell): Downloads the latest zip, extracts witr.exe to %LocalAppData%\witr\bin, and adds that directory to your User PATH.

    ### Unix (Linux, macOS & FreeBSD)
```bash
curl -fsSL https://raw.githubusercontent.com/pranshuparmar/witr/main/install.sh | bash

    Windows (PowerShell)

    irm https://raw.githubusercontent.com/pranshuparmar/witr/main/install.ps1 | iex

  5. Use the witr CLI to inspect processes

    main

    The witr CLI tool explains why a process, port, or file is running by tracing its ancestry. You can provide process names, PIDs, ports, files, or container names as inputs to investigate system activity.

    # Inspect a running process by name
witr nginx

# Look up a process by PID
witr --pid 1234

# Find the process listening on a specific port
witr --port 5432

# Find the process holding a file open
witr --file /var/lib/dpkg/lock

# Inspect a container by name
witr --container redis

# Inspect a process by name with exact matching (no fuzzy search)
witr bun --exact

  6. Enable shell completions for witr

    main

    To enable tab completion for all witr flags, add the following to your shell configuration file:

    Bash: echo 'eval "$(witr completion bash)"' >> ~/.bashrc && source ~/.bashrc

    Zsh: echo 'eval "$(witr completion zsh)"' >> ~/.zshrc

    Fish: witr completion fish > ~/.config/fish/completions/witr.fish (for permanent use)

    PowerShell: witr completion powershell | Out-String | Invoke-Expression (add to your $PROFILE for permanent use)

    echo 'eval "$(witr completion bash)"' >> ~/.bashrc
source ~/.bashrc

  7. Launch the Interactive Mode (TUI)

    main

    Running witr without any arguments or with the -i flag launches the Interactive Mode (TUI). This provides a real-time, terminal-based dashboard with four tabs for exploring system state:

    • Processes Tab: Live, sortable, filterable list of all running processes with an ancestry tree side panel.
    • Ports Tab: Open/listening ports with owning processes. Use a to toggle between LISTEN-only and ALL.
    • Containers Tab: Unified list of running containers (Docker, Podman, nerdctl, K8s/crictl, Incus, LXC, LXD, and FreeBSD jails) with detailed views for mounts, networks, and compose metadata.
    • Locks Tab: System-wide file locks. Press a to switch to "all open files" mode (merging locked entries with interesting open fds) and use / to search.

    Features:

    • Process Actions: Send signals (Kill, Terminate, Pause, Resume) or Renice processes (Unix only).
    • Mouse Support: Navigate, sort, and click rows.
    • Auto-Refresh: Lists refresh automatically (starting at 3s, backing off under load).
    • Adaptive Theme: Colors adapt to light/dark terminal backgrounds.
    witr -i

  8. Install witr via package managers

    main

    witr is available through numerous package managers across different ecosystems. Using a package manager is recommended for easier updates.

    Common Package Managers:

    • APT (Debian/Ubuntu): sudo apt install witr (Note: may lag behind GitHub releases)
    • Homebrew (macOS/Linux): brew install witr
    • MacPorts (macOS): sudo port install witr
    • Conda/Mamba/Pixi: conda install -c conda-forge witr or pixi global install witr
    • Arch Linux (AUR): yay -S witr-bin or paru -S witr-bin
    • Winget (Windows): winget install -e --id PranshuParmar.witr
    • NPM (Cross-platform): npm install -g @pranshuparmar/witr
    • Scoop (Windows): scoop install main/witr
    • Chocolatey (Windows): choco install witr
    • GNU Guix: guix install witr
    • Mise: mise use github:pranshuparmar/witr
    # Example: Homebrew
brew install witr

# Example: NPM
npm install -g @pranshuparmar/witr

  9. Deploy the playground to GitHub Pages

    main

    The playground is designed to be served directly from the docs/ folder without a build step. To deploy:

    1. Go to your GitHub repository Settings.
    2. Navigate to Pages.
    3. Under Build and deployment > Source, select Deploy from a branch.
    4. Set the branch to main and the folder to /docs.

    Note: The .nojekyll file ensures that files like fixtures/_meta.json are served verbatim without Jekyll processing.

  10. Run witr with elevated permissions

    main

    To access full system information, such as details for processes owned by other users, system services, or protected system directories, you must run witr with elevated privileges depending on your OS.

    • Linux/FreeBSD: Use sudo.
    • macOS: Use sudo. Note that macOS System Integrity Protection (SIP) may still restrict access to certain system process details even with sudo.
    • Windows: Run your terminal (e.g., PowerShell) as Administrator.
    # Linux/FreeBSD
sudo witr [your arguments]
    # macOS
sudo witr [your arguments]
    # Windows (Run in Administrator PowerShell)
.\witr.exe [your arguments]

  12. Regenerate golden fixtures for the playground

    main

    If you change a world file (in worlds/) or modify witr's output format, you must regenerate the golden fixtures to ensure the JS engine remains faithful to the real witr binary. The generator is build-tagged and does not affect standard builds.

    From the repository root, run the Go generator and then the fixture check script to verify byte-for-byte equality using a pinned clock.

    # from the repo root
go run -tags fixtures ./docs/fixtures/gen
node docs/scripts/check-fixtures.mjs