Pyroscope Python Integration

Warnings

• gotcha Profiling 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`).
• gotcha The `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.
• gotcha Data 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`.

Install

• pip install pyroscope-io Install `pyroscope-io`

Imports

• pyroscope

  import pyroscope

• configure

  pyroscope.configure(...)

  Commonly accessed directly as `pyroscope.configure()` after `import pyroscope`.
• profile

  @pyroscope.profile(...)

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

Quickstart

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()