docs(guides): Add practical 'what to do next' guides for key Sentry features#16410
docs(guides): Add practical 'what to do next' guides for key Sentry features#16410jaffrepaul wants to merge 15 commits intomasterfrom
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
docs/guides/custom-spans.mdx
Outdated
There was a problem hiding this comment.
I know this was being discussed on slack, but keeping all the examples in JS might make this a little alienating to some users. Would it make sense to maybe add tabs here for Python and PHP as well?
There was a problem hiding this comment.
Yea, this could be a follow up PR to keep things clean.
docs/guides/issues-errors.mdx
Outdated
There was a problem hiding this comment.
Do you think this would be a good spot for an arcade illustrating this?
There was a problem hiding this comment.
I think we need to wait if we're showing performance stuff. We're about to release a new UX on all these dashboards.
Meta comment on that too - this surface is super hard to find in product right now, and the trace view doc is quite dated. I purposefully have not updated it because it's rolled into the insights > dashboards updates I'm doing. I'm wondering if we can direct link to the product page for now instead?
There was a problem hiding this comment.
Re-reading, I think it's possible you mean the waterfall view? If so, let's not link to that page. Let's just link to the traces page, perhaps this section: /concepts/key-terms/tracing/#traces-to-trace-view.
I'm realizing it all sucks. I'll see if we can give the traces docs a face lift soon.
docs/guides/issues-errors.mdx
Outdated
There was a problem hiding this comment.
Another good opportunity for an arcade or screenshot (doesn't need to be added in v1, but wanted to mark it for posterity.)
There was a problem hiding this comment.
Love this and same problem as above - this UX is changing. We should wait.
docs/guides/issues-errors.mdx
Outdated
There was a problem hiding this comment.
I'm not seeing the 'addBreadCrumb' call here, is the breadcrumb being added by the contexts object?
There was a problem hiding this comment.
Yeah it's a little confusing here. Going to de-emphasize breadcrumbs.
docs/guides/issues-errors.mdx
Outdated
There was a problem hiding this comment.
I thought we generally do not want to reference breadcrumbs? We should mention logs and replays instead, yeah?
docs/guides/issues-errors.mdx
Outdated
There was a problem hiding this comment.
| **In Issues:** Search for `is:unresolved` (applied by default) and use the sort dropdown (defaults to "Last Seen") to sort by **Events** | |
| **[In Issues](https://sentry.io/orgredirect/organizations/:orgslug/issues/):** Search for `is:unresolved` (applied by default) and use the sort dropdown (defaults to "Last Seen") to sort by **Events** |
There was a problem hiding this comment.
I realized these are all issue filters, so bumped the link up to the top. It still might be useful to add a link in each section where we say In Issues, though. What do you think?
docs/guides/issues-errors.mdx
Outdated
There was a problem hiding this comment.
| Start with these five views to catch critical issues. | |
| Start by creating these five [Issue views](https://sentry.io/orgredirect/organizations/:orgslug/issues/) to catch the most critical problems. | |
| **Save these views**: Turn these five searches into saved Issues views by clicking **Save As** after setting each filter. |
I'm thinking if we feel like these are really valuable, we should suggest people save them to use them over and over again.
| **In Issues:** Filter by `is:unresolved` and sort by **Age** to find issues that first appeared recently (not just issues that happened recently). Filter by release: `release:v1.2.3` | ||
|
|
||
| **What to look for:** | ||
| - Issues that didn't exist in the previous release |
There was a problem hiding this comment.
Is there an easy way to recommend doing that comp? Or is it more common for folks to know whether or not it already existed?
There was a problem hiding this comment.
Good call out. And TIL about firstRelease which shows issues that first appeared in that release. Will make this edit so this section is legit.
docs/guides/issues-errors.mdx
Outdated
There was a problem hiding this comment.
I'd move this up to just under the explainer of this section so folks know they need to do this first.
docs/guides/issues-errors.mdx
Outdated
There was a problem hiding this comment.
Yes to all this. Just know that this UX is changing, with Monitors and Alerts in LA.
docs/guides/issues-errors.mdx
Outdated
There was a problem hiding this comment.
I think we want to de-emphasize breadcrumbs, and emphasize replays and logs.
There was a problem hiding this comment.
updated in 6a454d6fb
|
|
||
| Your Sentry SDK is sending errors to [Sentry Issues](/product/issues/) out of the box. Now what? This guide covers the high-value error patterns that help you catch problems before they impact users and fix issues faster. | ||
|
|
||
| ## The Pattern |
There was a problem hiding this comment.
I'm not clear on exactly what you're trying to tell me in this section - that every issue will have a pattern that can be tracked down? Or that every issue's anatomy has a pattern?
There was a problem hiding this comment.
More the latter. Most of the other pages have this at the top to set the stage with the anatomy of the feature.
There was a problem hiding this comment.
Hm, maybe we can better outline that, or just say that as the subheader? I didn't get it just from the header itself.
jaffrepaul
force-pushed
the
docs/early-days-5-reasons-guides
branch
from
a376fdc to
062fe31
Compare
| using Sentry; | ||
| SentrySdk.Logger.<Level>(message); | ||
| ``` | ||
|
|
There was a problem hiding this comment.
| Logs in Sentry are automatically trace-connected. Each log shows a trace ID that links to the full [trace view](/concepts/key-terms/tracing/#traces-to-trace-view). |
Same suggestion as on errors - until the trace view page gets cleaned up, this is more straightforward.
There was a problem hiding this comment.
Also, does this call-out need more context as to why we're talking about traces here, or is it self-evident for developers, like "oooOOOooo traces, yes! So valuable!"?
|
|
||
| ### 1. Authentication Events | ||
|
|
||
| Login flows are invisible until something breaks. Log successes and failures to spot patterns like brute force attempts, OAuth misconfigurations, or MFA issues. |
There was a problem hiding this comment.
Should we be more suggestive about where to place these snippets? Something like "add Sentry.logger.info when a user attempts to sign in and after the sign-in call completes"?
| Sentry.logger().warn("Login failed email=%s reason=%s", maskedEmail, "invalid_password") | ||
| ``` | ||
|
|
||
| **Search in Sentry:** `userId:123 "logged in"` or `severity:warn authMethod:*` |
There was a problem hiding this comment.
Where should they search? sentry.io/explore/logs/?
|
|
||
| Logs in Sentry are automatically trace-connected. Each log shows a trace ID that links to the full [trace view](/concepts/key-terms/tracing/trace-view/). | ||
|
|
||
| ## Where to Add Logs |
There was a problem hiding this comment.
Meta comment about this section - can you be more explicit about where in the code to add these snippets as examples? And can you also be specific about where in Sentry to search? Is it sentry.io/explore/logs/?
|
|
||
| ### 3. External APIs and Async Operations | ||
|
|
||
| Traces capture what your code does. Logs capture context about external triggers and async boundaries. Things like webhooks, scheduled tasks, and third-party API responses that traces can't automatically instrument. |
There was a problem hiding this comment.
| Traces capture what your code does. Logs capture context about external triggers and async boundaries. Things like webhooks, scheduled tasks, and third-party API responses that traces can't automatically instrument. | |
| Traces capture what your code does. Logs capture context about external triggers and async boundaries. These are things like webhooks, scheduled tasks, and third-party API responses that traces can't automatically instrument. |
|
|
||
| ### Production Logging | ||
|
|
||
| Local debugging often means many small logs tracing execution flow. In production, this creates noise that's hard to query. |
There was a problem hiding this comment.
I can't tell if this is a recommendation for formatting only for production, or a general guidance of how to format log capture.
| | **Gauge** | `Sentry.metrics.gauge()` | Current state (queue depth, connections) | | ||
| | **Distribution** | `Sentry.metrics.distribution()` | Values that vary (latency, sizes, amounts) | | ||
|
|
||
| Every metric is trace-connected. When a metric spikes, click into samples to see the exact trace that produced it. |
There was a problem hiding this comment.
Add a link to docs about traces?
|
|
||
| **Explore in Sentry:** | ||
|
|
||
| 1. Go to **Explore > Metrics** |
There was a problem hiding this comment.
| 1. Go to **Explore > Metrics** | |
| 1. Go to [**Explore > Metrics**](https://sentry.io/orgredirect/organizations/:orgslug/explore/metrics/) |
| Sentry.metrics().count("checkout.failed", 1.0) | ||
| ``` | ||
|
|
||
| ## Where to Track Metrics |
There was a problem hiding this comment.
Metric alerts/issues are coming very soon, so adding in alerts/monitors would be good to add when that releases!
|
|
||
| ## Where to Track Metrics | ||
|
|
||
| Start with these five metrics and you'll spot issues before they become problems. |
There was a problem hiding this comment.
I'd suggest linking to the in-product page for each these "explore in Sentry" prompts: https://sentry.io/orgredirect/organizations/:orgslug/explore/metrics/
| Learn about [creating alerts](/product/new-monitors-and-alerts/alerts/) and best practices for [reducing noise and routing notifications](/product/new-monitors-and-alerts/alerts/best-practices/). | ||
| */} | ||
|
|
||
| ## Alerts and Dashboard Widgets |
There was a problem hiding this comment.
I'm feeling torn about showing this. Maybe we update when it releases?
| - Long animation frames (main thread blocking) | ||
| - Resource loading (JS, CSS, images) | ||
|
|
||
| ## Where to Look |
There was a problem hiding this comment.
Suggest updating the "query in..." parts of each query suggestion to hyperlink to https://sentry.io/orgredirect/organizations/:orgslug/explore/traces/
|
|
||
| ## Where to Look | ||
|
|
||
| Start with these five queries and you'll catch most performance issues before users complain. |
There was a problem hiding this comment.
This page is so text heavy, my eyes are glazing over a little bit. What about adding an example of what the chart looks like once it's formatted for each one, or at least for one as a hero image at the top here?
|
|
||
| Auto-instrumentation captures HTTP, database, and framework operations. But it can't see business logic, third-party APIs without auto-instrumentation, or background jobs. This guide shows you where to add custom spans to fill in those gaps. | ||
|
|
||
| ## The Pattern |
There was a problem hiding this comment.
I don't know what this header is trying to tell me in this context
| transaction.finish() | ||
| ``` | ||
|
|
||
| Numeric attributes become metrics you can aggregate with `sum()`, `avg()`, `p90()` in Trace Explorer. |
There was a problem hiding this comment.
| Numeric attributes become metrics you can aggregate with `sum()`, `avg()`, `p90()` in Trace Explorer. | |
| Numeric attributes become metrics you can aggregate with `sum()`, `avg()`, `p90()` in [Trace Explorer](https://sentry.io/orgredirect/organizations/:orgslug/explore/traces/). |
|
|
||
| ### 1. Business-Critical User Flows | ||
|
|
||
| Track the full journey through critical paths. When checkout is slow, you need to know which step is responsible. |
There was a problem hiding this comment.
Could it be useful to contextually explain where in your code to add these snippets?
|
|
||
| Numeric attributes become metrics you can aggregate with `sum()`, `avg()`, `p90()` in Trace Explorer. | ||
|
|
||
| ## Where to Add Spans |
There was a problem hiding this comment.
Let's add the direct link to the explorer for each "Query in Explorer" https://sentry.io/orgredirect/organizations/:orgslug/explore/traces/
|
|
||
| **Alert idea:** `p90(span.duration) > 60s` for queue processing. | ||
|
|
||
| ### 5. AI/LLM Operations |
There was a problem hiding this comment.
Any reason we don't want to go into more detail in this guide or a separate AI monitoring guide about AI monitoring? I know it's just another input where we then create issues, capture traces, etc - maybe we just talk more about it in a couple of other places too?
| description: "Practical guidance on debugging errors and finding UX issues with Session Replay." | ||
| --- | ||
|
|
||
| You've set up [Sentry Session Replay](/product/explore/session-replay/). Now what? Stack traces tell you _what_ broke. Replay shows you _why_. This guide covers how to use replay to debug errors and spot UX problems before users report them. |
There was a problem hiding this comment.
Is it why or is it how it broke (for the user)?
|
|
||
| ## Where to Use Replay | ||
|
|
||
| Start with these five workflows and you'll debug faster and catch UX issues before they become support tickets. |
There was a problem hiding this comment.
Let's link "Go to Replays" with https://sentry.io/orgredirect/organizations/:orgslug/explore/replays
sfanahata
left a comment
sfanahata
left a comment
There was a problem hiding this comment.
Nice add! 💪
Left some non-blocking feedback throughout.
3 participants
Summary
Add a new /guides section with practical "what to do next" guidance for users who have set up Sentry but need direction on how to get value from it.
This introduces 6 new guides covering core Sentry workflows:
Each guide follows a consistent pattern:
SDK Coverage
Code examples across all guides for:
Additional Changes
The guides focus on being immediately actionable rather than comprehensive reference material, helping users move from "Sentry is installed" to "Sentry is helping me find and fix problems."
IS YOUR CHANGE URGENT?
PRE-MERGE CHECKLIST
Co-Authored-By: Claude noreply@anthropic.com