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 merged 22 commits intomasterfrom
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
docs/guides/custom-spans.mdx
Outdated
|
|
||
| ## The Pattern | ||
|
|
||
| ```javascript |
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
|
|
||
| **Context:** Tags, user info, and breadcrumbs help you debug faster. Tags are searchable, so use them for high-cardinality data like IDs, regions, and feature flags. | ||
|
|
||
| Every error in Sentry is automatically trace-connected. Click the trace ID to see the full [trace view](/concepts/key-terms/tracing/trace-view/) and understand what led to the error. |
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
|
|
||
| Issue alerts notify you when specific conditions are met. To create one: | ||
|
|
||
| 1. Go to **Alerts** and click "Create Alert Rule" |
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
|
|
||
| When you catch an error, add tags, user info, and breadcrumbs to make debugging instant. | ||
|
|
||
| ```javascript |
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
|
|
||
| **Levels:** `fatal`, `error`, `warning`, `info`, `debug` | ||
|
|
||
| **Context:** Tags, user info, and breadcrumbs help you debug faster. Tags are searchable, so use them for high-cardinality data like IDs, regions, and feature flags. |
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
|
|
||
| High event counts mean either many users are affected or one user is stuck in a loop. Both need immediate attention. | ||
|
|
||
| **In 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.
| **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
|
|
||
| ## Where to Look | ||
|
|
||
| Start with these five views to catch critical issues. |
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
| - Patterns in feedback about specific workflows or features | ||
| - Issues that frustrate users even if they don't generate many events | ||
|
|
||
| Enable the [User Feedback Widget](/platforms/javascript/user-feedback/) to let users report problems directly when errors happen. |
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
|
|
||
| **Alert idea:** Trigger when a new issue is created, filtered to issue category equals feedback. This ensures you respond quickly when users report problems. | ||
|
|
||
| ## Creating Issue Alerts |
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
|
|
||
| ### Capture Context, Not Just Exceptions | ||
|
|
||
| When you catch an error, add tags, user info, and breadcrumbs to make debugging instant. |
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
docs/guides/issues-errors.mdx
Outdated
|
|
||
| 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
docs/guides/metrics.mdx
Outdated
| | **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?
| 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?
There was a problem hiding this comment.
Yep, I took it out in favor of this callout for now.
| - 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?
There was a problem hiding this comment.
Yeah this one is just about the queries, so lots of text. Can follow with screenshots
docs/guides/custom-spans.mdx
Outdated
|
|
||
| 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
There was a problem hiding this comment.
Updated to be more explicit
|
|
||
| ### 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?
There was a problem hiding this comment.
I think that's captured with the span names without getting specific in a text-heavy way since this would be somewhat subjective.
|
|
||
| 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)?
There was a problem hiding this comment.
How is more appropriate!
|
|
||
| ## 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.
Co-authored-by: Shannon Anahata <shannon.anahata@gmail.com>
* origin/master: docs(guides): Add practical 'what to do next' guides for key Sentry features (#16410) # Conflicts: # src/components/sidebar/sidebarNavigation.tsx
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