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 11 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?
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