{"id":2712,"library":"pyroscope-io","title":"Pyroscope Python Integration","description":"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.","status":"active","version":"1.0.4","language":"en","source_language":"en","source_url":"https://github.com/pyroscope-io/pyroscope-python","tags":["profiling","observability","performance","continuous profiling","metrics"],"install":[{"cmd":"pip install pyroscope-io","lang":"bash","label":"Install `pyroscope-io`"}],"dependencies":[],"imports":[{"symbol":"pyroscope","correct":"import pyroscope"},{"note":"Commonly accessed directly as `pyroscope.configure()` after `import pyroscope`.","wrong":"from pyroscope import configure","symbol":"configure","correct":"pyroscope.configure(...)"},{"note":"Commonly accessed directly as `@pyroscope.profile()` after `import pyroscope` for decorator usage.","wrong":"from pyroscope import profile","symbol":"profile","correct":"@pyroscope.profile(...)"}],"quickstart":{"code":"import pyroscope\nimport time\nimport os\n\n# Configure Pyroscope to send profiling data\n# Ensure PYROSCOPE_SERVER_ADDRESS environment variable is set\n# or use a default, e.g., 'http://localhost:4040'\npyroscope.configure(\n    server_address=os.environ.get(\"PYROSCOPE_SERVER_ADDRESS\", \"http://localhost:4040\"),\n    application_name=\"my.python.app\",\n    # Optional: Set tags for filtering data in Pyroscope UI\n    # tags={\"env\": \"dev\", \"region\": \"us-east\"}\n)\n\n# Decorator to profile a specific function\n@pyroscope.profile(name=\"my_long_running_task\")\ndef my_long_running_task():\n    \"\"\"Simulates a task that takes some CPU time.\"\"\"\n    print(\"Running my_long_running_task...\")\n    _ = [i*i for i in range(1_000_000)] # CPU intensive operation\n    time.sleep(0.1)\n\n@pyroscope.profile(name=\"another_task\")\ndef another_task():\n    \"\"\"Another task that takes some time.\"\"\"\n    print(\"Running another_task...\")\n    time.sleep(0.2)\n\n\ndef main():\n    print(\"Starting profiling example. Run a Pyroscope server on \", pyroscope.configure().get('server_address'), \"to see data.\")\n    for i in range(5):\n        print(f\"Iteration {i+1}\")\n        my_long_running_task()\n        another_task()\n        time.sleep(0.5) # Simulate idle time\n    print(\"Profiling example finished. Data might take a moment to appear in Pyroscope UI.\")\n\nif __name__ == \"__main__\":\n    main()\n","lang":"python","description":"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."},"warnings":[{"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`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"1.x.x"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}