Install the Pyroscope Python SDK: pip install pyroscope-io
Initialize the profiler at application startup by calling pyroscope.configure() with server_address pointing to your Pyroscope or Grafana Pyroscope endpoint, application_name, and auth_token=YOUR_TOKEN if using Grafana Cloud
Add tags to the profiler configuration using the tags dict for static labels (environment, version) and use pyroscope.tag_wrapper() as a context manager to attach dynamic labels (like endpoint or job type) around specific code blocks
For background tasks and async applications call pyroscope.configure() once and rely on the SDK's thread-based sampling; for multi-process applications initialize the profiler in each worker process after fork
Deploy the application and navigate to the Pyroscope or Grafana Explore Profiles UI; select the application name and profile type (cpu, memory allocations) and inspect the flamegraph
Compare profiles across time windows or between app versions using the diff flamegraph view to identify regressions
Known gotchas
The Pyroscope Python SDK uses signal-based CPU profiling which does not work inside threads or async event loops; CPU profiling is sampled from the main thread — for thread-heavy applications profile each thread's CPU separately using explicit tagging
Pyroscope's default sampling interval is 10ms; reducing this increases profiling overhead while increasing it reduces resolution — do not set the interval below 10ms in production
The auth_token configured in the SDK is sent in plain HTTP headers; always ensure the server_address uses HTTPS in production to avoid leaking credentials
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp