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 12 commits intomasterfrom
Conversation
…cs, and traces Add four new documentation pages that bridge the gap between SDK setup and getting value from Sentry's observability features: - what-to-log.mdx: High-value logging patterns with search and alert examples - what-to-track.mdx: Metric patterns for counters, gauges, and distributions - querying-traces.mdx: How to query auto-instrumented trace data - custom-spans.mdx: When and how to add custom instrumentation Each guide follows a consistent "5 things to add" structure with code examples, query patterns, and alert recommendations. Co-Authored-By: Claude <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
Link Sentry feature names (Sentry Issues, Sentry Logs, Sentry Metrics, Sentry Tracing, Session Replay) in the opening sentences to their corresponding product walkthrough pages under /product/explore/ and /product/issues/. This provides users with easy navigation to comprehensive product documentation while maintaining the practical focus of the guides. Co-Authored-By: Claude Sonnet 4.5 (1M context) <noreply@anthropic.com>
|
|
||
| ## 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.
|
|
||
| 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
|
|
||
| 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.
Co-authored-by: Alex Krawiec <alex.krawiec@sentry.io> Co-authored-by: Shannon Anahata <shannon.anahata@gmail.com>
jaffrepaul
force-pushed
the
docs/early-days-5-reasons-guides
branch
from
a376fdc to
062fe31
Compare
3 participants
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:
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."
Co-Authored-By: Claude Sonnet 4.5 (1M context) noreply@anthropic.com