add server side sampling docs (#5315)

Co-authored-by: Daniel Khan <daniel@khan.io>
Co-authored-by: Markus Unterwaditzer <markus-honeypot@unterwaditzer.net>
Co-authored-by: Matej Minar <matej.minar@sentry.io>
Co-authored-by: Priscila Oliveira <priscilawebdev@gmail.com>
Co-authored-by: Jesse Box <me@jessebox.net>

Author: 6 people

src/docs/product/data-management-settings/server-side-sampling/current-limitations.mdx

@@ -0,0 +1,44 @@
+---
+title: Current Limitations
+sidebar_order: 20
+description: "Learn about the current limitions of server-side sampling."
+---
+
+<Note>
+
+This feature is in beta and is only available if your organization is participating in its limited release. Features in beta are still in-progress and may have bugs. We recognize the irony. If you’re interested in participating, [join the waitlist](https://sentry.io/for/performance/#updates-signup).
+
+</Note>
+
+Following are the current known limitations and functionality specifics that can create challenges when you're writing server-side sampling rules.
+
+## Supported SDKs & Versions
+
+Server-side sampling is currently only available for the following SDK's:
+
+- Python: 1.7.2 or later
+- JavaScript: 7.6.0 or later
+- Apple: 7.23.0 or later
+- Android: 6.2.1 or later
+
+If your application relies on any Sentry SDK that isn't specified above, then you won’t be able to use server-side sampling.
+
+## Trace rules can only select based on the attributes of the initial transaction
+
+When sampling traces, the decision to keep or throw away a trace needs to be taken when the first transaction of the trace is seen. This in turn means that for transaction traces, only the attributes of the first transaction can participate in the sampling decision. For example, if you have a frontend and a backend in the trace, you can only sample the trace by the SDK context available in the frontend, not the backend data.
+
+## Changing trace attributes in secondary transactions
+
+Related to the previously discussed issue about trace rules, setting the transaction, the release, or the environment in a transaction will have no influence on a trace sampling decision if the transaction is not the first transaction in the trace.
+
+## Limited number of rule conditions
+
+We're actively working on adding more conditions that you can sample by (for example, transaction name). However, feel free to provide suggestions by joining the channel [#server-side-sampling](https://discord.com/channels/621778831602221064/1004667579035570176) on our Discord Server.
+
+## Arbitrary logical composition for rule conditions
+
+Currently, rules containing more than one condition use a logical `and` for each condition. Multiple values for a condition use a logical `or` condition for matching.
+
+The decision to implement it this way was based on the desire to keep the UI simple while still being able to cover all common scenarios.
+
+Having multiple arguments within a single condition use the `or` operator is what we typically want since an attribute generally has one value and having an `and` condition wouldn't make sense. For example, the environment attribute could be `prod` or `dev`, but it couldn't be `prod` and `dev` at the same time.

src/docs/product/data-management-settings/server-side-sampling/edit-rule-modal.png

@@ -0,0 +1,81 @@
+---
+title: Getting Started
+sidebar_order: 10
+description: "Learn how to get started with server-side sampling."
+---
+
+<Note>
+
+This feature is in beta and is only available if your organization is participating in its limited release. Features in beta are still in-progress and may have bugs. We recognize the irony. If you’re interested in participating, [join the waitlist](https://sentry.io/for/performance/#updates-signup).
+
+</Note>
+
+<Note>
+
+To set up or configure server-side sampling, you need to be an Owner, Manager, or Admin of your Sentry organization.
+
+</Note>
+
+## Current Limitations
+
+Server-side sampling is currently only available for the following SDK's:
+
+- Python: 1.7.2 or later
+- JavaScript: 7.6.0 or later
+- Apple: 7.23.0 or later
+- Android: 6.2.1 or later
+
+If your application relies on any Sentry SDK that isn't specified above, then you won’t be able to use server-side sampling.
+
+There are other limitations that you should be aware of when setting up server-side sampling:
+
+- [Trace rules can only select based on the attributes of the initial transaction](/product/data-management-settings/server-side-sampling/current-limitations/#trace-rules-can-only-select-based-on-the-attributes-of-the-initial-transaction)
+- [Changing trace attributes in secondary transactions](/product/data-management-settings/server-side-sampling/current-limitations/#changing-trace-attributes-in-secondary-transactions)
+- [Limited number of rule conditions](/product/data-management-settings/server-side-sampling/current-limitations/#limited-number-of-rule-conditions)
+- [Arbitrary logical composition for rule conditions](/product/data-management-settings/server-side-sampling/current-limitations/#arbitrary-logical-composition-for-rule-conditions)
+
+For more detailed information about each of these, check out our [full Current Limitations documentation](/product/data-management-settings/server-side-sampling/current-limitations/).
+
+## 1. Update Sentry SDK Versions
+
+Once you’ve confirmed that your application only relies on [supported SDKs](#current-limitations), then the next step is to update them to the specified version or higher. Check out the migration documentation for the [SDKs](/platforms/) you’re using to learn everything you need to know to get up and running again with the latest Sentry features.
+
+## 2. Set a Uniform Sampling Rate
+
+Next, go to **[Project] > Settings > Server-side Sampling** in [sentry.io](https://sentry.io) and set a uniform sampling rate for all transactions: this is the number of transactions that Sentry should accept from your application:
+
+![Setting a uniform sampling rate for your project](set-uniform-sampling-rate.png)
+
+Based on your quota and usage, in this step, we’ll suggest sampling rates for both Sentry servers and your Sentry SDK. However, you can enter a custom sampling rate by overriding our recommended values. For example, you can select your current sampling rates to understand how our proposed sampling configuration would impact your transaction volume within the scope of this project. Learn more about [How Sentry Samples](/product/data-management-settings/server-side-sampling/#how-sentry-samples).
+
+The numbers you enter in the “Client” field do not affect your actual SDK sample rate, but if you click “Next” and save, the number you’ve entered in the “Server” field on the “Suggested” row is saved as your uniform server-side sampling rate.
+
+Even though you’ll only set this for one project/SDK, **this rate can affect all the transactions distributed across multiple services**, including other projects set up in Sentry. That’s because server-side currently samples by the context of all other transactions belonging to the same trace. Check out our [full Tracing documentation](/product/sentry-basics/tracing/) for a more detailed explanation.
+
+If this chart doesn’t provide enough information for you to determine a uniform sampling rate for this project, we recommend checking your **Stats** page. The **Stats** page provides a complete overview of how many transactions each project accepts, filters, and drops rather than for just one project.
+
+Once you've entered a uniform sample rate for all transactions, now you need to activate it by clicking “Done” and then toggling the rule to on:
+
+![A sampling rule with the Active toggle highlighted](sampling-rule-toggle.png)
+
+## 3. Set a Sampling Rate Based on a Condition
+
+Now, click “Add Rule” to set more sampling rules based on specific conditions. These rules will help you target the transactions you want to keep and allow you to have more of those transactions sent by the SDK.
+
+When a rule uses multiple conditions, we use the logical expression `AND` to determine when that rule should be evaluated. Multiple values for a condition use a logical or condition for matching. Learn more about [how to create effective server-side sampling rules](/product/data-management-settings/server-side-sampling/#server-side-sampling-configurations).
+
+You can use the following conditions to sample transactions by:
+
+- Environment
+- Release\*
+
+\* Allows glob pattern matching
+
+![Editing a sampling rule based on a release condition](edit-rule-modal.png)
+
+If we've accepted a transaction which contains a key-value pair matching the above conditions in the past, Sentry will suggest values for each condition. Of course, you're free to set a custom value for each condition. Then, specify a sampling rate for that specific rule.
+
+## 4. Increase Your SDK Transaction Sample Rate
+
+Generally speaking, the more active sampling rules you have, the fewer transactions we'll accept. If the volume of transactions our servers are receiving is insufficient given the rules you've specified, you might need to increase the sampling rate configured for your Sentry SDK. To see what we would suggest for your SDK sample rate, go to **[Project] > Settings > Server-side Sampling** and open the last rule in the list, which is where your uniform sample rate is set. Our suggestion is displayed there.
+

src/docs/product/data-management-settings/server-side-sampling/getting-started.mdx

@@ -0,0 +1,53 @@
+---
+title: Server-side Sampling
+sidebar_order: 1
+description: "Learn about how you can control which transactions Sentry retains."
+---
+
+<Note>
+
+This feature is in beta and is only available if your organization is participating in its limited release. Features in beta are still in-progress and may have bugs. We recognize the irony. If you’re interested in participating, [join the waitlist](https://sentry.io/for/performance/#updates-signup).
+
+</Note>
+
+Capturing a single trace involves minimal overhead, but capturing traces for every page load or every API request may add an undesirable load to your system. Sampling your events allows you to better manage the number of events sent to Sentry, so you can tailor your volume to your organization's needs.
+
+_Server-side sampling_ lets you control which transactions Sentry retains by setting sampling rules and rates, so you see more of the transactions you want to explore further, and less of the ones you don’t. In contrast to [client-side sampling](/platform-redirect/?next=/configuration/sampling/), server-side sampling allows you to manage your sampling configuration centrally and lets you make changes without the need to reconfigure the SDK and redeploy your application.
+
+![The Server-side Sampling page with a list of rules](server-side-sampling.png)
+
+> [A trace](/product/sentry-basics/tracing/distributed-tracing/) represents the record of an entire operation you want to measure or track, like page load, an instance of a user completing some action in your application, or a cron job in your backend. A trace consists of one or more transactions and the trace can be distributed across multiple services or projects.
+
+Because every project is different, you can set multiple sample rules with different sample rates per project. For example, you may need more events from high converting pages, critical API endpoints, or need to focus on latency issues from your latest release.
+
+Server-side sampling also makes your SDK and your sampling configuration largely independent of each other. This helps if you're building native applications with many releases active at a given time.
+
+## How Sentry Samples
+
+Before understanding how Sentry samples, there are some concepts you need to know:
+
+- Total transaction volume: Total number of transactions the Sentry SDK has observed before any sampling has begun.
+- Client-side(SDK) sampling: The process of selecting which transactions are discarded or sent to Sentry for processing.
+- Server-Side sampling: The process of selecting which transactions are indexed after being processed.
+
+Whether you’re sampling client-side or server-side, it’s always relative to the total transaction volume. Using the first illustration below as an example, we start the process of client-side sampling with a total transaction volume of 4. The client-Side sample rate is set at 50% which leaves only 2 transactions being sent to Sentry for processing. Server-side sampling then takes these 2 processed transactions and indexes only 1 of them because it's sampling at 25% (or a quarter) of the total transaction volume.
+
+![Visualization of how Sentry samples with an effective sampling configuration](server-side-sampling-a.png)
+
+In the next illustration, we show what would happen if the client-side sample rate was lower than the server-side rate. We again start the process of client-side sampling with a total transaction volume of 4. The client-side sample rate is lower this time, set at 25%, leaving only 1 transaction being sent to Sentry for processing. At this stage, you might be asking, “how can server-side sample 50% of the total transaction volume when the client has already discarded 75%?”. It can’t. So even though the server-side sample rate is set to 50% of the total volume, it will only index the 1 transaction it received from the client.
+
+Ultimately, your server-side sample rate must always be equal or lower than your client-side sample rate.
+
+![Visualization of how Sentry samples with an ineffective sampling configuration](server-side-sampling-b.png)
+
+## Traces & Propagation of Sampling Decisions
+
+For Dynamic Sampling, we want to make sampling decisions for entire traces. Sampling transactions using transaction traces is advantageous when trying to understand transactions in the context of the global system. In this case we are not interested in seeing a particular transaction, but the whole group of transactions in a trace, so sampling should occur at the trace level.
+
+When sampling traces, the sampling rules are based on the trace context, this means that the sampling decisions are based on the information extracted from the system that initiated the transaction.
+
+As a mental model: The head transaction in a trace determines the trace context for all following transactions in that trace. No information can be changed, added or deleted after the first propagation. The trace context is bound to only one particular trace, and all the transactions that are part of this trace.
+
+## Next Steps
+
+<PageGrid />

src/docs/product/data-management-settings/server-side-sampling/index.mdx

@@ -0,0 +1,71 @@
+---
+title: Server-side Sampling Configurations
+sidebar_order: 15
+description: "Learn about effective server-side sampling configurations."
+---
+
+<Note>
+
+This feature is in beta and is only available if your organization is participating in its limited release. Features in beta are still in-progress and may have bugs. We recognize the irony. If you’re interested in participating, [join the waitlist](https://sentry.io/for/performance/#updates-signup).
+
+</Note>
+
+<Note>
+
+To set up or configure server-side sampling, you need to be an Owner, Manager, or Admin of your Sentry organization.
+
+</Note>
+
+Now that you know how Sentry is sampling at a high-level, you can set server-side sampling rules in **[Project] > Settings > Server-side Sampling**.
+
+## Order of Precedence
+
+Rules evaluate from top to bottom, with the first matching rule determining the sample rate. Like with declaring a conditional statement in code, rules with the most specific conditional clauses should be evaluated first (`If`), followed by more generic ones (`Else If`). If generic rules lead the list, the more specific rules will likely never be evaluated. Setting a uniform sampling rate is equivalent to an `Else` clause which will always trail rules with conditional clauses.
+
+The Server-side Sampling page in sentry.io allows you to change the order of your rules so you can set it effectively.
+
+The following examples are illustrated as code samples, but you'll configure these rules using the **Server-side Sampling** page interface.
+
+## Good Examples
+
+**Most specific rule leads the list**
+
+The rule with the most specific conditional clause will always be evaluated because it's first in order.
+
+```
+if (release = 3.0) && (environment = production) {
+    transactionSample = 1.0
+} else if (environment = production) {
+    transactionSample = 0.5
+} else {
+    transactionSample = 0.25
+}
+```
+
+**Each rule is evaluated independently**
+
+This configuration also works just fine because each rule will be evaluated based on entirely different conditions.
+
+```
+if (release = 3.0) {
+    transactionSample = 1.0
+} else if (environment = production) {
+    transactionSample = 0.5
+} else {
+    transactionSample = 0.25
+}
+```
+
+## Poor Example
+
+The rule with the most specific conditional clause will never be evaluated because a rule with a similar, but more generic clause precedes it.
+
+```
+if (environment = production) {
+    transactionSample = 1.0
+} else if (release = 3.0) && (environment = production) {
+    transactionSample = 0.5 // Will never be evaluated
+} else {
+    transactionSample = 0.25
+}
+```