Skip to content

feat(python): Add docs on enable_asyncio_integration() #15988

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sentrivana merged 4 commits into from
Jan 20, 2026
Merged

feat(python): Add docs on enable_asyncio_integration() #15988

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3131138
feat(python): Add docs on enable_asyncio_integration()
sentrivana Jan 13, 2026
16b4b84
move around
sentrivana Jan 13, 2026
092518a
wording
sentrivana Jan 13, 2026
b3758e7
Apply suggestions from code review
sentrivana Jan 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 48 additions & 2 deletions docs/platforms/python/integrations/asyncio/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,10 @@ uv add "sentry-sdk"

## Configure

`AsyncioIntegration` works by instrumenting the current event loop, which is why it needs to be enabled when there's an event loop running.

### Enable `Asynciointegration` At `Init` Time

Add `AsyncioIntegration()` to your list of `integrations`, enable tracing and be sure to call `sentry_sdk.init()` **at the beginning of the first `async` function you call**, as shown in the example below.

<OnboardingOptionButtons
Expand Down Expand Up @@ -60,6 +64,43 @@ async def main():
asyncio.run(main())
```

### Enable `AsyncioIntegration` After `init`

Alternatively, if you're not in control of the event loop, you have multiple event loops, or you simply need a way to enable the integration on demand without setting up the whole SDK each time, you can use the `sentry_sdk.integrations.asyncio.enable_asyncio_integration` helper function.

```python {filename:main.py}
import sentry_sdk
from sentry_sdk.integrations.asyncio import enable_asyncio_integration

# Initializing the SDK as early as possible, when there is no event loop yet
sentry_sdk.init(
dsn="___PUBLIC_DSN___",
# Add data like request headers and IP for users, if applicable;
# see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info
send_default_pii=True,
# ___PRODUCT_OPTION_START___ performance
# Set traces_sample_rate to 1.0 to capture 100%
# of transactions for tracing.
traces_sample_rate=1.0,
# ___PRODUCT_OPTION_END___ performance
# ___PRODUCT_OPTION_START___ profiling
# To collect profiles for all profile sessions,
# set `profile_session_sample_rate` to 1.0.
profile_session_sample_rate=1.0,
# Profiles will be automatically collected while
# there is an active span.
profile_lifecycle="trace",
# ___PRODUCT_OPTION_END___ profiling
# No AsyncioIntegration in explicitly provided `integrations`
)


async def main():
enable_asyncio_integration() # instruments the current event loop
# Your code...
```


## Verify

Trigger an error in your code and see it show up in [sentry.io](https://sentry.io).
Expand All @@ -68,7 +109,6 @@ Trigger an error in your code and see it show up in [sentry.io](https://sentry.i
import asyncio

import sentry_sdk
from sentry_sdk.integrations.asyncio import AsyncioIntegration

async def my_task():
1 / 0 # raises an error!
Expand All @@ -88,12 +128,18 @@ asyncio.run(main())

## Troubleshooting

<Expandable title="Asyncio integration not working">
<Expandable title="The asyncio integration isn't working.">

The SDK needs the event loop to be running when instrumenting asyncio. Make sure to call `sentry_sdk.init()` inside of an `async` function.

</Expandable>

<Expandable title="There is no event loop when I need to initialize the SDK. How do I initialize the asyncio integration?">

You can initialize the SDK without `AsyncioIntegration` and then run `sentry_sdk.integrations.asyncio.enable_asyncio_integration()` once there is an event loop running. See [this section](#enable-asynciointegration-after-init) for an example.

</Expandable>

## Supported Versions

- Python: 3.7+