peeka 0.1.20

  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:

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

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"

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

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.

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