Skip to content
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

Jump to bottom

ref(stats): Introduce discard outcome & reason descriptions #10585

Merged
merged 18 commits into from
Jul 18, 2024
Merged

ref(stats): Introduce discard outcome & reason descriptions #10585

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
28d0b0b
ref(stats): Introduce discard outcome & reason descriptions
priscilawebdev Jul 4, 2024
599c8b1
small fix
priscilawebdev Jul 4, 2024
3c2b676
Update docs/product/stats/index.mdx
priscilawebdev Jul 5, 2024
c7c0568
feedback
priscilawebdev Jul 7, 2024
6086735
add ponctuation
priscilawebdev Jul 7, 2024
cef463f
add description for filtered
priscilawebdev Jul 7, 2024
4e5843e
Merge branch 'master' into priscila/ref/usage-stats/add-reason-meanin…
priscilawebdev Jul 9, 2024
a701897
Merge branch 'master' into priscila/ref/usage-stats/add-reason-meanin…
priscilawebdev Jul 15, 2024
1769c7f
feedback
priscilawebdev Jul 15, 2024
1d1d8a6
update screenshot
priscilawebdev Jul 15, 2024
e0976eb
update links
priscilawebdev Jul 15, 2024
4b57e70
add reasons for rate limited
priscilawebdev Jul 15, 2024
3d12a81
feedback
priscilawebdev Jul 15, 2024
7667f7e
update phrase
priscilawebdev Jul 15, 2024
9dac392
feedback
priscilawebdev Jul 16, 2024
59042c8
Update docs/product/stats/index.mdx
priscilawebdev Jul 16, 2024
71b5cbb
Update docs/product/stats/index.mdx
priscilawebdev Jul 16, 2024
3fac6c1
Update docs/product/stats/index.mdx
priscilawebdev Jul 16, 2024
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
Binary file added docs/product/stats/img/usage-stats-page.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/product/stats/img/usage-stats.png
View file
Open in desktop
Binary file not shown.
88 changes: 82 additions & 6 deletions docs/product/stats/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,87 @@ The "Usage" tab shows your organization’s event and attachments usage, while a

## Usage Stats

The "Usage" tab shows you the events (errors and transactions) and attachments Sentry has received across your entire organization along with a list of all projects and their consumption of each of those. Your usage falls into one of three categories: _Accepted_, _Filtered_, or _Dropped_. Filtered events and attachments are ones that were blocked due to your [inbound data filter](/concepts/data-management/filtering/) rules. Dropped events and attachments are ones the system dropped or discarded due to rate limits, quotas, spike protection, [size limits](/concepts/data-management/size-limits), or because of invalid data.

You can see which projects have had a recent spike or are the most active and may need more attention. On this page, you can also control the date range that’s displayed, allowing you to focus on a smaller period of time or zoom out for a longer view. The page is designed for org admins, but is available to all team members. This is helpful if a team member who isn't an admin is tasked with reviewing these statistics. Also, this allows team members associated with specific projects to use this page to investigate why their events are being dropped.

![Overview of Usage Stats page](./img/usage-stats.png)
The "Usage" tab provides an overview of the events (errors and transactions) and attachments that Sentry has received across your entire organization. It includes a detailed breakdown of each project's consumption categorized as _Accepted_, _Filtered_, _Discarded_, or _Dropped_.

#### Accepted
priscilawebdev marked this conversation as resolved.
Show resolved Hide resolved

Events and attachments that were successfully processed and stored.

#### Discarded
priscilawebdev marked this conversation as resolved.
Show resolved Hide resolved

Events and attachments discarded on the client side due to the sampling configuration in the SDK or other factors.
Copy link
Member

Choose a reason for hiding this comment

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

"or other factors" is a bit unspecific. I would either remove this part of the sentence or list more reasons. They are documented here under "discarded_events": https://develop.sentry.dev/sdk/client-reports/#envelope-item-payload


#### Filtered
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
#### Filtered
### Filtered


| Reason | Meaning |
| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [Browser Extensions](/concepts/data-management/filtering/#browser-extension-errors) | Filtered by browser extension. |
| Denied Name | Filtered due to name being denied. |
| Disabled Namespace | Filtered due to the namespace being disabled. |
priscilawebdev marked this conversation as resolved.
Show resolved Hide resolved
| Error Message | Filtered based on specific error message. |
| Filtered Transactions | Filtered because it was a call to a filtered transaction. |
| Ip Address | Filtered by IP address. |
| Invalid CSP | Filtered due to an invalid Content Security Policy (CSP) policy. |
| [Legacy Browsers](/concepts/data-management/filtering/#legacy-browser-filters) | Filtered out certain legacy versions of browsers that are known to cause problems. |
| Localhost | Filtered due to localhost restriction. |
| Release Version | Filtered by release name (version). |
| [Web Crawlers](/concepts/data-management/filtering/#web-crawler-errors) | Identified as known web crawler. |
| ? (Others) | Filtered due to other generic filtering rules not specified above. |

#### Dropped
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
#### Dropped
### Dropped


Events and attachments discarded by the system due to rate limits, quotas, spike protection, [size limits](/concepts/data-management/size-limits), or invalid data. You can see the common reasons below:
Copy link
Member

Choose a reason for hiding this comment

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

This combines the two outcomes RATE_LIMITED and INVALID. Do you really want to mix those?

Copy link
Member Author

@priscilawebdev priscilawebdev Jul 7, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

yes, because we are combining them in the code https://github.com/getsentry/sentry/blob/566f4a0a04d9a9dd6f1a56d13808ea715b913e8b/static/app/views/organizationStats/usageStatsOrg.tsx#L391-L396. So they are listed under dropped

priscilawebdev marked this conversation as resolved.
Show resolved Hide resolved

| Reason | Meaning |
Copy link
Member Author

Choose a reason for hiding this comment

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

I was uncertain about adding this table here since it can get quite lengthy. However, I didn't want to place it elsewhere, as that might make it feel disconnected from the usage stats section. Thoughts?

Copy link
Member

Choose a reason for hiding this comment

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

I would not list those at all. Those outcome reasons are not stable and meant for internal use. Apart from that, they refer to internals of the system that are confusing to a user.

Copy link
Member Author

@priscilawebdev priscilawebdev Jul 7, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

I understand those outcome reasons are intended for internal use and may confuse users. However, if users can see this information, we should provide at least a brief explanation to ensure clarity. Are you sure it’s better to not add an explanation for these reasons?

Copy link
Member

Choose a reason for hiding this comment

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

Let's expose these reasons in a simplified and grouped way that makes it easier for users to comprehend. I will post an update here with mapped reasons and improved descriptions.

Copy link
Member

Choose a reason for hiding this comment

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

Here is a list that groups all discard reasons so that they can be understood by users. I've also added more relatable descriptions that point at docs to make this more actionable.

https://gist.github.com/jan-auer/2d29e2ee6334bbcf32514b12b42b31ea

As for the different kinds of outcomes, please show them separately in the following combination at least in charts:

  • Accepted (0)
  • Filtered (1)
  • Rate limited (2) + Abuse (4) + Cardinality Limited (6) -- currently shown as "Dropped" in the UI
  • Invalid (3)
  • Client Discard (5)

| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Abuse | Activated when Sentry is misused. |
| Auth Client | The SDK did not send a client identifier. In Relay, this is no longer required. |
| Auth Version | The protocol version sent by the SDK is not supported and parts of the payload may be invalid. |
| Cardinality Limited | Exceeded internally defined cardinality limit. |
| Content Type | The content type for a specific endpoint was not allowed. |
| Cors | The request origin is not allowed for the project. |
| Disallowed Method | A store request was received with an invalid method. |
| Duplicate | An event with the same id has already been processed for this project. |
| Duplicate Item | An envelope was submitted with two items that need to be unique. |
| Empty Envelope | The envelope contains no items. |
| Feature Disabled | The envelope contains no items. |
| Internal | An error in Relay caused event ingestion to fail. |
| Invalid Compression | The payload had an invalid compression stream. |
| Invalid Envelope | Parsing an event envelope failed (likely missing a required header). |
| Invalid Json | Parsing the event JSON payload failed due to a syntax error. |
| Invalid Minidump | The file submitted as minidump is not a valid minidump file. |
| Invalid Msgpack | Parsing the event msgpack payload failed due to a syntax error. |
| Invalid Multipart | Parsing a multipart form-data request failed. |
| Invalid Replay Event | Sentry failed to parse the replay so we dropped it. |
| Invalid Replay Event No Payload | Sentry failed to parse the replay so we dropped it. |
| Invalid Replay Event Pii | Sentry failed to parse the replay so we dropped it. |
| Invalid Replay Record Event | Sentry failed to parse the replay so we dropped it. |
| Invalid Replay Video Event | Sentry failed to parse the replay so we dropped it. |
| Invalid Span | A span is not valid after normalization. |
| Invalid Transaction | The event is parseable but semantically invalid. This should only happen with transaction events. |
priscilawebdev marked this conversation as resolved.
Show resolved Hide resolved
| Missing Minidump Upload | A minidump file was missing for the minidump endpoint. |
| Multi Project Id | The project id in the URL does not match the one specified for the public key. |
| No Data | The store request was missing an event payload. |
| No Event Payload | An event envelope was submitted but no payload could be extracted. |
| Payload | Parsing the event JSON payload failed due to a syntax error. |
| Process Unreal | Symbolic failed to extract an Unreal Crash report from a request sent to the Unreal endpoint. |
| Profiling | Profiling related dropped reasons. |
| Project Id | There was no valid project id in the request or the required project does not exist. |
| Project State | A project state returned by the upstream could not be parsed. |
| Project State Pii | A project state returned by the upstream contained datascrubbing settings that could not be converted to PII config. |
| Rate Limited | Exceeded allowed event rate. |
| Spike Protection | Activated to protect from any sudden quota-depleting spike. |
| Security Report | Triggered to prevent any sudden spikes that could deplete the quota. |
| Security Report Time | The security report was not recognized due to missing data. |
| Timestamp | The timestamp of an event was required for processing and either missing out of the supported time range for ingestion. |
| Too Large | The event payload exceeds the maximum size limit for the respective endpoint. |
| Transaction Sampled | The envelope, which contained only a transaction, was dropped by the dynamic sampling rules. |
priscilawebdev marked this conversation as resolved.
Show resolved Hide resolved
priscilawebdev marked this conversation as resolved.
Show resolved Hide resolved

On this page, you can track projects that have experienced recent spikes in activity or are particularly active, which may require closer attention. Additionally, you have the flexibility to adjust the displayed date range, enabling you to narrow down to a specific period or zoom out for a broader overview.

While primarily designed for organization admins, this page is accessible to all team members. This inclusivity is beneficial, especially when non-admin team members need to review these statistics. It allows them to investigate why events associated with their specific projects might be discarded, dropped or filtered.

![Overview of Usage Stats page](./img/usage-stats-page.png)
priscilawebdev marked this conversation as resolved.
Show resolved Hide resolved

With the dropdowns at the top of the page, you can set whether the page displays stats for errors, transactions, or attachments, as well as the date range. With the date selector, the time period can be set from an hour to a maximum of 90 days, and all of the page elements change dynamically when you update this setting.

Expand All @@ -25,7 +101,7 @@ With the dropdowns at the top of the page, you can set whether the page displays

### Usage Cards

The cards on the page provide high-level usage stats about events and attachments, including the total number of either for the period, as well as which ones were accepted, filtered, or dropped.
The cards on the page provide high-level usage stats about events and attachments, including the total number of either for the period, as well as which ones were accepted, filtered, discarded or dropped.
priscilawebdev marked this conversation as resolved.
Show resolved Hide resolved

### Summary Chart

Expand Down
Loading