/sentry-python-sdk

Profiling — Sentry Python SDK

Minimum SDK: sentry-sdk 1.18.0+ (transaction-based); 2.24.1+ (continuous / session-based)

Configuration

Profiling requires traces_sample_rate > 0 (or traces_sampler) to be set.

API Comparison

Code Examples

Transaction-based profiling (simple / legacy)

import sentry_sdk

sentry_sdk.init(
    dsn="https://<key>@<org>.ingest.sentry.io/<project>",
    traces_sample_rate=1.0,
    profiles_sample_rate=1.0,   # relative to traces_sample_rate
    # e.g. profiles_sample_rate=0.5 → profiles 50% of sampled transactions
)

Profiles start when the transaction starts and stop when it ends or after 30 seconds, whichever is first.

Continuous profiling — auto-managed (profile_lifecycle="trace")

SDK automatically starts and stops the profiler around active spans.

import sentry_sdk

sentry_sdk.init(
    dsn="https://<key>@<org>.ingest.sentry.io/<project>",
    traces_sample_rate=1.0,
    profile_session_sample_rate=1.0,   # evaluated once at process start
    profile_lifecycle="trace",          # SDK manages start/stop automatically
)

Continuous profiling — manual control (profile_lifecycle="manual")

Full programmatic control over profiler lifetime.

import sentry_sdk

sentry_sdk.init(
    dsn="https://<key>@<org>.ingest.sentry.io/<project>",
    traces_sample_rate=1.0,
    profile_session_sample_rate=1.0,
    profile_lifecycle="manual",
)

# Application startup
sentry_sdk.profiler.start_profiler()

# ... application runs ...

# Application shutdown
sentry_sdk.profiler.stop_profiler()

Production-recommended setup (continuous)

import sentry_sdk
import signal

sentry_sdk.init(
    dsn="https://<key>@<org>.ingest.sentry.io/<project>",
    environment="production",
    release="my-app@2.0.0",
    traces_sample_rate=0.1,             # sample 10% of transactions
    profile_session_sample_rate=1.0,    # profile all sampled sessions
    profile_lifecycle="trace",
)

Best Practices

• Use continuous profiling (profile_session_sample_rate + profile_lifecycle) for long-running services and production workloads
• Use transaction-based (profiles_sample_rate) for simple setups or short-lived scripts
• profile_session_sample_rate is evaluated once at process start — changing it requires a restart
• "trace" and "manual" profile lifecycles are mutually exclusive; do not mix them
• Reduce traces_sample_rate in production (e.g., 0.1) — profiling overhead is low but not zero
• Python's GIL means the profiler captures the thread holding the GIL; async I/O wait time appears as near-zero CPU — this is expected

Troubleshooting