Merge branch 'master' into denrase/flutter-android-16kb-page-size

Author: denrase

.pre-commit-config.yaml

@@ -13,7 +13,7 @@ repos:
       - id: detect-private-key
         exclude: |
           (?x)^(
-              develop-docs/application-architecture/config.mdx|
+              develop-docs/api-server/config.mdx|
               develop-docs/integrations/github.mdx|
               develop-docs/self-hosted/sso.mdx
           )$

develop-docs/application-architecture/config.mdx renamed to develop-docs/api-server/config.mdx

@@ -1,6 +1,6 @@
 ---
 title: Configuration
-sidebar_order: 30
+sidebar_order: 10
 ---
 
 This document describes configuration available to the Sentry server itself.

develop-docs/application-architecture/dynamic-sampling/extrapolation.mdx

@@ -72,6 +72,12 @@ In new product surfaces, the question of whether to use extrapolated vs. non-ext
 - Does the user care more about a truthful estimate of the aggregate data or about the actual events that happened?
     - Some scenarios, like visualizing metrics over time, are based on aggregates, whereas a case of debugging a specific user's problem hinges on actually seeing the specific events. The best mode depends on the intended usage of the product.
 
+### Switching to Sample Mode
+Sample mode is designed to help users investigate specific events. Here are two common scenarios where it makes the most sense:
+
+1. **When both sample rate and event volume are low**: Extrapolation becomes less reliable in these cases. You can either increase your sample rate to improve accuracy, or switch to sample mode to examine the actual events - both are valid approaches depending on the user's needs.
+2. **When you have a high sample rate but still see low event volumes**: In this case, increasing the sample rate won't help capture more data, and sample mode will give you a clearer picture of the events you do have.
+
 ### Opting Out of Extrapolation
 Users may want to opt out of extrapolation for different reasons. It is always possible to set the sample rate for specific events to 100% and therefore send all data to Sentry, implicitly opting out of extrapolation and behaving in the same way as sample mode. Depending on their configuration, users may need to change Dynamic Sampling settings or their SDK's traces sampler callback for this.
 

develop-docs/application-architecture/dynamic-sampling/fidelity-and-biases.mdx

@@ -6,29 +6,38 @@ sidebar_order: 1
 
 ![Sequencing](./images/sequencing.png)
 
+
+<Alert title="💡 Note" level="info">
+
+Dynamic Sampling currently operates on either spans or transactions to measure data throughput. This is controlled by the feature flag `organizations:dynamic-sampling-spans` and usually set to what the organization's subscription is metered by. In development, this currently defaults to transactions.
+The logic between the two data categories is identical, so most of this documentation is kept at a generic level and important differences are pointed out explicitly.
+
+</Alert>
+
+
 ## Sequencing
 
 Dynamic Sampling occurs at the edge of our ingestion pipeline, precisely in [Relay](https://github.com/getsentry/relay).
 
-When transaction events arrive, in a simplified model, they go through the following steps (some of which won't apply if you self-host Sentry):
+When events arrive, in a simplified model, they go through the following steps:
 
-1. **Inbound data filters**: every transaction runs through inbound data filters as configured in project settings, such as legacy browsers or denied releases. Transactions dropped here do not count for quota and are not included in “total transactions” data.
-2. **Quota enforcement**: Sentry charges for all further transactions sent in, before events are passed on to dynamic sampling.
-3. **Metrics extraction**: after passing quotas, Sentry extracts metrics from the total incoming transactions. These metrics provide granular numbers for the performance and frequency of every application transaction.
-4. **Dynamic Sampling**: based on an internal set of rules, Relay determines a sample rate for every incoming transaction event. A random number generator finally decides whether this payload should be kept or dropped.
-5. **Rate limiting**: transactions that are sampled by Dynamic Sampling will be stored and indexed. To protect the infrastructure, internal rate limits apply at this point. Under normal operation, this **rate limit is never reached** since dynamic sampling already reduces the volume of stored events.
+1. **Inbound data filters**: every event runs through inbound data filters as configured in project settings, such as legacy browsers or denied releases. Events dropped here are not counted towards quota and are not included in "total events" data.
+2. **Quota enforcement**: Sentry charges for all further events sent in, before they are passed on to dynamic sampling.
+3. **Metrics extraction**: after passing quotas, Sentry extracts metrics from the total incoming events. These metrics provide granular numbers for the performance and frequency of every event.
+4. **Dynamic Sampling**: based on an internal set of rules, Relay determines a sample rate for every incoming event. A random number generator finally decides whether a payload should be kept or dropped.
+5. **Rate limiting**: events that are sampled by Dynamic Sampling will be stored and indexed. To protect the infrastructure, internal rate limits apply at this point. Under normal operation, this **rate limit is never reached** since dynamic sampling already reduces the volume of events stored.
 
 <Alert title="💡 Example" level="info">
 
-A client is sending 1000 transactions per second to Sentry:
-1. 100 transactions per second are from old browsers and get dropped through an inbound data filter.
-2. The remaining 900 transactions per second show up as total transactions in Sentry.
-3. Their current overall sample rate is at 20%, which statistically samples 180 transactions per second.
-4. Since this is above the 100/s limit, about 80 transactions per second are randomly dropped, and the rest is stored.
+A client is sending 1000 events per second to Sentry:
+1. 100 events per second are from old browsers and get dropped through an inbound data filter.
+2. The remaining 900 events per second show up as total events in Sentry.
+3. Their current overall sample rate is at 20%, which statistically samples 180 events per second.
+4. Since this is above the 100/s limit, about 80 events per second are randomly dropped, and the rest is stored.
 
 </Alert>
 
-## Rate Limiting and Total Transactions
+## Rate Limiting and Total Events
 
 The ingestion pipeline has two kinds of rate limits that  behave differently compared to organizations without dynamic sampling:
 
@@ -37,49 +46,49 @@ The ingestion pipeline has two kinds of rate limits that  behave differently com
 
 <Alert title="✨️ Note" level="info">
 
-There is a dedicated rate limit for stored transactions after inbound filters and dynamic sampling. However, it does not affect total transactions since the fidelity decreases with higher total transaction volumes and this rate limit is not expected to trigger since Dynamic Sampling already reduces the stored transaction throughput.
+There is a dedicated rate limit for stored events after inbound filters and dynamic sampling. However, it does not affect total events since the fidelity decreases with higher total event volumes and this rate limit is not expected to trigger since Dynamic Sampling already reduces the stored event throughput.
 
 </Alert>
 
 ## Rate Limiting and Trace Completeness
 
-Dynamic sampling ensures complete traces by retaining all transactions associated with a trace if the head transaction is preserved.
+Dynamic sampling ensures complete traces by retaining all events associated with a trace if the head event is preserved.
 
-Despite dynamic sampling providing trace completeness, transactions or other items (errors, replays, ...) may still be missing from a trace when rate limiting drops one or more transactions. Rate limiting drops items without regard for the trace, making each decision independently and potentially resulting in broken traces.
+Despite dynamic sampling providing trace completeness, events or other items (errors, replays, ...) may still be missing from a trace when rate limiting drops one or more of them. Rate limiting drops items without regard for the trace, making each decision independently and potentially resulting in broken traces.
 
 <Alert title="💡 Example" level="info">
 
-For example, if there is a trace from `Project A` to `Project B` and `Project B` is subject to rate limiting or quota enforcement, transactions of `Project B` from the trace initiated by `Project A` are lost.
+For example, if there is a trace from `Project A` to `Project B` and `Project B` is subject to rate limiting or quota enforcement, events of `Project B` from the trace initiated by `Project A` are lost.
 
 </Alert>
 
 ## Client Side Sampling and Dynamic Sampling
 
-Clients have their own [traces sample rate](https://docs.sentry.io/platforms/javascript/performance/#configure-the-sample-rate). The client sample rate is a number in the range `[0.0, 1.0]` (from 0% to 100%) that controls **how many transactions arrive at Sentry**. While documentation will generally suggest a sample rate of `1.0`, for some use cases it might be better to reduce it.
+Clients have their own [traces sample rate](https://docs.sentry.io/platforms/javascript/tracing/#configure). The client sample rate is a number in the range `[0.0, 1.0]` (from 0% to 100%) that controls **how many events arrive at Sentry**. While documentation will generally suggest a sample rate of `1.0`, for some use cases it might be better to reduce it.
 
-Dynamic Sampling further reduces how many transactions get stored internally. **While many-to-most graphs and numbers in Sentry are based on total transactions**, accessing spans and tags requires stored transactions. The sample rates apply on top of each other.
+Dynamic Sampling further reduces how many events get stored internally. **While most graphs and numbers in Sentry are based on metrics**, accessing spans and tags requires stored events. The sample rates apply on top of each other.
 
-An example of client side sampling and Dynamic Sampling starting from 100k transactions which results in 15k stored transactions is shown below:
+An example of client side sampling and Dynamic Sampling starting from 100k events which results in 15k stored events is shown below:
 
 ![Client and Dynamic Sampling](./images/clientAndDynamicSampling.png)
 
 ## Total Transactions
 
-To collect unsampled information for “total” transactions in Performance, Alerts, and Dashboards, Relay extracts [metrics](https://getsentry.github.io/relay/relay_metrics/index.html) from transactions. In short, these metrics comprise:
+To collect unsampled information for “total” transactions in Performance, Alerts, and Dashboards, Relay extracts [metrics](https://getsentry.github.io/relay/relay_metrics/index.html) from spans and transactions. In short, these metrics comprise:
 
-- Counts and durations for all transactions.
+- Counts and durations for all events.
 - A distribution (histogram) for all measurements, most notably the web vitals.
 - The number of unique users (set).
 
 Each of these metrics can be filtered and grouped by a number of predefined tags, [implemented in Relay](https://github.com/getsentry/relay/blob/master/relay-server/src/metrics_extraction/transactions/types.rs#L142-L157).
 
-For more granular queries, **stored transaction events are needed**. _The purpose of dynamic sampling here is to ensure that enough representatives are always available._
+For more granular queries, **stored events are needed**. _The purpose of dynamic sampling here is to ensure that there are always sufficient representative sample events._
 
 <Alert title="💡 Example" level="info">
 
-If Sentry applies a 1% dynamic sample rate, you can still receive accurate TPM (transactions per minute) and web vital quantiles through total transaction data backed by metrics. There is also a listing of each of these numbers by the transaction.
+If Sentry applies a 1% dynamic sample rate, you can still receive accurate events per minute (SPM or TPM, depending on event type) and web vital quantiles through total event data backed by metrics. There is also a listing of each of these numbers by the transaction.
 
-When you go into transaction summary or Discover, you might want to now split the data by a custom tag you’ve added to your transactions. This granularity is not offered by metrics, so **these queries need to use stored transactions**.
+When you go into the trace explorer or Discover, you might want to now split the data by a custom tag you’ve added to your events. This granularity is not offered by metrics, so **these queries need to use stored events**.
 
 </Alert>
 

develop-docs/application-architecture/dynamic-sampling/the-big-picture.mdx

@@ -49,17 +49,20 @@ To align DSC propagation over all our SDKs, we defined a [unified propagation me
 All of the attributes in the table below are required (non-optional) in a sense, that when they are known to an SDK at the time an envelope with an event (transaction or error) is sent to Sentry, or at the time a baggage header is propagated, they must also be included in said envelope or baggage.
 
 At the moment, only `release`, `environment` and `transaction` are used by the product for dynamic sampling functionality.
-The rest of the context attributes, `trace_id`, `public_key`, and `sample_rate`, are used by Relay for internal decisions (like transaction sample rate smoothing).
+The rest of the context attributes, `trace_id`, `public_key`, `sampled` and `sample_rate`, are used by Relay for internal decisions and for extrapolation in the product.
+Additional entries such as `replay_id`, `org` and `sample_rand` are only using the DSC as a means of transport.
 
 | Attribute                   | Type   | Description                                                                                                                  | Example                              | Required Level                       |
 | --------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------ |
 | `trace_id`                  | string | The original trace ID as generated by the SDK. This must match the trace id of the submitted transaction item. [1]           | `771a43a4192642f0b136d5159a501700`   | strictly required [0]                |
 | `public_key`                | string | Public key from the DSN used by the SDK. [2]                                                                                 | `49d0f7386ad645858ae85020e393bef3`   | strictly required [0]                |
-| `sample_rate`               | string | The sample rate as defined by the user on the SDK. [3]                                                                       | `0.7`                                | strictly required [0]                |
-| `sampled`                   | string | `"true"` if the trace is sampled, `"false"` otherwise. This is set by the head of the trace.                                 | `true`                               | required                             |
+| `sample_rate`               | string | The sample rate as defined by the user on the SDK. [3] [4]                                                                   | `0.7`                                | strictly required [0]                |
+| `sample_rand`               | string | A random number generated at the start of a trace by the head of trace SDK. [4]                                              | `0.5`                                | required                             |
+| `sampled`                   | string | `"true"` if the trace is sampled, `"false"` otherwise. This is set by the head of the trace SDK. [4]                         | `true`                               | required                             |
 | `release`                   | string | The release name as specified in client options.                                                                             | `[email protected]`, `1.2.3`, `2025.4.107` | required                             |
 | `environment`               | string | The environment name as specified in client options.                                                                         | `production`, `staging`              | required                             |
 | `transaction`               | string | The transaction name set on the scope. **Only include** if name has [good quality](#note-on-good-quality-transaction-names). | `/login`, `myApp.myController.login` | required (if known and good quality) |
+| `org`                       | string | The org ID parsed from the DSN or received by a downstream SDK.                                                              | `1`                                  | required                             |
 | `user_segment` [DEPRECATED] | string | User segment as set by the user with `scope.set_user()`.                                                                     |                                      | deprecated                           |
 
 0: In any case, `trace_id`, `public_key`, and `sample_rate` should always be known to an SDK, so these values are strictly required.
@@ -70,6 +73,8 @@ The rest of the context attributes, `trace_id`, `public_key`, and `sample_rate`,
 
 3: This string should always be a number between (and including) 0 and 1 in a notation that is supported by the [JSON specification](https://www.json.org/json-en.html). If a `tracesSampler` callback was used for the sampling decision, its result should be used for `sample_rate` instead of the `tracesSampleRate` from `SentryOptions`. In case `tracesSampler` returns `True` it should be sent as `1.0`, `False` should be sent as `0.0`.
 
+4: These attributes must conform to the invariant `sample_rand < sample_rate <=> sampled`.
+
 <Alert level="warning">
 
 ### Note on good-quality transaction names
@@ -276,5 +281,4 @@ TODO - Add some sort of Q&A section on the following questions, after evaluating
 - Why must baggage be immutable before the second transaction has been started?
 - What are the consequences and impacts of the immutability of baggage on Dynamic Sampling UX?
 - Why can't we just make the decision for the whole trace in Relay after the trace is complete?
-- What is sample rate smoothing and how does it use `sample_rate` from the Dynamic Sampling Context?
 - What are the differences between Dynamic Sampling on traces vs. transactions?