zprofile

library1.0.13pypypi✓ verified 79d ago

zprofile provides statistical (sampling) CPU and wall-clock profilers for Python applications. Derived from the `google-cloud-profiler`, it allows users to collect profiling data with minimal overhead, making it suitable for production environments. The library outputs data in the `pprof` format, which can then be visualized using the external `go tool pprof`. The current version is 1.0.13, last released in August 2023, indicating a maintenance-oriented release cadence.

observability

pip install zprofile

github ↗package ↗

INSTALL

IMPORT

SIG · ZPROFILE

zprofile

observabilitypythonv1.0.13

Install

2.1s avg

Import

—

Disk

22MB

Pass rate

4/ 10

Env Coverage4 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.13 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

✓ 2.1s

py 3.11

✕ build_error

✓ 1.98s

py 3.12

✕ build_error

✓ 1.9s

py 3.13

✕ build_error

py 3.9

✕ build_error

✓ 2.6s

22MB installed

● package 22MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CPUProfiler

✓ import zprofile

✗ from zprofile import CPUProfiler

This quickstart demonstrates how to use the `CPUProfiler` to collect CPU usage statistics over a 10-second period for a simulated busy-wait function. The collected profile data is saved to a file named `profile.pprof`, which can then be visualized using the `go tool pprof` utility.

import time from zprofile.cpu_profiler import CPUProfiler def busy_wait(duration): end_time = time.time() + duration while time.time() < end_time: pass def main_function(): print("Starting CPU intensive task...") busy_wait(2) # Simulate CPU work print("CPU task complete.") p = CPUProfiler() profile_data = p.profile(10) # Profile for 10 seconds with open("profile.pprof", "wb") as f: f.write(profile_data) print("CPU profile data written to profile.pprof") print("Use 'go tool pprof -http=:8080 profile.pprof' to view the profile.")

Debug

Known issues

gotchaTo visualize the `.pprof` output files, you must install the Go programming language SDK and use its `go tool pprof` utility. This tool is not bundled with the `zprofile` Python library.

fix

Install the Go SDK from golang.org/doc/install and ensure `go tool pprof` is in your system's PATH. Then run `go tool pprof -http=:8080 profile.pprof` in your terminal to view the interactive flame graph.

affects: All versions

gotchaAs a statistical (sampling) profiler, `zprofile` captures CPU and wall-clock usage by periodically taking samples. This approach minimizes overhead but might occasionally miss very short-lived function calls or specific line-by-line execution details that a deterministic profiler would catch. For very fine-grained analysis of short functions, consider deterministic profiling tools if overhead is acceptable.

fix

For general system profiling, `zprofile` is effective. If precise, per-line execution counts for extremely fast operations are needed, consider `cProfile` (built-in Python) or other deterministic profilers, understanding their potentially higher overhead. Ensure your profiled code runs long enough to generate meaningful samples (e.g., at least a few seconds).

affects: All versions

Upgrade

Version history

1.0.13latest on PyPI · released Aug 21, 2023

Audit

Dependencies

No dependency data recorded yet.

Agent activity

48 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/timpalpant/zprofile ↗

packagehttps://pypi.org/project/zprofile/ ↗