feat(dynamic-sampling): organization settings

docs/concepts/key-terms/tracing/trace-view.mdx

@@ -84,7 +84,7 @@ Also, in these cases you can click "Open In Discover" to see all the events in t
 
 Broken subtraces may be caused by:
 
-- SDK sampling. Setting a sample rate that's too low may prevent the SDK from sending a transaction. We recommend [sending us all of your transaction data](/product/performance/retention-priorities/#deciding-on-your-sdk-sample-rate).
+- SDK sampling. Setting a sample rate that's too low may prevent the SDK from sending a transaction. We recommend [sending us all of your transaction data](/organization/dynamic-sampling/#deciding-on-your-sdk-sample-rate).
 - [Ad blockers](/platforms/javascript/troubleshooting/#dealing-with-ad-blockers) may prevent transactions in browsers being sent, but HTTP requests to backend projects will still create child transactions
 - [Rate-limiting](/product/accounts/quotas/#limiting-events) on a project may cause only some events to be sent to Sentry
 - [Project permissions](/product/accounts/membership/#restricting-access) may mean you do not have access to transactions in another project

docs/product/performance/retention-priorities/index.mdx → docs/organization/dynamic-sampling/index.mdx

@@ -1,18 +1,54 @@
 ---
-title: Retention Priorities
-sidebar_order: 130
-description: "Learn how Sentry determines retention priorities and how to update them."
+title: Dynamic Sampling
+sidebar_order: 30
+description: "Learn how to make your billing quota go farther with Sentry's Dynamic Sampling."
 ---
 
+## Overview
+
+High-volume projects that generate many events can quickly consume a large portion of your billing quota, leaving less room for other projects and decreasing visibility across them.
+
+With high-volume projects, you'll often see many similar events, which can be redundant and less helpful for debugging. But with Dynamic Sampling, you can maximize your quota by adjusting sample rates based on each project’s event volume. The sample rate is a percentage from 0% (no events passed) to 100% (all events passed), that can be tailored to each project’s needs.
+
+When you use Dynamic Sampling, projects in your organization are sampled based on their recent event volumes. High-volume projects are sampled at lower rates while lower-volume projects are sampled at higher rates or not sampled at all, based on your recent event data. This makes it possible for each project to retain a meaningful set of key events, improving visibility into all projects regardless of their size.
+
+![The dynamic sampling mode and target sample rate setting.](./img/mode-and-target-sample-rate.png)
+
+## Modes
+
+You can choose between two Dynamic Sampling modes for your organization: manual or automatic.
+
+    * **`automatic`** (default): In automatic mode, the sample rate for each project is set automatically based on relative project volume, so events fit within your organization’s billing quota. This boosts visibility into lower-volume projects. To account for any changes in event volume, sample rates are recalibrated on a regular basis. Automatic mode overrides any manually-set project sample rates. 
+
+    * **`manual`**: If you want to set the exact sample rate for each project in your organization yourself, choose manual mode. Note, that in this mode, there is no automatic recalibration.
+
+
+[]: # (TODO: Rename AM3 with the actual user-facing name.)
+
 <Note>
 
-Retention priorities are only available on the latest version of our plans, starting from 1M reserved transactions. Anyone in your org with owner or billing-level permissions can update your plan by going to Settings > Subscription, and clicking the "Manage Subscription" button.
+Please note that these Dynamic Sampling modes are only available for customers on the AM3 platform.
 
 </Note>
 
-While storing all your data makes sense at relatively low volumes, as your application scales, storing a raw copy of all your data has diminishing returns. When data reaches high volumes, Sentry begins to automatically prioritize retaining certain transactions over others with server-side data retention strategies called retention priorities.
 
-It's important to note that even when we begin to only store the most valuable data based on retention priorities, the [performance metrics](/product/performance/metrics/) you see are still based on **all** the events you send to Sentry. This ensures that you get a full and complete view of your application's health.
+## Differences to Sampling in the Sentry SDKs
+
+Dynamic Sampling is different from the sampling that you can configure in the Sentry SDKs. The SDK sampling rate is applied before events are sent to Sentry, while Dynamic Sampling is applied after events are received by Sentry. This means that Dynamic Sampling can be used to adjust the sample rate for events that have already been sent to Sentry and only take into account the volume of events that have been received by Sentry.
+
+Also in contrast to the Dynamic Sampling, the SDK sample rate is never dynamically adjusted.
+
+## Dynamic Sampling Priorities
+
+<Note>
+
+Dynamic Sampling priorities are only available on the latest version of our plans, starting from 1M reserved transactions. Anyone in your org with owner or billing-level permissions can update your plan by going to Settings > Subscription, and clicking the "Manage Subscription" button.
+
+</Note>
+
+While storing all your data makes sense at relatively low volumes, as your application scales, storing a raw copy of all your data has diminishing returns. When data reaches high volumes, Sentry begins to automatically prioritize retaining certain transactions over others with server-side data sampling strategies called dynamic sampling priorities.
+
+It's important to note that even when we begin to only store the most valuable data based on dynamic sampling priorities, the [performance metrics](/product/performance/metrics/) you see are still based on **all** the events you send to Sentry. This ensures that you get a full and complete view of your application's health.
 
 ## Prerequisites
 
@@ -32,8 +68,6 @@ It's important to note that even when we begin to only store the most valuable d
   - .NET: 3.22.0 or later
   - Go: 0.16.0 or later
 
-## Retention Priorities
-
 Below is a list of the transactions we prioritize and deprioritize. They are enabled by default, but can be updated on a per-project basis to better fit your organization's needs.
 
 ### Prioritized Transactions
@@ -42,7 +76,7 @@ Sentry automatically prioritizes and retains the following types of transactions
 
 #### Latest Release
 
-Latest releases are a retention priority because when you create a new release, we assume you'll want to have more visibility during the early adoption phase, which improves your ability to catch new issues as your release is gaining traction.
+Latest releases are a dynamic sampling priority because when you create a new release, we assume you'll want to have more visibility during the early adoption phase, which improves your ability to catch new issues as your release is gaining traction.
 Because you may want to deploy the same release in different environments, we'll also take your environment into account and prioritize those transactions.
 
 #### Dev Environments
@@ -59,7 +93,7 @@ Since dev environments usually generate a small number of transactions as compar
 
 <Note>
 
-You won't be able to disable the Low Volume Projects retention priority because it's set on an organization-wide level, not on a per-project basis.
+You won't be able to disable the Low Volume Projects dynamic sampling priority because it's set on an organization-wide level, not on a per-project basis.
 
 </Note>
 
@@ -72,7 +106,7 @@ We prioritize low-volume transactions for the same reason we prioritize low-volu
 
 ### Investigation Mode
 
-Our automated retention priorities work well in a generic manner to collect a baseline of samples because they prioritize retaining data that is valuable for any customer at any given time. However, there are certain scenarios, such as investigating a particular issue, when very specific data becomes temporarily more important. In such cases, sometimes the automated sampling priorities do not provide enough samples, so you may want to create investigation rules.
+Our automated dynamic sampling priorities work well in a generic manner to collect a baseline of samples because they prioritize retaining data that is valuable for any customer at any given time. However, there are certain scenarios, such as investigating a particular issue, when very specific data becomes temporarily more important. In such cases, sometimes the automated sampling priorities do not provide enough samples, so you may want to create investigation rules.
 
 Investigation rules are sampling rules that can be created through the Sentry UI to temporarily boost the number of transactions collected for a particular scenario (for example, transactions with specific tag values). These rules can be created to retain more samples when too few (less than 5) are available. Once created, a rule will be active for up to 48 hours or until 100 samples are collected. You'll be notified via email when enough transactions have been collected.
 
@@ -120,9 +154,9 @@ We deprioritize health check type transactions because while they're important f
 - `*/readyz`
 - `*/ping`
 
-### How to Change Retention Priorities
+### How to Change Dynamic Sampling Priorities
 
-To make changes to a project's retention priorities in Sentry, go to **Settings > Projects**, select the project you're interested in, then scroll down to "Performance" in the "PROCESSING" section and make any updates under "RETENTION PRIORITIES" using the toggles. Each of your projects can have an individual set of retention priorities.
+To make changes to a project's dynamic sampling priorities in Sentry, go to **Settings > Projects**, select the project you're interested in, then scroll down to "Performance" in the "PROCESSING" section and make any updates under "DYNAMIC SAMPLING PRIORITIES" using the toggles. Each of your projects can have an individual set of dynamic sampling priorities.
 
 <Arcade src="https://demo.arcade.software/bEv0SO2UEmqbVJVok99o?embed" />
 

docs/organization/early-adopter-features/index.mdx

@@ -20,6 +20,6 @@ Limitations:
 - [Issue Views](/product/issues/issue-views/)
 - [Issue Status](/product/issues/states-triage/) tags
 - [Span Summary](/product/performance/transaction-summary/#span-summary)
-- [Investigation Mode](/product/performance/retention-priorities/#investigation-mode) for retention priorities in Tracing
+- [Investigation Mode](/organization/dynamic-sampling/#investigation-mode) for sampling priorities in Tracing
 - [Uptime Monitoring](/product/alerts/uptime-monitoring/)
 - [Dynamic Alerts](/product/alerts/create-alerts/metric-alert-config/#dynamic-alerts)

docs/product/explore/discover-queries/query-builder.mdx

@@ -64,7 +64,7 @@ Click on any of these sections to further refine your search. For example, click
 
 When performing searches on transaction events, based on your search criteria
 and sample rate, the events available may be limited because Discover uses
-sampled data only. Learn more by reading about [our retention priorities](/product/performance/retention-priorities/).
+sampled data only. Learn more by reading about [our sampling priorities](/organization/dynamic-sampling/).
 
 </Note>
 

docs/product/explore/traces/index.mdx

@@ -45,7 +45,7 @@ For a list of built-in key fields used in Sentry, check out our [Searchable Prop
 
 <Note>
 
-Trace Explorer uses sampled data. Your search results may be limited based on sampling rates and retention policies. Learn more about [retention priorities](/product/performance/retention-priorities/).
+Trace Explorer uses sampled data. Your search results may be limited based on sampling rates and retention policies. Learn more about [sampling priorities](/organization/dynamic-sampling/).
 
 </Note>