Dynamic error sampling Python (#8314)

* Dynamic error sampling Python

* Apply suggestions from code review

Co-authored-by: Shana Matthews <shana.l.matthews@gmail.com>

* Remove extra closing parenthesis

* Added error-sampler to basic options

* Bullet points for valid values

* [getsentry/action-github-commit] Auto commit

---------

Co-authored-by: Shana Matthews <shana.l.matthews@gmail.com>
Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>

src/platform-includes/configuration/error-sampler/python.mdx

@@ -0,0 +1,20 @@
+```python
+import sentry_sdk
+
+def my_sampler(_, hint):
+    exception_sampler_values = {
+        MyException: 0.5,
+        MyIgnoredException: 0.0,  # or equivalently, False
+    }
+
+    try:
+        return exception_sampler_values[hint["exc_info"][0]]
+    except (IndexError, KeyError, TypeError):
+        return 1.0  # or equivalently, True
+
+sentry_sdk.init(
+    # ...
+
+    error_sampler=my_sampler,
+)
+```

src/platforms/common/configuration/options.mdx

@@ -192,6 +192,14 @@ Configures the sample rate for error events, in the range of `0.0` to `1.0`. The
 
 </ConfigKey>
 
+<ConfigKey name="error-sampler" supported={["python"]}>
+
+Dynamically configures the sample rate for error events on a per-event basis. This configuration option accepts a function, which takes two parameters (the `event` and the `hint`), and which returns a boolean (indicating whether the event should be sent to Sentry) or a floating-point number between 0.0 and 1.0, inclusive (where the number indicates the probability the event is sent to Sentry; the SDK will randomly decide whether to send the event with the given probability).
+
+If this configuration option is specified, the <PlatformIdentifier name="sample-rate" /> option is ignored.
+
+</ConfigKey>
+
 <ConfigKey name="max-breadcrumbs">
 
 This variable controls the total amount of breadcrumbs that should be captured. This defaults to `100`, but you can set this to any number. However, you should be aware that Sentry has a [maximum payload size](https://develop.sentry.dev/sdk/envelopes/#size-limits) and any events exceeding that payload size will be dropped.

src/platforms/common/configuration/sampling.mdx

@@ -41,6 +41,33 @@ Changing the error sample rate requires re-deployment. In addition, setting an S
 
 </Note>
 
+<PlatformSection supported={["python"]}>
+
+### 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" />, which it uses to inform the sampling decision.
+
+<Alert level="warning">
+
+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>
+
+</PlatformSection>
+
 <PlatformSection notSupported={["elixir", "javascript.electron", "perl"]}>
 
 ## Sampling Transaction Events