Registry / observability / pyroscope-io

pyroscope-io

JSON →
library1.2.1pypypi✓ verified 26d ago

The `pyroscope-io` library provides seamless integration for Python applications with the Pyroscope continuous profiling platform. It collects CPU and memory profiling data from your application and sends it to a Pyroscope server for visualization and analysis. Currently at version 1.0.4, it follows a feature-driven release cadence.

pip install pyroscope-io
INSTALL
IMPORT
SIG · PYROSCOPE-IO
P
pyroscope-io
observabilitypythonv1.2.1
Install
1.8s avg
Import
20ms
Disk
29MB
Pass rate
9/ 10
Env Coverage9 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.2.1 · 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
✓ —
✓ 1.7s
py 3.11
✓ —
✓ 1.8s
py 3.12
✓ —
✓ 1.6s
py 3.13
✓ —
✓ 1.7s
py 3.9
✕ build_error
✓ 2.4s
29MB installed
● package 29MB
Code
Verified usage

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

pyroscope
import pyroscope
configure
pyroscope.configure(...)
from pyroscope import configure
Commonly accessed directly as `pyroscope.configure()` after `import pyroscope`.
profile
@pyroscope.profile(...)
from pyroscope import profile
Commonly accessed directly as `@pyroscope.profile()` after `import pyroscope` for decorator usage.

This example demonstrates how to configure `pyroscope-io` and profile specific functions using the `@pyroscope.profile` decorator. Ensure a Pyroscope server is running and accessible at the configured `server_address`. The `application_name` is crucial for identifying your data in the Pyroscope UI.

import pyroscope import time import os # Configure Pyroscope to send profiling data # Ensure PYROSCOPE_SERVER_ADDRESS environment variable is set # or use a default, e.g., 'http://localhost:4040' pyroscope.configure( server_address=os.environ.get("PYROSCOPE_SERVER_ADDRESS", "http://localhost:4040"), application_name="my.python.app", # Optional: Set tags for filtering data in Pyroscope UI # tags={"env": "dev", "region": "us-east"} ) # Decorator to profile a specific function @pyroscope.profile(name="my_long_running_task") def my_long_running_task(): """Simulates a task that takes some CPU time.""" print("Running my_long_running_task...") _ = [i*i for i in range(1_000_000)] # CPU intensive operation time.sleep(0.1) @pyroscope.profile(name="another_task") def another_task(): """Another task that takes some time.""" print("Running another_task...") time.sleep(0.2) def main(): print("Starting profiling example. Run a Pyroscope server on ", pyroscope.configure().get('server_address'), "to see data.") for i in range(5): print(f"Iteration {i+1}") my_long_running_task() another_task() time.sleep(0.5) # Simulate idle time print("Profiling example finished. Data might take a moment to appear in Pyroscope UI.") if __name__ == "__main__": main()
pyroscope --version
Debug
Known issues
gotchaProfiling data will not be collected or correctly attributed if `server_address` or `application_name` are not properly configured. An incorrect `server_address` means data cannot reach the Pyroscope server, while a missing `application_name` (or one that defaults to a generic value) makes it difficult to distinguish your application's data.
fix
Always explicitly set `application_name` in `pyroscope.configure()`. Ensure `server_address` points to a running Pyroscope server (e.g., via environment variable `PYROSCOPE_SERVER_ADDRESS` or directly in `configure`).
affects: All versions
gotchaThe `pyroscope.configure()` function sets up continuous background profiling. Using `pyroscope.start()` and `pyroscope.stop()` for manual, explicit control can lead to unexpected behavior or incomplete data if not managed carefully alongside `configure()`. For most continuous profiling use cases, `configure()` is sufficient.
fix
For continuous profiling, rely primarily on `pyroscope.configure()` to initialize the profiler. Only use `pyroscope.start()` and `pyroscope.stop()` for specific, short-lived profiling sessions where you need fine-grained control over the profiling lifecycle.
affects: 1.x.x
gotchaData will not appear in the Pyroscope UI if a Pyroscope server is not running and accessible at the configured `server_address`. The client library will attempt to send data, but it will be dropped if there's no listener.
fix
Before running your Python application with Pyroscope integration, ensure that a Pyroscope server instance is running and reachable from your application's host and port. You can verify network connectivity using `ping` or `curl` to the `server_address`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pyroscope'
The `pyroscope-io` library is not installed in the current Python environment or the environment is not active, preventing the `import pyroscope` statement from finding the module.
fix
Install the library using the command: `pip install pyroscope-io`
RuntimeError: Pyroscope has not been configured.
The `pyroscope.start()` or `pyroscope.stop()` method was called before `pyroscope.configure()` was successfully executed to initialize the profiler's internal state.
fix
Ensure `pyroscope.configure(application_name='your_app', server_address='http://localhost:4040')` is called with the necessary parameters before attempting to start or stop profiling.
requests.exceptions.ConnectionError: ('Connection aborted.', ConnectionRefusedError(111, 'Connection refused'))
The Python application failed to connect to the Pyroscope server at the `server_address` specified in `pyroscope.configure()`, often because the server is not running, is on the wrong address/port, or a firewall is blocking the connection.
fix
Verify that the Pyroscope server is running, that the `server_address` (e.g., `http://localhost:4040`) in `pyroscope.configure()` is correct and accessible, and check for any network or firewall restrictions.
Upgrade
Version history
1.2.1latest on PyPI · released Jul 27, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
21 hits · last 30 days
node
18
OpenAI (training)
2
Resources
pyroscope-io — pip install pyroscope-io · libregistry