docs(python): Update stream mode in instrumentation files (tracing part 2/3) by inventarSarah · Pull Request #18532 · getsentry/sentry-docs

inventarSarah · 2026-06-24T10:37:49Z

DESCRIBE YOUR PR

This PR updates pages under Tracing with information about the new stream mode and the new Span APIs.

Part 2 out of 3
(result of splitting up PR #18511 into smaller parts)

Important

Broken links: I added links to the New Spans guide on these pages, but since this guide does not exist in this branch, we get a linting error.
Should only be merged after #18456

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.

Urgent deadline (GA date, etc.):
Other deadline:
None: Not urgent, can wait up to 1 week+

SLA

Teamwork makes the dream work, so please add a reviewer to your PRs.
Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it.
Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

Checked Vercel preview for correctness, including links
PR was reviewed and approved by any necessary SMEs (subject matter experts)
PR was reviewed and approved by a member of the Sentry docs team

LEGAL BOILERPLATE

Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms.

EXTRA RESOURCES

Sentry Docs contributor guide

vercel · 2026-06-24T10:37:57Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sentry-docs	Ready	Preview, Comment	Jul 7, 2026 7:03am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
develop-docs	Ignored	Preview	Jul 7, 2026 7:03am

sentrivana

Approving to not block, but please see comments

sentrivana · 2026-06-29T08:52:57Z

 1. Set the cache value with whatever cache library you happen to be using.
-2. Wrap the part of your application that uses the cached value with  `with sentry_sdk.start_span(...)`
+2. Wrap the part of your application that uses the cached value with `with sentry_sdk.start_span(...)` (transaction mode) or `with sentry_sdk.traces.start_span(...)` (stream mode).
 3. Set `op` to `cache.put`.


Suggested change

3. Set `op` to `cache.put`.

3. Set `op` (transaction mode) or the `sentry.op` attribute (stream mode) to `cache.put`.

sentrivana · 2026-06-29T08:56:50Z

+        "network.transport": "tcp",
+    })
+
+    # Set prompt arguments (optional, if send_default_pii=True)


send_default_pii is a flag the sdk uses to gate attributes. As this is a custom instrumentation snippet, it's up to the user to decide what they want to include:

Suggested change

# Set prompt arguments (optional, if send_default_pii=True)

# Set prompt arguments (keep in mind this might contain PII data, so only set if that's ok)

sentrivana · 2026-06-29T08:57:13Z

+    # For single-message prompts, set role and content
+    if len(messages) == 1:
+        span.set_attribute("mcp.prompt.result.message_role", messages[0].get("role"))
+        # Content is PII, only set if send_default_pii=True


Suggested change

# Content is PII, only set if send_default_pii=True

# Note that content might contain PII data

sentrivana · 2026-06-29T08:59:40Z

-Use `sentry_sdk.continue_trace()` to connect your consumer spans to their associated producer spans, and `transaction.set_status()` to mark the trace of your message as success or failed.
+In stream mode, there's no separate transaction to depend on. If your `queue.process` span has no parent, it's automatically promoted to a service span. If you'd rather group it under an explicit service span, start one with `sentry_sdk.traces.start_span(parent_span=None)` first.

+Use `continue_trace()` to connect your consumer spans to their associated producer spans. To mark the trace of your message as success or failed, use `transaction.set_status()` in transaction mode, or set `.status = "ok"/"error"` directly on the service span in stream mode.


Suggested change

Use `continue_trace()` to connect your consumer spans to their associated producer spans. To mark the trace of your message as success or failed, use `transaction.set_status()` in transaction mode, or set `.status = "ok"/"error"` directly on the service span in stream mode.

Use `continue_trace()` to connect your consumer spans to their associated producer spans. To mark the trace of your message as success or failed, use `transaction.set_status()` in transaction mode, or set `span.status = "ok"/"error"` directly on the service span in stream mode.

sentrivana · 2026-06-29T09:00:47Z

+
+def make_request(method, url):
+    span = sentry_sdk.traces.start_span(
+        name="%s %s" % (method, url),


This is a very old-style way of string formatting

Suggested change

name="%s %s" % (method, url),

name=f"{method} {url}",

sentrivana · 2026-06-29T09:03:29Z

+
+    content_length = response.headers.get("content-length")
+    if content_length is not None:
+        span.set_attribute("http.response_content_length", content_length)


We can set this as the Sentry conventions approved attribute:

Suggested change

span.set_attribute("http.response_content_length", content_length)

span.set_attribute("http.response.header.content-length", content_length)

It doesn't matter too much in custom instrumentation, but folks might get nicer dashboards/etc. in the UI.

sentrivana · 2026-06-29T09:04:09Z

-Spans are only created within an existing transaction. If you're not using any of the supported frameworks, you'll need to <PlatformLink to="/tracing/instrumentation/custom-instrumentation/">create transactions manually</PlatformLink>.
+In transaction mode, spans are only created within an existing transaction. If you're not using any of the supported frameworks, you'll need to <PlatformLink to="/tracing/instrumentation/custom-instrumentation/">create transactions manually</PlatformLink>.
+
+Stream mode removes this limitation. Since there are no transactions, any span started without a parent is automatically promoted to a service span (the equivalent of a transaction). You can also force any span to become a service span when starting it by removing its parent. See <PlatformLink to="/tracing/instrumentation/custom-instrumentation/">Custom Instrumentation</PlatformLink> to learn more.


Suggested change

Stream mode removes this limitation. Since there are no transactions, any span started without a parent is automatically promoted to a service span (the equivalent of a transaction). You can also force any span to become a service span when starting it by removing its parent. See <PlatformLink to="/tracing/instrumentation/custom-instrumentation/">Custom Instrumentation</PlatformLink> to learn more.

Stream mode removes this limitation. Since there are no transactions, any span started without a parent is automatically promoted to a service span (the equivalent of a transaction). You can also force any span to become a service span when starting it by setting its parent to `None`. See <PlatformLink to="/tracing/instrumentation/custom-instrumentation/">Custom Instrumentation</PlatformLink> to learn more.

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 0f6abb3. Configure here.}

…on-tracing-2

sentry · 2026-07-07T06:55:05Z

+# Continue the trace started in the producer
+# If you are using a web framework, the framework integration
+# will create this for you and you can omit this.
+sentry_sdk.traces.continue_trace(message["headers"])


Bug: The documentation uses a non-existent API sentry_sdk.traces.continue_trace() instead of the correct sentry_sdk.continue_trace().
_{Severity: HIGH}

Suggested Fix

Replace the incorrect call sentry_sdk.traces.continue_trace(message["headers"]) with the correct one: sentry_sdk.continue_trace(message["headers"]). Consider also capturing the return value to be used in a subsequent start_transaction call, as shown in other examples.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not valid. Location: docs/platforms/python/tracing/instrumentation/custom-instrumentation/queues-module.mdx#L218 Potential issue: The stream mode consumer example in the documentation uses an incorrect API call, `sentry_sdk.traces.continue_trace()`. The `continue_trace` function is a top-level function in the `sentry_sdk` module, not part of the `traces` submodule. As a result, any user who copies and runs this code example will encounter an `AttributeError: module 'sentry_sdk.traces' has no attribute 'continue_trace'` at runtime, preventing distributed tracing from working as intended.

inventarSarah requested review from alexander-alderman-webb, cleptric, ericapisani, sentrivana and sfanahata June 24, 2026 10:37

inventarSarah mentioned this pull request Jun 24, 2026

docs(python): Update Tracing pages for new stream mode #18511

Closed

6 tasks

vercel Bot deployed to Preview – sentry-docs June 24, 2026 10:47 View deployment

update stream mode in instrumentation files

0a53c54

inventarSarah force-pushed the smi/span-first/python-tracing-2 branch from a081e8d to 0a53c54 Compare June 24, 2026 11:50

inventarSarah marked this pull request as ready for review June 24, 2026 11:50

sentry Bot reviewed Jun 24, 2026

View reviewed changes

Comment thread docs/platforms/python/tracing/instrumentation/custom-instrumentation/requests-module.mdx Outdated

vercel Bot deployed to Preview – sentry-docs June 24, 2026 12:01 View deployment

Sentry bot PR feedback

91b5fad

vercel Bot deployed to Preview – sentry-docs June 24, 2026 12:29 View deployment

sentrivana approved these changes Jun 29, 2026

View reviewed changes

rename 'New Spans' references to 'Streamed Spans'

0f6abb3

cursor Bot reviewed Jul 2, 2026

View reviewed changes

Comment thread docs/platforms/python/tracing/instrumentation/custom-instrumentation/queues-module.mdx Outdated

Comment thread docs/platforms/python/tracing/instrumentation/custom-instrumentation/queues-module.mdx Outdated

sentry Bot reviewed Jul 2, 2026

View reviewed changes

Comment thread docs/platforms/python/tracing/instrumentation/custom-instrumentation/queues-module.mdx Outdated

apply review suggestions from sentrivana

7a5f150

vercel Bot deployed to Preview – sentry-docs July 2, 2026 20:28 View deployment

inventarSarah added 2 commits July 6, 2026 12:54

Merge remote-tracking branch 'origin/master' into smi/span-first/pyth…

f186f4f

…on-tracing-2

update attribute value example

f9873fb

sentry Bot reviewed Jul 6, 2026

View reviewed changes

Comment thread docs/platforms/python/tracing/instrumentation/custom-instrumentation/queues-module.mdx Outdated

vercel Bot deployed to Preview – sentry-docs July 6, 2026 11:10 View deployment

inventarSarah added 2 commits July 7, 2026 08:48

Merge remote-tracking branch 'origin/master' into smi/span-first/pyth…

a82a009

…on-tracing-2

update latency value in code snippets

127f231

sentry Bot reviewed Jul 7, 2026

View reviewed changes

vercel Bot deployed to Preview – sentry-docs July 7, 2026 07:03 View deployment

	3. Set `op` to `cache.put`.
	3. Set `op` (transaction mode) or the `sentry.op` attribute (stream mode) to `cache.put`.

	# Set prompt arguments (optional, if send_default_pii=True)
	# Set prompt arguments (keep in mind this might contain PII data, so only set if that's ok)

	# Content is PII, only set if send_default_pii=True
	# Note that content might contain PII data

	Use `continue_trace()` to connect your consumer spans to their associated producer spans. To mark the trace of your message as success or failed, use `transaction.set_status()` in transaction mode, or set `.status = "ok"/"error"` directly on the service span in stream mode.
	Use `continue_trace()` to connect your consumer spans to their associated producer spans. To mark the trace of your message as success or failed, use `transaction.set_status()` in transaction mode, or set `span.status = "ok"/"error"` directly on the service span in stream mode.

	span.set_attribute("http.response_content_length", content_length)
	span.set_attribute("http.response.header.content-length", content_length)

Uh oh!

Uh oh!

Conversation

inventarSarah commented Jun 24, 2026

DESCRIBE YOUR PR

IS YOUR CHANGE URGENT?

SLA

PRE-MERGE CHECKLIST

LEGAL BOILERPLATE

EXTRA RESOURCES

Uh oh!

vercel Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

sentrivana left a comment

Choose a reason for hiding this comment

Uh oh!

sentrivana Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

sentrivana Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

sentrivana Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

sentrivana Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

sentrivana Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

sentrivana Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

sentrivana Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sentry Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vercel Bot commented Jun 24, 2026 •

edited

Loading