feat(python): Update the Configuration > Sampling page for Python SDK 3.0 (#14275)

We've made some changes to sampling in the upcoming 3.0 version of the
Python SDK. Creating a new 3.x version of the relevant pages.

Also removed some `python.<platform>.mdx` snippets because as far as I
can tell they can never be displayed anywhere (and they're now
outdated). They'd only display if the Python docs supported the
sub-SDK/platform view like e.g. JS does.

Once 3.x is actually out of alpha, we can make the `__v3.x` page the
default and make the base page into a `__v2.x`.


---------

Co-authored-by: Shannon Anahata <[email protected]>

Author: sentrivana

docs/platforms/python/configuration/sampling.mdx

@@ -83,7 +83,27 @@ The information contained in the <PlatformIdentifier name="sampling-context" />
 
 When using custom instrumentation to create a transaction, you can add data to the <PlatformIdentifier name="sampling-context" /> by passing it as an optional second argument to <PlatformIdentifier name="start-transaction" />. This is useful if there's data to which you want the sampler to have access but which you don't want to attach to the transaction as `tags` or `data`, such as information that's sensitive or that’s too large to send with the transaction. For example:
 
-<PlatformContent includePath="performance/custom-sampling-context" />
+```python
+sentry_sdk.start_transaction(
+    # kwargs passed to Transaction constructor - will be recorded on transaction
+    name="GET /search",
+    op="search",
+    data={
+        "query_params": {
+            "animal": "dog",
+            "type": "very good"
+        }
+    },
+    # `custom_sampling_context` - won't be recorded
+    custom_sampling_context={
+        # PII
+        "user_id": "12312012",
+        # too big to send
+        "search_results": { ... }
+    }
+)
+```
+
 
 ## Inheritance
 
@@ -105,7 +125,12 @@ If you're using a <PlatformIdentifier name="traces-sample-rate" /> rather than a
 
 If you know at transaction creation time whether or not you want the transaction sent to Sentry, you also have the option of passing a sampling decision directly to the transaction constructor (note, not in the <PlatformIdentifier name="custom-sampling-context" /> object). If you do that, the transaction won't be subject to the <PlatformIdentifier name="traces-sample-rate" />, nor will <PlatformIdentifier name="traces-sampler" /> be run, so you can count on the decision that's passed not to be overwritten.
 
-<PlatformContent includePath="performance/force-sampling-decision" />
+```python
+sentry_sdk.start_transaction(
+    name="GET /search",
+    sampled=True
+)
+```
 
 ## Precedence
 

docs/platforms/python/configuration/sampling__v3.x.mdx

@@ -0,0 +1,127 @@
+---
+title: Sampling
+description: "Learn how to configure the volume of error and transaction events sent to Sentry."
+sidebar_order: 60
+---
+
+Adding Sentry to your app gives you a great deal of valuable information about errors and performance you wouldn't otherwise get. And lots of information is good -- as long as it's the right information, at a reasonable volume.
+
+## Sampling Error Events
+
+To send a representative sample of your errors to Sentry, set the <PlatformIdentifier name="sample-rate" /> option in your SDK configuration to a number between `0.0` (0% of errors sent) and `1.0` (100% of errors sent). This is a static rate, which will apply equally to all errors. For example, to sample 25% of your errors:
+
+<PlatformContent includePath="configuration/sample-rate" />
+
+The error sample rate defaults to `1.0`, meaning all errors are sent to Sentry.
+
+Changing the error sample rate requires re-deployment. In addition, setting an SDK sample rate limits visibility into the source of events. Setting a [rate limit](/pricing/quotas/manage-event-stream-guide/#rate-limiting) for your project (which only drops events when volume is high) may better suit your needs.
+
+### Dynamically Sampling Error Events
+
+To sample error events dynamically, set the <PlatformIdentifier name="error-sampler" /> to a function that returns the desired sample rate for the event. The <PlatformIdentifier name="error-sampler" /> takes two arguments, <PlatformIdentifier name="event" /> and <PlatformIdentifier name="hint" />. `event` is the [Event](https://github.com/getsentry/sentry-python/blob/master/sentry_sdk/_types.py) that will be sent to Sentry, `hint` includes Python's [sys.exc_info()](https://docs.python.org/3/library/sys.html#sys.exc_info) information in `hint["exc_info"]`.
+
+<Alert>
+
+Your <PlatformIdentifier name="error-sampler" /> function **must return a valid value**. A valid value is either:
+
+- A **floating-point number** between `0.0` and `1.0` (inclusive) indicating the probability an error gets sampled, **or**
+- A **boolean** indicating whether or not to sample the error.
+
+</Alert>
+
+One potential use case for the <PlatformIdentifier name="error-sampler" /> is to apply different sample rates for different exception types. For instance, if you would like to sample some exception called `MyException` at 50%, discard all events of another exception called `MyIgnoredException`, and sample all other exception types at 100%, you could use the following code when initializing the SDK:
+
+<PlatformContent includePath="configuration/error-sampler" />
+
+<Alert>
+
+You can define at most one of the <PlatformIdentifier name="error-sampler" /> and the <PlatformIdentifier name="sample-rate" />. If both are set, the <PlatformIdentifier name="error-sampler" /> will control sampling, and the <PlatformIdentifier name="sample-rate" /> will be ignored.
+
+</Alert>
+
+## Sampling Transaction Events
+
+We recommend sampling your transactions for two reasons:
+
+1. 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.
+2. Enabling sampling allows you to better manage the number of events sent to Sentry, so you can tailor your volume to your organization's needs.
+
+Choose a sampling rate with the goal of finding a balance between performance and volume concerns with data accuracy. You don't want to collect _too_ much data, but you want to collect sufficient data from which to draw meaningful conclusions. If you’re not sure what rate to choose, start with a low value and gradually increase it as you learn more about your traffic patterns and volume.
+
+## Configuring the Transaction Sample Rate
+
+The Sentry SDKs have two configuration options to control the volume of transactions sent to Sentry, allowing you to take a representative sample:
+
+1. Uniform sample rate (<PlatformIdentifier name="traces-sample-rate" />):
+   - Provides an even cross-section of transactions, no matter where in your app or under what circumstances they occur.
+   - Uses default [inheritance](#inheritance) and [precedence](#precedence) behavior
+2. Sampling function (<PlatformIdentifier name="traces-sampler" />) which:
+   - Samples different transactions at different rates
+   - <PlatformLink to="/configuration/filtering/">Filters</PlatformLink> out some
+     transactions entirely
+   - Modifies default [precedence](#precedence) and [inheritance](#inheritance) behavior
+
+By default, none of these options are set, meaning no transactions will be sent to Sentry. You must set either one of the options to start sending transactions.
+
+### Setting a Uniform Sample Rate
+
+<PlatformContent includePath="performance/uniform-sample-rate" />
+
+### Setting a Sampling Function
+
+<PlatformContent includePath="performance/sampling-function-intro" />
+
+## Sampling Context Data
+
+### Default Sampling Context Data
+
+The information contained in the <PlatformIdentifier name="sampling-context" /> object passed to the <PlatformIdentifier name="traces-sampler" /> when a transaction is created varies by integration.
+
+<PlatformContent includePath="performance/default-sampling-context" />
+
+### Custom Sampling Context Data
+
+When using custom instrumentation to create a transaction, you can add data to the <PlatformIdentifier name="sampling-context" /> by providing additional `attributes` to <PlatformIdentifier name="start-span" />.
+
+<PlatformContent includePath="performance/custom-sampling-context" />
+
+All span attributes provided at span start are accessible via the <PlatformIdentifier name="sampling-context" /> and will also ultimately be sent to Sentry. If you want to exclude an attribute, you can filter it out in a <PlatformLink to="/configuration/filtering">`before_send`</PlatformLink>.
+
+## Inheritance
+
+Whatever a transaction's sampling decision, that decision will be passed to its child spans and from there to any transactions they subsequently cause in other services.
+
+(See <PlatformLink to="/tracing/trace-propagation/">Distributed Tracing</PlatformLink> for more about how that propagation is done.)
+
+If the transaction currently being created is one of those subsequent transactions (in other words, if it has a parent transaction), the upstream (parent) sampling decision will be included in the sampling context data. Your <PlatformIdentifier name="traces-sampler" /> can use this information to choose whether to inherit that decision. In most cases, inheritance is the right choice, to avoid breaking distributed traces. A broken trace will not include all your services.
+
+<PlatformContent includePath="performance/always-inherit-sampling-decision">
+
+In some SDKs, for convenience, the <PlatformIdentifier name="traces-sampler" /> function can return a boolean, so that a parent's decision can be returned directly if that's the desired behavior.
+
+</PlatformContent>
+
+If you're using a <PlatformIdentifier name="traces-sample-rate" /> rather than a <PlatformIdentifier name="traces-sampler" />, the decision will always be inherited. The provided <PlatformIdentifier name="traces-sample-rate" /> will only be used to generate a sample rate if there is no sampling decision coming in from upstream.
+
+## Forcing a Sampling Decision
+
+If you know at span creation time whether or not you want the transaction sent to Sentry, you also have the option of passing a sampling decision directly in the `start_span` API. If you do that, the transaction won't be subject to the <PlatformIdentifier name="traces-sample-rate" />, nor will <PlatformIdentifier name="traces-sampler" /> be run, so you can count on the decision that's passed not to be overwritten.
+
+<PlatformContent includePath="performance/force-sampling-decision" />
+
+## Precedence
+
+There are multiple ways for a transaction to end up with a sampling decision.
+
+- Random sampling according to a static sample rate set in <PlatformIdentifier name="traces-sample-rate" />
+- Random sampling according to a sample function rate returned by <PlatformIdentifier name="traces-sampler" />
+- Absolute decision (100% chance or 0% chance) returned by <PlatformIdentifier name="traces-sampler" />
+- If the transaction has a parent, inheriting its parent's sampling decision
+- Absolute decision passed to <PlatformIdentifier name="start-span" />
+
+When there's the potential for more than one of these to come into play, the following precedence rules apply:
+
+1. If a sampling decision is passed to <PlatformIdentifier name="start-transaction" />, that decision will be used, overriding everything else.
+2. If <PlatformIdentifier name="traces-sampler" /> is defined, its decision will be used. It can choose to keep or ignore any parent sampling decision, use the sampling context data to make its own decision, or choose a sample rate for the transaction. We advise against overriding the parent sampling decision because it will break distributed traces.
+3. If <PlatformIdentifier name="traces-sampler" /> is not defined, but there's a parent sampling decision, the parent sampling decision will be used.
+4. If <PlatformIdentifier name="traces-sampler" /> is not defined and there's no parent sampling decision, <PlatformIdentifier name="traces-sample-rate" /> will be used.

docs/platforms/python/profiling/index.mdx

@@ -115,7 +115,7 @@ sentry_sdk.init(
     # To set a uniform sample rate
     # Set profiles_sample_rate to 1.0 to profile 100%
     # of sampled transactions.
-    # We recommend adjusting this value in production,
+    # We recommend adjusting this value in production.
     profiles_sample_rate=1.0,
     # Alternatively, to control sampling dynamically
     profiles_sampler=profiles_sampler

platform-includes/performance/custom-sampling-context/python.mdx

@@ -1,20 +1,20 @@
 ```python
-sentry_sdk.start_transaction(
-    # kwargs passed to Transaction constructor - will be recorded on transaction
+sentry_sdk.start_span(
     name="GET /search",
     op="search",
     data={
-      "query_params": {
-        "animal": "dog",
-        "type": "very good"
-      }
+        "query_params": {
+            "animal": "dog",
+            "type": "very good"
+        }
     },
-    # `custom_sampling_context` - won't be recorded
-    custom_sampling_context={
-        # PII
+    # Attributes defined at root span (transaction) start will be accessible in traces_sampler
+    # and they will be sent to Sentry unless filtered out manually.
+    # Note that these can only be primitive types or a list of a single primitive
+    # type.
+    attributes={
         "user_id": "12312012",
-        # too big to send
-        "search_results": { ... }
+        "foo": "bar",
     }
-);
+)
 ```

platform-includes/performance/default-sampling-context-platform/python.mdx

@@ -1,12 +1,12 @@
-For Python-based SDKs, it includes at least the following:
+For the Python SDK, it includes at least the following:
 
 ```python
 {
-  "transaction_context": {
-    "name": <string>  # transaction title at creation time
-    "op": <string>  # short description of transaction type, like "http.request"
-  },
-  "parent_sampled": <bool>  # if this transaction has a parent, its sampling decision
-  ...  # custom context as passed to `start_transaction`
+    "transaction_context": {
+        "name": <string>  # transaction title at creation time
+        "op": <string>  # short description of transaction type, like "http.request"
+    },
+    "parent_sampled": <bool>  # if this transaction has a parent, its sampling decision
+    ...  # other attributes as passed to `start_span`
 }
 ```