Peeka

Peek-a-boo! — The name comes from the children’s game. A diagnostic tool finding a hidden bug feels just like that moment of surprise when someone is found in hide-and-seek.

A runtime diagnostic tool based on Python 3.14 remote debugging protocol (PEP 768), providing non-invasive function observation capabilities similar to Java Arthas.

Quick Start View on GitHub

🌐 Language / 语言: This documentation is also available in Chinese (中文).

本文档也提供中文版本。

What is Peeka?

Peeka is a tool that provides real-time diagnostic capabilities for Python developers in production environments. It can dynamically observe and diagnose running Python applications without modifying target code.

Why Peeka?

Traditional Python debugging methods face many challenges in production environments:

Cannot stop service - Breakpoint debugging blocks the process
Intermittent issues - Need to observe under real load
Code modification difficulties - Cannot deploy freely in production

Peeka is designed specifically to solve these production environment diagnostic challenges.

Core Features

🔍 Non-Invasive Observation

No need to modify target code
Runtime dynamic injection of observation logic
Complete restoration after diagnosis

⚡ Real-Time Diagnosis

Millisecond-level data transmission latency
Streaming observation data push
JSON format output for easy integration with other tools

🛡️ Production-Ready

Performance overhead < 5%
Complete exception capture and recovery mechanisms
Fixed memory buffer to prevent memory expansion

🎯 Conditional Filtering

Safe expression filtering (based on simpleeval)
Flexible filtering syntax (parameters, return values, execution time, etc.)
Blocks all code injection attacks (__import__, eval, exec, etc.)

Quick Start

Installation

pip install peeka

Basic Usage

1. Attach to Target Process

peeka-cli attach <pid>

2. Observe Function Calls

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

# Conditional filtering
peeka-cli watch "module.Class.method" --condition "len(params) > 2"

# Real-time streaming observation
peeka-cli watch "module.Class.method"

3. Data Processing

# Extract results with jq
peeka-cli watch "module.func" | jq 'select(.type == "observation") | .data.result'

# Filter slow calls
peeka-cli watch "module.func" | jq 'select(.type == "observation" and .data.duration_ms > 1)'

Main Features

Command	Function	Status
`attach`	Attach to target process	✅
`watch`	Observe function calls (params, return, time)	✅
`trace`	Trace call chain and execution time	✅
`stack`	Trace call stack	✅
`monitor`	Performance statistics monitoring	✅
`logger`	Dynamically adjust log level	✅
`memory`	Memory analysis	✅
`inspect`	Runtime object inspection	✅
`sc/sm`	Search classes and methods	✅
`reset`	Reset enhancements	✅
`thread`	Thread analysis	✅
`top`	Function-level performance sampling	✅
`detach`	Safely exit diagnostic session	✅

View Complete Command Reference

🎨 Interactive TUI Interface

In addition to CLI commands, Peeka also provides a feature-complete TUI (Text User Interface):

Process Selector - Automatically displays system process list with search filtering
10 Dedicated Views - Dashboard, Watch, Trace, Stack, Monitor, Logger, Memory, Inspect, Threads, Top
Real-Time Data Stream - Streaming observation data with pause/resume/clear support
Auto-Completion - Dynamically retrieve classes and methods from target process
Theme Support - Multiple built-in color themes

# Launch TUI
peeka

# Use number keys to switch views
# 1/2/3/4/5/6/7/8/9/0

View Complete TUI Usage Guide

Comparison with Arthas

Peeka’s design is deeply inspired by Alibaba Arthas, bringing similar diagnostic capabilities to the Python ecosystem.

Python-Specific Advantages

Native JSON Output - All commands output JSONL format for easy automation integration
simpleeval Security Sandbox - Conditional expressions use AST whitelist, fully defending against code injection
Python 3.12+ Performance Optimization - trace command uses sys.monitoring API with < 5% overhead
Lightweight Deployment - No Java runtime required, one-click pip installation

Technical Highlights

Python 3.14 Remote Debugging Protocol (PEP 768)

The core sys.remote_exec(pid, script_path) function is the key to the entire system’s operation, encapsulating complex process attachment, code injection, and execution scheduling logic.

Fallback for Python < 3.14: For older Python versions, uses GDB + ptrace mechanism (reference: pyrasite).

Unix Domain Socket

Uses Unix Domain Socket as the main inter-process communication mechanism:

Higher transmission efficiency - No need for network protocol stack
Stronger security - Only local processes can use
Simple and reliable - Length prefix + JSON format

Safe Conditional Expression Evaluation

Implements safe conditional filtering based on simpleeval library:

AST whitelist - Only allows safe operations
Attribute protection - Blocks reflection attacks
Function blacklist - Disables dangerous functions

Learn Architecture Design

Supported Python Versions

Python Version	Attachment Mechanism	Requirements
3.14+	PEP 768 `sys.remote_exec`	None
3.9-3.13	GDB + ptrace fallback	GDB, python3-dbg, CAP_SYS_PTRACE

License

Peeka is open source under Apache License 2.0.

Acknowledgments

Inspiration: Alibaba Arthas
Security evaluation: simpleeval
Remote debugging protocol: PEP 768