feat(python): Reintroduce Python span streaming docs

docs/platforms/python/configuration/filtering/index.mdx

@@ -68,7 +68,8 @@ When the SDK creates an event or breadcrumb for transmission, that transmission
 
 Hints are available in two places:
 
-1. <PlatformIdentifier name="before-send" /> / <PlatformIdentifier name="before-breadcrumb" />
+1. <PlatformIdentifier name="before-send" /> /
+   <PlatformIdentifier name="before-breadcrumb" />
 2. `eventProcessors`
 
 Event and breadcrumb `hints` are objects containing various information used to put together an event or a breadcrumb. Typically `hints` hold the original exception so that additional data can be extracted or grouping can be affected.
@@ -101,24 +102,95 @@ When a string or a non-error object is raised, Sentry creates a synthetic except
 
 <PlatformContent includePath="configuration/decluttering" />
 
-## Filtering Transaction Events
+## Filtering Transactions and Spans
 
-To prevent certain transactions from being reported to Sentry, use the <PlatformIdentifier name="traces-sampler" /> or <PlatformIdentifier name="before-send-transaction" /> configuration option, which allows you to provide a function to evaluate the current transaction and drop it if it's not one you want.
+To prevent certain transactions (or spans in <PlatformLink to="/tracing/streamed-spans">stream mode</PlatformLink>) from being reported to Sentry, use the <PlatformIdentifier name="traces-sampler" />, <PlatformIdentifier name="before-send-transaction" /> (for transaction mode), or <PlatformIdentifier name="ignore-spans" /> (for stream mode) configuration options. These allow you to provide a function to evaluate the current transaction or span and drop it if it's not one you want.
+
+You can also use <PlatformIdentifier name="before-send-transaction" /> (for transaction mode) or <PlatformIdentifier name="before-send-span" /> (for stream mode) to modify transaction/span data.
 
 ### Using <PlatformIdentifier name="traces-sampler" />
 
-**Note:** The <PlatformIdentifier name="traces-sampler" /> and <PlatformIdentifier name="traces-sample-rate" /> config options are mutually exclusive. If you define a <PlatformIdentifier name="traces-sampler" /> to filter out certain transactions, you must also handle the case of non-filtered transactions by returning the rate at which you'd like them sampled.
+**Note:** The <PlatformIdentifier name="traces-sampler" /> and <PlatformIdentifier name="traces-sample-rate" /> config options are mutually exclusive. If you define a <PlatformIdentifier name="traces-sampler" /> to filter out certain transactions/service spans, you must also handle the case of non-filtered transactions/service spans by returning the rate at which you'd like them sampled.
 
-In its simplest form, used just for filtering the transaction, it looks like this:
+In its simplest form, used just for filtering the transaction/service span, it looks like this:
 
 <PlatformContent includePath="performance/traces-sampler-as-filter" />
 
-It also allows you to sample different transactions at different rates.
+It also allows you to sample different transactions/service spans at different rates.
 
-If the transaction currently being processed has a parent transaction (from an upstream service calling this service), the parent (upstream) sampling decision will always be included in the sampling context data, so that your <PlatformIdentifier name="traces-sampler" /> can choose whether and when 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. See <PlatformLink to="/configuration/sampling/#inheritance">Inheriting the parent sampling decision</PlatformLink> to learn more.
+If the transaction or span currently being processed has a parent (from an upstream service calling this service), the parent's (upstream) sampling decision will always be included in the sampling context data, so that your <PlatformIdentifier name="traces-sampler" /> can choose whether and when 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.
 
-Learn more about <PlatformLink to="/configuration/sampling/">configuring the sample rate</PlatformLink>.
+Learn more about <PlatformLink to="/tracing/configure-sampling/">configuring sampling</PlatformLink>.
 
 ### Using <PlatformIdentifier name="before-send-transaction" />
 
+<Alert>
+
+Not available in stream mode. Use <PlatformIdentifier name="before-send-span" /> instead.
+
+</Alert>
+
 <PlatformContent includePath="configuration/before-send-transaction" />
+
+### Using <PlatformIdentifier name="before-send-span" />
+
+<Alert>
+
+Only available in stream mode.
+
+</Alert>
+
+Use the <PlatformIdentifier name="before-send-span" /> configuration option, which lets you provide a function to modify a span.
+This function is called for the service span and all child spans.
+
+If you want to drop the service span, including its child spans, use [`ignore_spans`](#using-ignore-spans).
+
+<PlatformContent includePath="configuration/before-send-span" />
+
+See <PlatformLink to="/configuration/options/#before_send_span">`before_send_span`</PlatformLink> for details.
+
+### Using <PlatformIdentifier name="ignore-spans" />
+
+<Alert>
+
+Only available in stream mode.
+
+</Alert>
+
+You can use the <PlatformIdentifier name="ignore-spans" /> option to filter out spans that match a certain pattern by providing a list of strings, compiled regular expressions, or dictionaries. When using strings, a span name containing the string will be filtered out. For exact or more complex pattern matching, use compiled regular expressions instead.
+
+You can also provide a dictionary with `name` and/or `attributes` keys to match on multiple conditions. At least one key must be provided.
+
+```python
+import re
+import sentry_sdk
+
+sentry_sdk.init(
+    trace_lifecycle="stream",
+    ignore_spans=[
+        # String match against span name
+        "/health",
+
+        # Regex match against span name
+        re.compile(r"/flow/.*"),
+
+        # Match by attributes (all must match)
+        {
+            "attributes": {
+                "service.id": "15def9a",
+                "flow.pipeline": "legacy",
+            }
+        },
+
+        # Match by name and attributes
+        {
+            "name": re.compile(r"/flow/.*"),
+            "attributes": {
+                "service.id": re.compile(r".*\.facade"),
+            },
+        },
+    ],
+)
+```
+
+See <PlatformLink to="/configuration/options/#ignore_spans">`ignore_spans`</PlatformLink> for details.

docs/platforms/python/configuration/options.mdx

@@ -252,6 +252,43 @@ This function is called with a transaction event object, and can return a modifi
 
 </SdkOption>
 
+<SdkOption name="before_send_span" type='function' defaultValue='None' availableSince='2.67.0'>
+
+<Alert>
+
+Only available in <PlatformLink to="/tracing/streamed-spans">stream mode</PlatformLink>.
+
+</Alert>
+
+This function is called with a span event object and can return a modified span object. Use it, for example, to manually strip PII from spans or filter data from spans before they're sent to Sentry.
+
+Note that `before_send_span` can only modify span data, meaning you cannot use it to drop spans. Use [`ignore_spans`](#ignore_spans) to drop spans.
+
+<Expandable title="Examples">
+
+```python {tabTitle:Stream Mode}
+import sentry_sdk
+
+def before_send_span(span, hint):
+    # Runs once per span, as it's flushed.
+    # Only attributes set at span-creation time are available here.
+    span["attributes"].update({
+        "component_version": "2.0.0",
+        "deployment_stage": "production",
+    })
+    return span
+
+sentry_sdk.init(
+    # ...
+    trace_lifecycle="stream",
+    before_send_span=before_send_span,
+)
+```
+
+</Expandable>
+
+</SdkOption>
+
 <SdkOption name="before_breadcrumb" type='function' defaultValue='None'>
 
 This function is called with a breadcrumb object before the breadcrumb is added to the scope. When nothing is returned from the function, the breadcrumb is dropped. To pass the breadcrumb through, return the first argument, which contains the breadcrumb object.
@@ -356,7 +393,7 @@ sentry_sdk.init(
 
 <SdkOption name="traces_sample_rate" type='float' defaultValue='None'>
 
-A number between `0` and `1`, controlling the percentage chance a given transaction will be sent to Sentry. (`0` represents 0% while `1` represents 100%.) Applies equally to all transactions created in the app. Either this or `traces_sampler` must be defined to enable tracing.
+A number between `0` and `1`, controlling the percentage chance a given transaction (or service span in stream mode) will be sent to Sentry. (`0` represents 0% while `1` represents 100%.) Applies equally to all transactions and spans created in the app. Either this or `traces_sampler` must be defined to enable tracing.
 
 If `traces_sample_rate` is `0`, this means that no new traces will be created. However, if you have another service (for example a JS frontend) that makes requests to your service that include trace information, those traces will be continued and thus transactions will be sent to Sentry.
 
@@ -366,6 +403,68 @@ If you want to disable all tracing you need to set `traces_sample_rate=None`. In
 
 <PlatformContent includePath="/performance/traces-sampler-config-option" />
 
+<SdkOption name="trace_lifecycle" type='string' defaultValue='"static"' availableSince='2.62.0'>
+
+Controls how spans are sent to Sentry:
+
+- In transaction mode (`"static"`, the default), all spans are collected in memory and sent to Sentry as a single transaction once the root span ends.
+- In <PlatformLink to="/tracing/streamed-spans/">stream mode</PlatformLink> (`"stream"`), spans are sent in batches as they finish.
+
+</SdkOption>
+
+<SdkOption name="ignore_spans" type='list[str | Pattern | dict]' defaultValue='[]' availableSince='2.62.0'>
+
+<Alert>
+
+Only available in <PlatformLink to="/tracing/streamed-spans">stream mode</PlatformLink>.
+
+</Alert>
+
+A list of strings, compiled regular expressions, or dictionaries describing spans that shouldn't be sent to Sentry. When using strings, a span name containing the string will be filtered out. For exact or more complex pattern matching, use compiled regular expressions instead. You can also provide a dictionary with `name` and/or `attributes` keys to match on multiple conditions. At least one key must be provided.
+
+If the dropped span is a service span, its children are dropped too. If it's a child span, only that span is dropped and its children are reparented to the nearest ancestor.
+By default, no spans are ignored.
+
+`ignore_spans` is evaluated at span start, so only the span name and attributes available at that point are taken into account. Any name updates or additional attributes added while the span is active won't influence whether the span is dropped.
+
+<Expandable title="Examples">
+
+```python
+import re
+import sentry_sdk
+
+sentry_sdk.init(
+    trace_lifecycle="stream",
+    ignore_spans=[
+        # String match against span name
+        "/health",
+
+        # Regex match against span name
+        re.compile(r"/flow/.*"),
+
+        # Match by attributes (all must match)
+        {
+            "attributes": {
+                "service.id": "15def9a",
+                "flow.pipeline": "legacy",
+            }
+        },
+
+        # Match by name and attributes
+        {
+            "name": re.compile(r"/flow/.*"),
+            "attributes": {
+                "service.id": re.compile(r".*\.facade"),
+            },
+        },
+    ],
+)
+```
+
+</Expandable>
+
+</SdkOption>
+
 <SdkOption name="trace_propagation_targets" type='list' defaultValue="['.*']">
 
 An optional property that controls which downstream services receive tracing data, in the form of a `sentry-trace` and a `baggage` header attached to any outgoing HTTP requests.

docs/platforms/python/data-management/sensitive-data/index.mdx

@@ -45,9 +45,9 @@ You can use the <PlatformIdentifier name="event-scrubber" /> configuration param
 
 <PlatformContent includePath="configuration/event-scrubber" />
 
-### <PlatformIdentifier name="before-send" /> & <PlatformIdentifier name="before-send-transaction" />
+### <PlatformIdentifier name="before-send" />, <PlatformIdentifier name="before-send-transaction" />, & <PlatformIdentifier name="before-send-span" />
 
-The SDK provides a <PlatformIdentifier name="before-send" /> hook, which is invoked before an error or message event is sent and can be used to modify event data to remove sensitive information. The SDK also provide a <PlatformIdentifier name="before-send-transaction" /> hook which does the same thing for transactions. We recommend using <PlatformIdentifier name="before-send" /> and <PlatformIdentifier name="before-send-transaction" /> in the SDK to **scrub any data before it is sent**, to ensure that sensitive data never leaves the local environment.
+The SDK provides a <PlatformIdentifier name="before-send" /> hook, which is invoked before an error or message event is sent and can be used to modify event data to remove sensitive information. The SDK also provides a <PlatformIdentifier name="before-send-transaction" /> hook, that does the same thing for transactions, and a <PlatformIdentifier name="before-send-span" /> hook, that does the same thing for spans in <PlatformLink to="/tracing/streamed-spans/">stream mode</PlatformLink>. We recommend using these hooks in the SDK to **scrub any data before it is sent**, to ensure that sensitive data never leaves the local environment.
 
 <PlatformContent includePath="configuration/before-send/" />
 

docs/platforms/python/profiling/index.mdx

@@ -16,7 +16,10 @@ With [profiling](/product/profiling/), Sentry tracks your software's performance
 
 Continuous profiling is available starting in SDK version `2.24.1`.
 
-<PlatformLink to="/profiling/#enable-transaction-based-profiling">Transaction-based profiling</PlatformLink> is available starting in SDK version `1.18.0`.
+<PlatformLink to="/profiling/#enable-transaction-based-profiling">
+  Transaction-based profiling
+</PlatformLink>
+is available starting in SDK version `1.18.0`.
 
 </Alert>
 
@@ -92,6 +95,7 @@ Continuous profiling was experimental in SDK versions prior to `2.24.1` and will
 <Alert>
 
 Transaction-based profiling is available starting in SDK version `1.18.0`.
+It's not available in <PlatformLink to="/tracing/streamed-spans">stream mode</PlatformLink>. Use continuous profiling instead.
 
 </Alert>
 

docs/platforms/python/sampling.mdx

@@ -42,6 +42,12 @@ You can define at most one of the <PlatformIdentifier name="error-sampler" /> an
 
 ## Sampling Transaction Events
 
+<Alert level="warning" title="Using stream mode?">
+
+If you're using <PlatformLink to="/tracing/streamed-spans">stream mode</PlatformLink>, refer to our <PlatformLink to="/tracing/configure-sampling/">Configure Sampling</PlatformLink> guide for setup instructions.
+
+</Alert>
+
 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.
@@ -58,8 +64,8 @@ The Sentry SDKs have two configuration options to control the volume of transact
    - 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
+   - <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.
@@ -105,7 +111,6 @@ sentry_sdk.start_transaction(
 )
 ```
 
-
 ## 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.