peeka 0.1.18

A Python dynamic debugger inspired by Arthas, using Python 3.14's safe external debugger interface

  Peeka

中文 | English

Runtime diagnostics for Python applications. Peeka attaches to a running Python process and lets you observe function calls, traces, stacks, logs, memory, threads, and hot paths without changing application code.

It uses PEP 768 on Python 3.14+, with debugger-based fallback for Python 3.8.1-3.13.

Screenshots

Dashboard	Watch	Trace

Key Features

• Non-invasive - Inject observation logic at runtime and restore it on detach or reset.
• Real-time streaming - Stream observations over Unix domain sockets with low latency.
• Production-minded - Keep overhead bounded with fixed-size buffers and graceful recovery.
• Safe filtering - Evaluate conditions with simpleeval instead of Python eval.
• Dual interface - Use JSONL CLI for agents and automation, or TUI for human exploration.

What Peeka Is For

• Inspect a live service when logs and metrics are not enough.
• Watch function inputs, return values, exceptions, and latency in real time.
• Trace call trees to find where time is spent inside one request or job.
• Capture call stacks, thread state, memory summaries, loggers, and runtime objects.

Two Interfaces

Peeka is designed for two different operators:

Interface	Designed for	Why it exists
CLI	Agents and automation	Stable commands with JSONL output for scripts, pipelines, and coding agents
TUI	Humans	An interactive terminal workspace for exploring live diagnostics without building shell pipelines

Install

# CLI only: best for agents, scripts, and headless environments.
pip install peeka

# CLI + TUI: best when a human will inspect the process interactively.
pip install "peeka[tui]"

Peeka supports Python 3.8.1+. The TUI requires Python 3.9+.

For Python 3.8.1-3.13, attaching needs debugger support: GDB on Linux or LLDB on macOS. On Linux, ptrace permissions must allow attaching to the target process.

Python Support

Python version	CLI	TUI	Attach mechanism	Main dependency
3.14+	Yes	Yes	PEP 768 sys.remote_exec()	Same UID or CAP_SYS_PTRACE
3.9-3.13	Yes	Yes	GDB on Linux, LLDB on macOS	Debugger support and attach permission
3.8.1-3.8.x	Yes	No	GDB on Linux, LLDB on macOS	Debugger support and attach permission

See the documentation for platform-specific setup and troubleshooting.

Quick Start

CLI for agents and automation

# Attach to a running Python process.
peeka-cli attach <pid>

# Observe function calls.
peeka-cli watch "module.Class.method" -n 5

# Trace a call tree.
peeka-cli trace "module.func" -d 3

The CLI emits structured JSONL, so agents and scripts can parse, filter, and persist observations reliably.

TUI for humans

# Launch the TUI.
peeka

The TUI provides an interactive dashboard for browsing watches, traces, stacks, memory, threads, logs, and other runtime views.

Patterns use fully qualified function names such as module.function or module.Class.method.

Core Commands

Command	Purpose
attach / detach	Connect to or leave a target process
watch	Observe function arguments, return values, exceptions, and latency
trace	Trace nested calls and timing breakdowns
stack	Capture call stacks at function entry
monitor / top	Inspect periodic metrics and hot functions
memory / thread / logger	Inspect runtime memory, threads, and loggers
inspect / sc / sm	Inspect objects and search classes or methods
reset	Remove injected observations and restore wrapped functions
run	Start a script with Peeka injected from launch

Gevent Compatibility

Peeka separates its gevent support into two layers:

• Control plane: attach, the in-process agent socket, RPL primitives, and patch-status. This layer avoids target-process monkey-patched socket/threading primitives.
• Data plane: observation commands such as trace and top. These commands report their gevent compatibility in JSONL meta fields when runtime behavior is degraded.

Command	No gevent	gevent imported	gevent patched / active hub
watch	safe	safe	safe
monitor	safe	safe	safe
stack	safe	safe	safe
trace	full trace backend	full trace backend	degraded to wrapper_only
top	frame-walk sampling	frame-walk sampling	greenlet_aware_sampling with greenlet_blind meta

When Peeka detects gevent monkey patching, affected JSONL records include metadata such as:

{
  "meta": {
    "gevent_state": "patched",
    "backend": "wrapper_only",
    "greenlet_blind": false,
    "degraded_reason": "sys.settrace under gevent can violate frame stack invariants; using wrapper-only tracing without recursive call tree"
  }
}

For gevent targets, prefer watch when wrapper-level entry/exit observations are enough. trace remains available, but under patched gevent it uses wrapper-only tracing instead of recursive sys.settrace call trees. top remains available through a chained greenlet.settrace backend that preserves any existing greenlet tracer, while still marking greenlet_blind because suspended greenlets cannot be fully enumerated.

Read More

• Documentation - command reference, TUI usage, installation details, and troubleshooting.
• Scenario guide - practical debugging walkthroughs.
• Demo guide - command-by-command examples against the demo app.
• Attach internals - how Peeka injects diagnostics into a running Python interpreter.
• Roadmap - planned work and product direction.

License

Apache License 2.0

Acknowledgments

• Inspired by Alibaba Arthas
• Safe expression evaluation powered by simpleeval
• Python 3.14+ attach path based on PEP 768