Python tracing docs refresh #13125
Python tracing docs refresh #13125
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
2 Skipped Deployments
|
docs/platforms/python/tracing/distributed-tracing/custom-instrumentation/index.mdx
Outdated
Show resolved
Hide resolved
|
|
||
| with sentry_sdk.start_span(op="task", name="Create User"): | ||
| # Your code here | ||
| # The span will automatically end when exiting this block |
There was a problem hiding this comment.
I'm not familiar enough with Python to know, but is there a way to illustrate what closing this code block would look like?
There was a problem hiding this comment.
It looks like the with statement is used to automatically close the block, hence the comment, but I extended the block to demonstrate what it would look like within a larger set of code. LMK if that helps with what you were thinking!
|
|
||
| ## Span Starting Options | ||
|
|
||
| The following options can be used when creating spans: |
docs/platforms/python/tracing/span-metrics/performance-metrics.mdx
Outdated
Show resolved
Hide resolved
Bundle ReportChanges will increase total bundle size by 1.05kB (0.01%) ⬆️. This is within the configured threshold ✅ Detailed changes
Affected Assets, Files, and Routes:view changes for bundle: sentry-docs-server-cjsAssets Changed:
view changes for bundle: sentry-docs-client-array-pushAssets Changed:
|
sfanahata
changed the title
Co-authored-by: Alex Krawiec <[email protected]>
Co-authored-by: Alex Krawiec <[email protected]>
There was a problem hiding this comment.
Did another quick pass review, looks better now than it was before but I still found some items to improve.
As I mentioned, I am at a conference this week, so please work with @antonpirker for further reviews (@sentrivana is out today, you can also work with her once she is back hopefully later this week)
| ## Inheritance in Distributed Tracing | ||
|
|
||
| In distributed systems, trace information is propagated between services. You can implement inheritance logic like this: | ||
|
|
||
| ```python | ||
| def traces_sampler(sampling_context): | ||
| # Examine provided context data | ||
| if "transaction_context" in sampling_context: | ||
| name = sampling_context["transaction_context"].get("name", "") | ||
|
|
||
| # Apply specific rules first | ||
| if "critical-path" in name: | ||
| return 1.0 # Always sample | ||
|
|
||
| # Inherit parent sampling decision if available | ||
| if sampling_context.get("parent_sampled") is not None: | ||
| return sampling_context["parent_sampled"] | ||
|
|
||
| # Otherwise use a default rate | ||
| return 0.1 | ||
| ``` | ||
|
|
||
| This approach ensures consistent sampling decisions across your entire distributed trace. All transactions in a given trace will share the same sampling decision, preventing broken or incomplete traces. |
There was a problem hiding this comment.
Idk, I do still think having this snippet adds too much complexity to the page
what do you all think @antonpirker @sentrivana?
| Alternatively, you can create spans manually and control their lifecycle yourself, which gives you more flexibility but also more responsibility: | ||
|
|
||
| ```python | ||
| import sentry_sdk | ||
|
|
||
| span = sentry_sdk.start_span(op="task", name="Create User") | ||
| try: | ||
| # Your code here | ||
| finally: | ||
| # Remember to always end your spans | ||
| # If you don't call span.finish(), the span will remain open indefinitely, | ||
| # causing memory leaks and incorrect timing data | ||
| span.finish() | ||
| ``` |
There was a problem hiding this comment.
I think we should avoid mentioning this configuration method. Correct me if I am wrong @antonpirker, but I don't think we generally recommend using this manual method. Folks should use the with context manager.
If someone really needs to manage the spans manually, they can call .__enter__() and .__exit__() on the span (.__exit__() internally calls .finish()). Since this is actually how the with block works in Python, there is no need for us to describe how to do this; because we support with, we already automatically support using __enter__ and __exit__.
| Alternatively, you can create spans manually and control their lifecycle yourself, which gives you more flexibility but also more responsibility: | |
| ```python | |
| import sentry_sdk | |
| span = sentry_sdk.start_span(op="task", name="Create User") | |
| try: | |
| # Your code here | |
| finally: | |
| # Remember to always end your spans | |
| # If you don't call span.finish(), the span will remain open indefinitely, | |
| # causing memory leaks and incorrect timing data | |
| span.finish() | |
| ``` |
There was a problem hiding this comment.
Is there any common use case in which this would unblock a developer in setting up tracing?
| ## Creating Spans Manually | ||
|
|
||
| In some cases, you might need more control over when a span starts and ends. For this, you can create spans manually: | ||
|
|
||
| ```python | ||
| import sentry_sdk | ||
|
|
||
| def process_file(file_path): | ||
| # Create a span | ||
| span = sentry_sdk.start_span(op="file", name="Process File") | ||
|
|
||
| try: | ||
| # Your processing logic | ||
| with open(file_path, 'r') as f: | ||
| content = f.read() | ||
|
|
||
| # Set additional attributes | ||
| span.set_attribute("file_size", len(content)) | ||
|
|
||
| # Process the content | ||
| result = process_content(content) | ||
|
|
||
| return result | ||
| except Exception as e: | ||
| # Mark the span as failed | ||
| span.set_status("error") | ||
| # You can also add error details as attributes | ||
| span.set_attribute("error_type", type(e).__name__) | ||
| span.set_attribute("error_message", str(e)) | ||
| raise | ||
| finally: | ||
| # Always end the span | ||
| span.finish() | ||
| ``` |
There was a problem hiding this comment.
Following from my previous suggestion, I would delete this section on manual span management.
| ## Creating Spans Manually | |
| In some cases, you might need more control over when a span starts and ends. For this, you can create spans manually: | |
| ```python | |
| import sentry_sdk | |
| def process_file(file_path): | |
| # Create a span | |
| span = sentry_sdk.start_span(op="file", name="Process File") | |
| try: | |
| # Your processing logic | |
| with open(file_path, 'r') as f: | |
| content = f.read() | |
| # Set additional attributes | |
| span.set_attribute("file_size", len(content)) | |
| # Process the content | |
| result = process_content(content) | |
| return result | |
| except Exception as e: | |
| # Mark the span as failed | |
| span.set_status("error") | |
| # You can also add error details as attributes | |
| span.set_attribute("error_type", type(e).__name__) | |
| span.set_attribute("error_message", str(e)) | |
| raise | |
| finally: | |
| # Always end the span | |
| span.finish() | |
| ``` |
The example is also not very good, since (as far as I can tell), it would be possible and in fact easier to just use the with sentry_sdk.start_span syntax here, like so:
with sentry_sdk.start_span(...) as span: # note the "as span"
try:
...
except Exception as e:
span.set_status("error")
span.set_attribute(...)
...
# no need for finallyThere was a problem hiding this comment.
@codyde - did you have any particular users in mind when thinking about this use case?
| @@ -1,7 +1,297 @@ | |||
| --- | |||
There was a problem hiding this comment.
Thanks, this looks quite a bit better!
sfanahata
changed the title
Co-authored-by: Cody De Arkland <[email protected]>
Co-authored-by: Daniel Szoke <[email protected]>
Co-authored-by: Daniel Szoke <[email protected]>
adding parent inheritance info
updating to add parent inheritance to all examples.
Nix distributed tracing
Co-authored-by: Daniel Szoke <[email protected]>
Co-authored-by: Daniel Szoke <[email protected]>
DESCRIBE YOUR PR
Closes issue: https://linear.app/getsentry/project/tracing-improvements-python-120f4a3d71f2/overview
improve the structure of the tracing docs to match the structure we built for the JavaScript ones.
Add span metrics section
Example instrumentation
Sending performance metrics
Reformat Python tracing section to mirror JS structure
trace propagation -> distributed tracing, review section docs
Add configure sampling doc
Review instrumentation section
Add troubleshooting doc
Delete performance-metrics.mdx file under instrumentation (was redundant to the span-netsed doc I created)
PRE-MERGE CHECKLIST
Make sure you've checked the following before merging your changes: