feat(grouping): Document hierarchical grouping (#3916)

Document grouping breakdown, sentinel and prefix frames.
New page is marked as draft, so it is still hidden from the sidebar.

Fix https://getsentry.atlassian.net/browse/INGEST-115

Author: jjbayer

src/docs/product/data-management-settings/event-grouping/grouping-breakdown/breakdown_level_01.png

@@ -0,0 +1,100 @@
+---
+title: "Grouping Breakdown"
+sidebar_order: 3
+draft: false
+description: "Learn more about the grouping algorithm and using the Grouping tab in Issue Details."
+---
+
+<Note>
+
+This feature is currently only available to a few select organizations. If you have any feedback, please mail [[email protected]](mailto:[email protected]).
+
+</Note>
+
+<!--
+<Note>
+
+This feature is available only if you're in the Early Adopter program. Features available to Early Adopters are still in-progress and may have bugs. We recognize the irony.
+
+If you’re interested in being an Early Adopter, you can turn your organization’s Early Adopter status on/off in General Settings. This will affect all users in your organization and can be turned back off just as easily.
+
+</Note>
+-->
+
+Sentry's current grouping algorithm puts two error events into the same issue if they have the same stack trace. This approach sometimes creates multiple distinct issues for errors with the same root cause.
+
+If two distinct issues are created occasionally, you may be able to reduce the noise by manually [merging](/product/issues/issue-details/#tabs) those issues. Alternatively, if you want coarser issue groups (thus fewer issues) by default, follow the process outlined here.
+
+
+<!--
+## Enable the Grouping Breakdown (beta)
+
+Enable our newest grouping algorithm, which creates coarser (that is, fewer) issues by considering only the most relevant part of the stack trace.
+
+1. Join our Early Adopter program by navigating to **Settings > General Settings**.
+
+1. [Upgrade to the latest grouping algorithm](/product/data-management-settings/event-grouping#grouping-algorithms).
+
+<Alert level="warning" title="Changing the grouping algorithm">
+
+Upgrading the grouping algorithm cannot be undone.
+
+</Alert>
+-->
+
+## Use the Updated Grouping Breakdown
+
+After enabling the updated grouping algorithm, the grouping breakdown allows you to navigate subgroups of an issue, to see what events would group together if a larger part of the stack trace were to be considered.
+
+For example, if you have a crashing function called from multiple locations in your code ("intermediate function" "1" and "2"), when you move the slider all the way to the left, only the crashing frame is considered for grouping, and
+all events are sorted into the same issue regardless of the calling location:
+
+![Breakdown of this issue on the highest level](breakdown_level_01.png)
+
+When you move the slider to the right, you can see what groups would be created
+if the calling frame were also to be considered:
+
+![Breakdown of this issue on an intermediate level](breakdown_level_02.png)
+
+You can add another level by moving the slider all the way to the right. However, this does not add any new subgroups, as both calling functions are themselves called from the same location (`main`):
+
+![Breakdown of this issue on the deepest level](breakdown_level_03.png)
+
+## Sentinel & Prefix Frames
+
+With Grouping Breakdown enabled, Sentry groups events by identifying the most
+interesting group of frames it can find in a stack trace.
+
+To mark frames as interesting, use the `+sentinel` and `+prefix` actions in [Stack Trace Rules](/product/data-management-settings/event-grouping/stack-trace-rules). For the first level, our algorithm looks for the first frame `X` which is marked as sentinel. The fingerprint of this frame is added to the level. If `X` is also a prefix frame, the next frame `Y` is also added. If `Y` is again a prefix frame, the next frame `Z` is added, and so on.
+
+If no sentinel frame is found, every frame that contributes to grouping according to the usual
+stack trace rules (for example, `+group`) constitutes its own level of detail.
+
+#### Example
+
+Consider a stack trace with functions `a`, `b`, `c`, `d`, `e`, `f`, `g`, `h`, with `a` being the crashing frame
+and `h` being the thread base. Imagine you have the following stack trace rules defined:
+
+```discover {tabTitle:Sentinel & Prefix Rules}
+function:b +sentinel +prefix
+function:c +prefix
+function:f +sentinel
+```
+
+In this case
+
+- `b` is used for grouping because it is the first sentinel frame,
+- `c` is used for grouping because `b` is a prefix frame,
+- `d` is used for grouping because `c` is a prefix frame.
+
+This becomes visible in the [Breakdown tab](/product/data-management-settings/event-grouping/grouping-breakdown):
+
+![Example Breakdown with Sentinel & Prefix Frames (level 1)](breakdown_sentinels_level_01.png)
+
+Increasing the level adds the second sentinel:
+
+![Example Breakdown with Sentinel & Prefix Frames (level 2)](breakdown_sentinels_level_02.png)
+
+Finally, the deepest level contains the entire stack trace, ignoring sentinel and prefix frames:
+
+![Example Breakdown with Sentinel & Prefix Frames (level 3)](breakdown_sentinels_level_03.png)

src/docs/product/data-management-settings/event-grouping/grouping-breakdown/breakdown_level_02.png

@@ -16,7 +16,7 @@ The syntax for stack trace rules is similar to:
 matcher-name:expression other-matcher:expression ... action1 action2 ...
 ```
 
-The syntax follows the syntax from [Discover queries](/product/discover-queries/). If you want to negate the match, you can prefix the expression with an exclamation mark (`!`).
+The syntax is the same as the syntax used for [Discover queries](/product/discover-queries/). If you want to negate the match, prefix the expression with an exclamation mark (`!`). If a line is prefixed with a hash (`#`), it's ignored and treated as a comment.
 
 The following is a practical example of how this looks:
 
@@ -44,9 +44,11 @@ Matches on the general platform family, which currently includes `javascript`, `
 ```discover {tabTitle:Match multiple}
 family:javascript,native stack.abs_path:**/generated/**  -group
 ```
+
 ```discover {tabTitle:Match only JavaScript}
 family:javascript stack.abs_path:**/generated/**  -group
 ```
+
 ```discover {tabTitle:Match only native}
 family:native stack.abs_path:**/generated/**  -group
 ```
@@ -99,13 +101,56 @@ stack.package:**/libcurl.dylib -group
 
 Matches on the current state of the in-app flag of a stack trace frame. `yes` means the frame is in-app, `no` means it's not.
 
+<!--
+
+### `category`
+
+Matches on a built-in [built-in](#built-in-categories) or a user-defined frame category.
+See [variable actions](#variable-actions) on how to set a category.
+
+```discover {tabTitle:Category Match}
+category:telemetry -group
+```
+
+#### Built-in Categories
+
+Frame categorization is heavily used by our newest grouping algorithm, so [if you have it enabled](/product/data-management-settings/event-grouping/grouping-breakdown#enable-the-grouping-breakdown-beta), you can match on a variety of categories, including:
+
+- `system` - detected system libraries
+- `std` - detected standard libraries
+- `ui` - UI frameworks
+- `driver` - graphics drivers, and so on
+- `telemetry` - crash reporting and analytics frameworks
+
+See [our source code](https://github.com/getsentry/sentry/blob/master/src/sentry/grouping/enhancer/enhancement-configs/mobile%402021-04-02.txt) for a full list of built-in categories.
+
+-->
+
 </DefinitionList>
 
+<!--
+
+### Matching Sibling Frames
+
+If information about the surrounding frames is necessary to apply a rule to a frame, use caller/callee matching syntax. For example:
+
+```discover {tabTitle:Sibling matches}
+# Ignore in-app frames if they are called by telemetry
+[ category:telemetry ] | app:yes -group
+
+# Ignore system frames if they call app frames
+category:system | [ app:yes ] -group
+```
+
+-->
+
 ## Actions
 
 There are two types of **actions**: flag and variables setting.
 
-1. A **flag** identifies the action to be taken if all matchers match and uses these prefixes:
+### Flag Actions
+
+A _flag_ identifies the action to be taken if all matchers match, and it uses these prefixes:
 
 - `+` sets the flag
 - `-` unsets the flag
@@ -117,11 +162,25 @@ As an example, `-group ^-group` removes the matching frame and all frames above
 - `app`: marks or unmarks a frame in-app
 - `group`: adds or removes a frame from grouping
 
-2. **variables**: Variables can be set (`variable=value`). Currently, there is just one:
+<!--
+- `sentinel`: marks a frame as [sentinel frame](#sentinel--prefix-frames)
+- `prefix`: marks a frame as [prefix frame](#sentinel--prefix-frames)
+-->
 
-- `max-frames`: sets the total number of frames to be considered for grouping. The default is `0`, which means "all frames." If set to `3`, only the top three frames are considered.
+### Variable Actions
 
-If a line is prefixed with a hash (`#`), it's a comment and ignored.
+A limited set of _variables_ can be defined (`variable=value`):
+
+- `max-frames`: Sets the total number of frames to be considered for grouping. The default is `0`, which means "all frames". If set to `3`, only the top three frames are considered.
+
+<!--
+- `category`: Sets a custom category for the frame.
+
+  - Custom categories overwrite [built-in categories](#built-in-categories).
+  - If multiple category-applying rules match a frame, only the category set in the bottom-most rule is preserved.
+-->
+
+### Example
 
 ```discover {tabTitle:Enhancement Rules}
 stack.abs_path:**/node_modules/** -group
@@ -197,7 +256,6 @@ SentrySDK.start { options in
 When using static frameworks, the frameworks end up in the main executable. Therefore, the SDK currently can't detect if a frame of the main executable
 originates from your application or a private framework and marks all of them as `inApp`. To improve your experience, use the below explained stack trace rules on the server to tell Sentry which should be marked as `not inApp`.
 
-
 #### Stack Trace Rules
 
 The following marks frames from libdispatch starting with `_dispatch_` as `inApp`.
@@ -213,6 +271,7 @@ app:no                   +app
 stack.function:std::*    -app
 stack.function:boost::*  -app
 ```
+
 <Note>
 
 You need to force all frames to be in-app first because there might already have been some defaults set by the client SDK or earlier processing.

src/docs/product/data-management-settings/event-grouping/grouping-breakdown/breakdown_level_03.png

@@ -34,7 +34,7 @@ Fortunately you can change the default grouping behavior to make certain issue t
 
 </Note>
 
-# Solutions
+## Solutions
 
 There are three different approaches for updating how events group into issues. The first approach is for merging together historical issues already created. We'll call this **Merging Similar Issues**. The second is for setting rules so next incoming issues will get grouped together. We'll call this **Fingerprint Rules**. The third is **SDK Side Fingerprinting**. The difference between SDK side and Server side is the data elements on the exception and stack traces which you can use for matching issues.
 
@@ -44,7 +44,7 @@ In **Fingerprint Rules** we'll see how to set rules for new incoming issues of o
 
 More on **SDK Side Fingerprinting** [here](/platform-redirect/?next=/usage/sdk-fingerprinting/).
 
-## Merging Similar Issues
+### Merging Similar Issues
 
 This is for merging similar issues and will not auto merge the next occurrence of this issue coming in.
 
@@ -59,14 +59,14 @@ You can also do this from inside a single issue. Click the Similar Issues tab
 
 **Warning:** Future issues will get added to the merged set only if they match one of the stack traces in the merged set.
 
-## Fingerprint Rules
+### Fingerprint Rules
 
 Here's an overview of what we'll do using **Fingerprint Rules**
 
 1. Identify the match logic for grouping issues together. We'll use either the error's **type** or **message**
 2. Set the match logic and its fingerprint for it, in your Project's Settings.
 
-### 1. Identify Match Logic
+#### 1. Identify Match Logic
 
 Let's say you want the following 2 issues to group together:
 ![ConnectionTimeouts](connection-timeouts-2.png)
@@ -79,7 +79,7 @@ Or you can do it based on the **message** as in any value after the word host:
 
 ![ConnectionTimeoutMessage](connection-timeout-message.png)
 
-### 2. Implement
+#### 2. Implement
 
 Here's how to set the match based on the error **type**