Skip to content

feat(develop-docs): Add instructions how to add a new client outcome reason #17347

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Lms24 merged 2 commits into from
Apr 16, 2026
+11 −2
Merged

feat(develop-docs): Add instructions how to add a new client outcome reason #17347

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
204bff2
feat(develop-docs): Add instructions how to add a new client outcome …
Lms24 Apr 15, 2026
181dfb9
Apply suggestion from @Lms24
Lms24 Apr 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 11 additions & 2 deletions develop-docs/sdk/telemetry/client-reports.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -343,7 +343,6 @@ The following discard reasons are defined for `discarded_events`:
| `cache_overflow` | 1.0.0 | SDK internal cache (e.g., offline event cache) overflowed. |
| `ratelimit_backoff` | 1.0.0 | Rate limit instructed the SDK to back off. |
| `network_error` | 1.0.0 | Network errors, not retried. |
| `no_parent_span` | 1.22.0 | Span was not started or dropped because no parent span was present at span start (for example, auto-instrumented spans suppressed when the request happens outside an active span). |
| `sample_rate` | 1.0.0 | Configured sample rate. |
| `before_send` | 1.0.0 | Dropped in `before_send`. |
| `event_processor` | 1.0.0 | Dropped by event processor; may also be used for ignored exceptions/errors (since 1.6.0). |
Expand All @@ -354,8 +353,18 @@ The following discard reasons are defined for `discarded_events`:
| `buffer_overflow` | 1.15.0 | SDK internal buffer (e.g., breadcrumbs buffer) overflowed. |
| `ignored` | 1.16.0 | Telemetry item was ignored by the SDK (e.g., a span was ignored by `ignore_spans`; can also be used by other deny-list mechanisms). |
| `invalid` | 1.17.0 | Failed validation (e.g., replay session exceeded maximum allowed length). |
| `no_parent_span` | 1.22.0 | Span was not started or dropped because no parent span was present at span start (for example, auto-instrumented spans suppressed when the request happens outside an active span). |

#### Adding a new discard reason:

Adding a new reason involves multiple repos in Sentry but is very straight-forward:

1. Register the new reason in [snuba](https://github.com/getsentry/snuba/blob/dd7ca91d81484455953653f59ed4ab90ecbc9719/rust_snuba/src/processors/outcomes.rs#L15). The list MUST be ordered alphabetically ([Example PR](https://github.com/getsentry/snuba/pull/7866)).
2. Add the new reason to the Sentry frontend to show it in the Usage Stats and `_admin` pages ([Example PR](https://github.com/getsentry/sentry/pull/112937)).
Copy link
Copy Markdown
Member

@cleptric cleptric Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is a difference between _admin and stats page, as in we group certain outcomes for user consumption and do not just return the raw outcome like we do on _admin.

Copy link
Copy Markdown
Member Author

@Lms24 Lms24 Apr 16, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I checked with @shellmayr and Cursor: While true that we group and omit certain outcomes/discard reason sub categories in the user-facing page, this currently only concerns server-side outcomes. Client outcomes are all displayed at the moment. I'm gonna merge this as-is for the time being because I don't (yet) see a reason to not emit an outcome. Happy to follow up with changes if we need any.

3. Add the new reason to this develop doc ([Example PR](https://github.com/getsentry/sentry-docs/pull/17292)).
4. Add the new reason to product docs ([Example PR](https://github.com/getsentry/sentry-docs/pull/17346)).

In case a reason needs to be added, it also has to be added to the allowlist in [snuba](https://github.com/getsentry/snuba/blob/master/rust_snuba/src/processors/outcomes.rs#L15).
Once all these PRs are merged and deployed, the new reason can be shipped in SDKs.

</SpecSection>

Expand Down
Loading