feat(wsgi,asgi): Introduce substitute values for filtered fields in span-streaming mode (#6178)

In the legacy (event-based) pipeline, filtered/removed values in request
data are represented as `AnnotatedValue` objects — wrappers that carry
metadata (`rem` remarks) consumed by Relay during ingestion. In
span-streaming mode, request attributes are plain strings sent directly
on spans, so `AnnotatedValue` is not appropriate there.

Previously, `_filter_headers` had a `use_annotated_value: bool`
parameter that callers set to `False` when building span attributes.
This was fragile — callers had to know the right value, and the logic
was split between call sites instead of living in one place.

This PR:
- Adds two new substitute string constants
(`OVER_SIZE_LIMIT_SUBSTITUTE`, `UNPARSABLE_RAW_DATA_SUBSTITUTE`) for use
in the span-streaming path.
- Adds two new `AnnotatedValue` factory methods
(`substituted_because_raw_data`, `substituted_because_over_size_limit`)
that use remark type `"s"` (substituted) rather than `"x"` (removed),
for future use as the SDK fully transitions to span-first.

Refs GH-6175
Fixes PY-2396

Author: ericapisani

sentry_sdk/_types.py

@@ -6,13 +6,14 @@
 
 from typing import TYPE_CHECKING, TypeVar, Union
 
-
 # Re-exported for compat, since code out there in the wild might use this variable.
 MYPY = TYPE_CHECKING
 
 
 SENSITIVE_DATA_SUBSTITUTE = "[Filtered]"
 BLOB_DATA_SUBSTITUTE = "[Blob substitute]"
+OVER_SIZE_LIMIT_SUBSTITUTE = "[Exceeds maximum size]"
+UNPARSABLE_RAW_DATA_SUBSTITUTE = "[Unparsable]"
 
 
 class AnnotatedValue:
@@ -47,6 +48,8 @@ def __len__(self: "AnnotatedValue") -> int:
     @classmethod
     def removed_because_raw_data(cls) -> "AnnotatedValue":
         """The value was removed because it could not be parsed. This is done for request body values that are not json nor a form."""
+        # This is the legacy approach - we want to transition over to `substituted_because_raw_data` after we completely transition
+        # to span-first
         return AnnotatedValue(
             value="",
             metadata={
@@ -59,12 +62,29 @@ def removed_because_raw_data(cls) -> "AnnotatedValue":
             },
         )
 
+    @classmethod
+    def substituted_because_raw_data(cls) -> "AnnotatedValue":
+        """The value was replaced because it could not be parsed. This is done for request body values that are not json nor a form."""
+        return AnnotatedValue(
+            value=UNPARSABLE_RAW_DATA_SUBSTITUTE,
+            metadata={
+                "rem": [  # Remark
+                    [
+                        "!raw",  # Unparsable raw data
+                        "s",  # The fields original value was substituted
+                    ]
+                ]
+            },
+        )
+
     @classmethod
     def removed_because_over_size_limit(cls, value: "Any" = "") -> "AnnotatedValue":
         """
         The actual value was removed because the size of the field exceeded the configured maximum size,
         for example specified with the max_request_body_size sdk option.
         """
+        # This is the legacy approach - we want to transition over to `substituted_because_over_size_limit` after we completely transition
+        # to span-first
         return AnnotatedValue(
             value=value,
             metadata={
@@ -77,6 +97,26 @@ def removed_because_over_size_limit(cls, value: "Any" = "") -> "AnnotatedValue":
             },
         )
 
+    @classmethod
+    def substituted_because_over_size_limit(
+        cls, value: "Any" = OVER_SIZE_LIMIT_SUBSTITUTE
+    ) -> "AnnotatedValue":
+        """
+        The actual value was replaced because the size of the field exceeded the configured maximum size,
+        for example specified with the max_request_body_size sdk option.
+        """
+        return AnnotatedValue(
+            value=value,
+            metadata={
+                "rem": [  # Remark
+                    [
+                        "!config",  # Because of configured maximum size
+                        "s",  # The fields original value was substituted
+                    ]
+                ]
+            },
+        )
+
     @classmethod
     def substituted_because_contains_sensitive_data(cls) -> "AnnotatedValue":
         """The actual value was removed because it contained sensitive information."""
@@ -99,17 +139,10 @@ def substituted_because_contains_sensitive_data(cls) -> "AnnotatedValue":
 
 if TYPE_CHECKING:
     from collections.abc import Container, MutableMapping, Sequence
-
     from datetime import datetime
-
     from types import TracebackType
-    from typing import Any
-    from typing import Callable
-    from typing import Dict
-    from typing import Mapping
-    from typing import NotRequired
-    from typing import Optional
-    from typing import Type
+    from typing import Any, Callable, Dict, Mapping, NotRequired, Optional, Type
+
     from typing_extensions import Literal, TypedDict
 
     class SDKInfo(TypedDict):

sentry_sdk/integrations/_asgi_common.py

@@ -93,7 +93,9 @@ def _get_request_data(asgi_scope: "Any") -> "Dict[str, Any]":
     if ty in ("http", "websocket"):
         request_data["method"] = asgi_scope.get("method")
 
-        request_data["headers"] = headers = _filter_headers(_get_headers(asgi_scope))
+        request_data["headers"] = headers = _filter_headers(
+            _get_headers(asgi_scope),
+        )
         request_data["query_string"] = _get_query(asgi_scope)
 
         request_data["url"] = _get_url(

sentry_sdk/integrations/_wsgi_common.py

@@ -218,11 +218,11 @@ def _filter_headers(
     if should_send_default_pii():
         return headers
 
-    substitute: "Union[AnnotatedValue, str]"
-    if use_annotated_value:
-        substitute = AnnotatedValue.removed_because_over_size_limit()
-    else:
-        substitute = SENSITIVE_DATA_SUBSTITUTE
+    substitute: "Union[AnnotatedValue, str]" = (
+        SENSITIVE_DATA_SUBSTITUTE
+        if not use_annotated_value
+        else AnnotatedValue.removed_because_over_size_limit()
+    )
 
     return {
         k: (v if k.upper().replace("-", "_") not in SENSITIVE_HEADERS else substitute)