py-spy for Python Performance

py-spy is a sampling profiler for Python.

Usage

py-spy is a sampling profiler for Python. Where cProfile requires modifying the application, py-spy attaches to running processes; the discipline is non-invasive.

What basic usage looks like:

• py-spy top --pid PID shows hot functions live.: The top mode is interactive. Functions are sorted by CPU time; the engineer sees what is hot in real time; the investigation is direct.
• py-spy record for FlameGraph data.: The record mode produces FlameGraph-compatible output. The team's analysis includes flame graph visualization; the patterns are visible at a glance.
• No application modification.: py-spy does not require modifying the Python application. The application keeps running; py-spy attaches; the profiling is observational.
• Sample-based.: py-spy samples the running interpreter. Each sample captures the call stack; the aggregation produces the profile data; the overhead is minimal.
• Multi-thread support.: py-spy handles multi-threaded Python. Each thread's stack is captured; the team can see what each thread is doing; the analysis is comprehensive.

Basic usage is fast. Engineers who debug Python performance benefit from learning py-spy.

When

py-spy is reached for during Python performance investigations. Slow processes, high-CPU processes, processes under load all are good candidates.

• Slow Python process.: When a Python process is slower than expected, py-spy reveals where the time is spent. The hot path is identified; optimization is targeted.
• Identify the hot path.: Python's flexibility makes performance issues sometimes non-obvious. py-spy's profile data shows actual hot functions; speculation is replaced by data.
• Low overhead.: py-spy's sampling overhead is small. The application's behavior is preserved; the profile data is representative; the discipline is non-invasive.
• Safe in production.: Some teams use py-spy in production. The low overhead makes it tolerable; the data is from real production load; the analysis is realistic.
• Combine with other tools.: py-spy is for CPU profile. Memory profiling uses different tools (memory_profiler, tracemalloc); the discipline includes choosing the right tool.

The when is straightforward. py-spy is the Python-specific reach for CPU investigation.

Alternatives

Beyond py-spy, other profilers exist. Each has trade-offs; the team picks the appropriate tool for the situation.

• cProfile is built-in but heavier.: Python's standard cProfile module is widely available. The overhead is higher than py-spy's; the application must be modified to enable; the data is detailed.
• py-spy beats it for production debugging.: For production investigations, py-spy's non-invasiveness wins. The application does not need modification; the profile is fast; the production impact is bounded.
• Scalene for memory plus CPU.: Scalene profiles both CPU and memory simultaneously. Some investigations need both views; Scalene is the right tool when memory is suspect.
• Pyroscope for continuous.: Pyroscope is a continuous profiling platform. py-spy data can feed Pyroscope; long-running profiles produce trends; the discipline scales beyond ad-hoc investigation.
• Combine for full picture.: Different tools have different strengths. The team uses each where it fits; the comprehensive analysis combines them.

py-spy for Python perf is one of those tooling skills that pays off in Python performance investigations. Nova AI Ops integrates with application performance telemetry, surfaces patterns at scale, and complements local-tool profiling.