docs(python): Update stream mode in instrumentation files (tracing part 2/3)#18532
Open
inventarSarah wants to merge 2 commits into
Open
docs(python): Update stream mode in instrumentation files (tracing part 2/3)#18532inventarSarah wants to merge 2 commits into
inventarSarah wants to merge 2 commits into
Conversation
inventarSarah
requested review from
alexander-alderman-webb,
cleptric,
ericapisani,
sentrivana and
sfanahata
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
6 tasks
inventarSarah
force-pushed
the
smi/span-first/python-tracing-2
branch
from
a081e8d to
0a53c54
Compare
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
sentrivana
approved these changes
Jun 29, 2026
sentrivana
left a comment
sentrivana
left a comment
Contributor
There was a problem hiding this comment.
Approving to not block, but please see comments
| 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`. |
Contributor
There was a problem hiding this comment.
Suggested change
| 3. Set `op` to `cache.put`. | |
| 3. Set `op` (transaction mode) or the `sentry.op` attribute (stream mode) to `cache.put`. |
| "network.transport": "tcp", | ||
| }) | ||
|
|
||
| # Set prompt arguments (optional, if send_default_pii=True) |
Contributor
There was a problem hiding this comment.
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) |
| # 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 |
Contributor
There was a problem hiding this comment.
Suggested change
| # Content is PII, only set if send_default_pii=True | |
| # Note that content might contain PII data |
| 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. |
Contributor
There was a problem hiding this comment.
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. |
|
|
||
| def make_request(method, url): | ||
| span = sentry_sdk.traces.start_span( | ||
| name="%s %s" % (method, url), |
Contributor
There was a problem hiding this comment.
This is a very old-style way of string formatting
Suggested change
| name="%s %s" % (method, url), | |
| name=f"{method} {url}", |
|
|
||
| content_length = response.headers.get("content-length") | ||
| if content_length is not None: | ||
| span.set_attribute("http.response_content_length", content_length) |
Contributor
There was a problem hiding this comment.
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.
| 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. |
Contributor
There was a problem hiding this comment.
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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
SLA
Thanks in advance for your help!
PRE-MERGE CHECKLIST
Make sure you've checked the following before merging your changes:
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