Update migration guide for async transport #4732

srothh · 2025-09-01T13:40:16Z

Update the migration guide for 3.0 to include information on the async transport and context manager

…gration guide

…anges

codecov · 2025-09-01T13:52:04Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.61%. Comparing base (f1850ce) to head (752db32).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@              Coverage Diff               @@
##           potel-base    #4732      +/-   ##
==============================================
- Coverage       84.61%   84.61%   -0.01%     
==============================================
  Files             158      158              
  Lines           16162    16162              
  Branches         2575     2575              
==============================================
- Hits            13676    13675       -1     
  Misses           1693     1693              
- Partials          793      794       +1

see 1 file with indirect coverage changes

seer-by-sentry · 2025-09-02T06:53:13Z

MIGRATION_GUIDE.md

+- Added a new experimental async transport using the [httpcore](https://pypi.org/project/httpcore/) library. Requires the [httpcore[asyncio]](https://www.encode.io/httpcore/async/) extension. The async transport makes Sentry network I/O non-blocking in async programs. The async transport can only be used when an event loop is running, and additionally requires the [asyncio](https://docs.sentry.io/platforms/python/integrations/asyncio/) integration. Can be enabled by passing ``transport_async=true`` in the experiments dict in ``sentry.init()``.
+- Added an asynchronous context manager for spans. This can be used to remove unnessecary nesting for span creation in async programs.
+- Added `flush_async()` as a top level API. This has to be used when flushing the async transport. `flush_async` is a coroutine and can be awaited if blocking behaviour is desired.


Potential bug: The migration guide documents a new flush_async() function and transport_async option, but they are not implemented, causing an AttributeError when called.

Description: The migration guide introduces documentation for new asynchronous transport functionality, including a top-level flush_async() function, an AsyncHttpTransport class, and a transport_async configuration option. However, none of these features are implemented in the codebase. Users following the guide and attempting to call sentry_sdk.flush_async() will encounter an AttributeError, causing their application to crash. This discrepancy between documentation and the actual API guarantees a runtime failure for users trying to adopt the documented async features.

Suggested fix: Remove the section from the migration guide that describes the flush_async() function, the transport_async configuration option, and the AsyncHttpTransport class, as these features are not implemented in the current codebase. Alternatively, implement the documented functionality.
_{severity: 0.82, confidence: 0.98}

_{Did we get this right? 👍 / 👎 to inform future reviews.}

Seer seems to have a point here unless I'm grepping incorrectly

I created the migration branch before adding this function to the API, I can merge potel base back in then flush_async should be here.

Should be here now

sentrivana

Thanks for adding! Left some formatting suggestions and a question regarding the seer comment

MIGRATION_GUIDE.md

sentrivana · 2025-09-02T07:20:28Z

MIGRATION_GUIDE.md

+- Added a new experimental async transport using the [httpcore](https://pypi.org/project/httpcore/) library. Requires the [httpcore[asyncio]](https://www.encode.io/httpcore/async/) extension. The async transport makes Sentry network I/O non-blocking in async programs. The async transport can only be used when an event loop is running, and additionally requires the [asyncio](https://docs.sentry.io/platforms/python/integrations/asyncio/) integration. Can be enabled by passing ``transport_async=true`` in the experiments dict in ``sentry.init()``.
+- Added an asynchronous context manager for spans. This can be used to remove unnessecary nesting for span creation in async programs.
+- Added `flush_async()` as a top level API. This has to be used when flushing the async transport. `flush_async` is a coroutine and can be awaited if blocking behaviour is desired.


Seer seems to have a point here unless I'm grepping incorrectly

alexander-alderman-webb · 2025-09-02T07:25:13Z

MIGRATION_GUIDE.md

@@ -8,7 +8,9 @@ Looking to upgrade from Sentry SDK 2.x to 3.x? Here's a comprehensive list of wh

 - Added `add_attachment()` as a top level API, so you can do now: `sentry_sdk.add_attachment(...)` (up until now it was only available on the `Scope`)
 - Added a new SDK option `exclude_span_origins`. Spans with an `origin` from `exclude_span_origins` won't be created. This can be used for example in dual OpenTelemetry/Sentry setups to filter out spans from specific Sentry instrumentations. Note that using `exclude_span_origins` might potentially lead to surprising results: if, for example, a root span is excluded based on `origin`, all of its children will become root spans, unless they were started with `only_as_child_span=True`.
-
+- Added a new experimental async transport using the [httpcore](https://pypi.org/project/httpcore/) library. Requires the [httpcore[asyncio]](https://www.encode.io/httpcore/async/) extension. The async transport makes Sentry network I/O non-blocking in async programs. The async transport can only be used when an event loop is running, and additionally requires the [asyncio](https://docs.sentry.io/platforms/python/integrations/asyncio/) integration. Can be enabled by passing ``transport_async=true`` in the experiments dict in ``sentry.init()``.


It might be worth having a code snippet?

Suggested change

- Added a new experimental async transport using the [httpcore](https://pypi.org/project/httpcore/) library. Requires the [httpcore[asyncio]](https://www.encode.io/httpcore/async/) extension. The async transport makes Sentry network I/O non-blocking in async programs. The async transport can only be used when an event loop is running, and additionally requires the [asyncio](https://docs.sentry.io/platforms/python/integrations/asyncio/) integration. Can be enabled by passing ``transport_async=true`` in the experiments dict in ``sentry.init()``.

- Added a new experimental async transport using the [httpcore](https://pypi.org/project/httpcore/) library. Requires the [httpcore[asyncio]](https://www.encode.io/httpcore/async/) extension. The async transport makes Sentry network I/O non-blocking in async programs. The async transport can only be used when an event loop is running. Try it out by initializing Sentry with:

```python

import sentry_sdk

from sentry_sdk.integrations.asyncio import AsyncioIntegration

sentry_sdk.init(

_experiments={

"transport_async": True,

},

integrations=[

sentry_sdk.AsyncIO(),

]

)

```.

added, thanks for the suggestion!

Co-authored-by: Ivana Kellyer <[email protected]>

…details Expanded the migration guide with details on the new experimental async transport feature and provided usage examples.

Corrected a typo in the migration guide regarding the asynchronous context manager for spans.

sentrivana

👍🏻

MIGRATION_GUIDE.md

Co-authored-by: Ivana Kellyer <[email protected]>

srothh added 2 commits August 14, 2025 16:08

ref(migration): Update migration guide with new async features

205e880

ref(migration_guid): Revise async transport feature description in mi…

7fb860a

…gration guide

srothh changed the base branch from master to potel-base September 1, 2025 13:40

srothh added 2 commits September 1, 2025 15:41

ref(migration_guide): Update migration guide with new features and ch…

6453417

…anges

ref(migration_guide): Update migration guide with new API features

4ed423c

srothh marked this pull request as ready for review September 2, 2025 06:48

srothh requested a review from a team as a code owner September 2, 2025 06:48

seer-by-sentry bot reviewed Sep 2, 2025

View reviewed changes

sentrivana reviewed Sep 2, 2025

View reviewed changes

alexander-alderman-webb reviewed Sep 2, 2025

View reviewed changes

srothh and others added 2 commits September 2, 2025 10:57

ref(migration_guide): update formatting from review

77c733e

Co-authored-by: Ivana Kellyer <[email protected]>

ref(migration_guide): Update MIGRATION_GUIDE.md with async transport …

0304706

…details Expanded the migration guide with details on the new experimental async transport feature and provided usage examples.

This comment was marked as outdated.

Sign in to view

Merge branch 'potel-base' into srothh/update-migration-guide

26873f1

This comment was marked as outdated.

Sign in to view

srothh and others added 3 commits September 2, 2025 11:03

ref(migration_guide): remove git comments from migration guide

429476e

ref(migration_guide): fix code example for async transport

e5a38ef

ref(migration_guide): fix typo in migration guide

752db32

Corrected a typo in the migration guide regarding the asynchronous context manager for spans.

sentrivana approved these changes Sep 2, 2025

View reviewed changes

MIGRATION_GUIDE.md Show resolved Hide resolved

ref(migration_guide): update MIGRATION_GUIDE.md

c8ecdbd

Co-authored-by: Ivana Kellyer <[email protected]>

srothh merged commit ebd77f2 into potel-base Sep 2, 2025
125 of 126 checks passed

srothh deleted the srothh/update-migration-guide branch September 2, 2025 14:44

BYK mentioned this pull request Sep 3, 2025

breaking: Remove Spotlight Django integration #4747

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Update migration guide for async transport #4732

Update migration guide for async transport #4732

srothh commented Sep 1, 2025

Uh oh!

codecov bot commented Sep 1, 2025 •

edited

Loading

Uh oh!

seer-by-sentry bot Sep 2, 2025

Uh oh!

sentrivana Sep 2, 2025

Uh oh!

srothh Sep 2, 2025

Uh oh!

srothh Sep 2, 2025

Uh oh!

sentrivana left a comment

Uh oh!

Uh oh!

sentrivana Sep 2, 2025

Uh oh!

alexander-alderman-webb Sep 2, 2025

Uh oh!

srothh Sep 2, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

sentrivana left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

-- Added a new experimental async transport using the [httpcore](https://pypi.org/project/httpcore/) library. Requires the [httpcore[asyncio]](https://www.encode.io/httpcore/async/) extension. The async transport makes Sentry network I/O non-blocking in async programs. The async transport can only be used when an event loop is running, and additionally requires the [asyncio](https://docs.sentry.io/platforms/python/integrations/asyncio/) integration. Can be enabled by passing ``transport_async=true`` in the experiments dict in ``sentry.init()``.
+- Added a new experimental async transport using the [httpcore](https://pypi.org/project/httpcore/) library. Requires the [httpcore[asyncio]](https://www.encode.io/httpcore/async/) extension. The async transport makes Sentry network I/O non-blocking in async programs. The async transport can only be used when an event loop is running. Try it out by initializing Sentry with:
+```python
+import sentry_sdk
+from sentry_sdk.integrations.asyncio import AsyncioIntegration
+sentry_sdk.init(
+    _experiments={
+        "transport_async": True,
+    },
+    integrations=[
+       	sentry_sdk.AsyncIO(),
+    ]
+)
+```.

Update migration guide for async transport #4732

Update migration guide for async transport #4732

Conversation

srothh commented Sep 1, 2025

Uh oh!

codecov bot commented Sep 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

seer-by-sentry bot Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

sentrivana Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

srothh Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

srothh Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

sentrivana left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sentrivana Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

alexander-alderman-webb Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

srothh Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

sentrivana left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Sep 1, 2025 •

edited

Loading