feat(python): Add 3.x version of span metrics page (#14477)

Adding a 3.x version of the Span Metrics page. The contents are
identical except for changing 2.x-style `set_data()` to 3.x-style
`set_attribute()`.

Since the 3.x page is a brand new file, it shows up all green on the
diff. This is the actual difference between the old page and the new
`index__v3.x.mdx` page:

```diff
--- index.mdx   2025-07-21 14:06:41
+++ index__v3.x.mdx     2025-07-28 09:44:24
@@ -23,11 +23,11 @@
 span = sentry_sdk.get_current_span()
 if span:
     # Add individual metrics
-    span.set_data("database.rows_affected", 42)
-    span.set_data("cache.hit_rate", 0.85)
-    span.set_data("memory.heap_used", 1024000)
-    span.set_data("queue.length", 15)
-    span.set_data("processing.duration_ms", 127)
+    span.set_attribute("database.rows_affected", 42)
+    span.set_attribute("cache.hit_rate", 0.85)
+    span.set_attribute("memory.heap_used", 1024000)
+    span.set_attribute("queue.length", 15)
+    span.set_attribute("processing.duration_ms", 127)
 
 ### Best Practices for Span Data
@@ -48,11 +48,11 @@
     name="Database Query Metrics"
 ) as span:
     # Set metrics after creating the span
-    span.set_data("db.query_type", "SELECT")
-    span.set_data("db.table", "users")
-    span.set_data("db.execution_time_ms", 45)
-    span.set_data("db.rows_returned", 100)
-    span.set_data("db.connection_pool_size", 5)
+    span.set_attribute("db.query_type", "SELECT")
+    span.set_attribute("db.table", "users")
+    span.set_attribute("db.execution_time_ms", 45)
+    span.set_attribute("db.rows_returned", 100)
+    span.set_attribute("db.connection_pool_size", 5)
     # Your database operation here
     pass
```

Author: sentrivana

docs/platforms/python/tracing/span-metrics/index__v3.x.mdx

@@ -0,0 +1,99 @@
+---
+title: Sending Span Metrics
+description: "Learn how to add attributes to spans in Sentry to monitor performance and debug applications "
+sidebar_order: 20
+---
+
+<Alert>
+
+To use span metrics, you must first <PlatformLink to="/tracing/">configure tracing</PlatformLink> in your application.
+
+</Alert>
+
+Span metrics allow you to extend the default metrics that are collected by tracing and track custom performance data and debugging information within your application's traces. There are two main approaches to instrumenting metrics:
+
+1. [Adding metrics to existing spans](#adding-metrics-to-existing-spans)
+2. [Creating dedicated spans with custom metrics](#creating-dedicated-metric-spans)
+
+## Adding Metrics to Existing Spans
+
+You can enhance existing spans with custom metrics by adding data. This is useful when you want to augment automatic instrumentation or add contextual data to spans you've already created.
+
+```python
+span = sentry_sdk.get_current_span()
+if span:
+    # Add individual metrics
+    span.set_attribute("database.rows_affected", 42)
+    span.set_attribute("cache.hit_rate", 0.85)
+    span.set_attribute("memory.heap_used", 1024000)
+    span.set_attribute("queue.length", 15)
+    span.set_attribute("processing.duration_ms", 127)
+```
+
+### Best Practices for Span Data
+
+When adding metrics as span data:
+
+- Use consistent naming conventions (for example, `category.metric_name`)
+- Keep attribute names concise but descriptive
+- Use appropriate data types (string, number, boolean, or an array containing only one of these types)
+
+## Creating Dedicated Metric Spans
+
+For more detailed operations, tasks, or process tracking, you can create custom dedicated spans that focus on specific metrics or attributes that you want to track. This approach provides better discoverability and more precise span configurations, however it can also create more noise in your trace waterfall.
+
+```python
+with sentry_sdk.start_span(
+    op="db.metrics",
+    name="Database Query Metrics"
+) as span:
+    # Set metrics after creating the span
+    span.set_attribute("db.query_type", "SELECT")
+    span.set_attribute("db.table", "users")
+    span.set_attribute("db.execution_time_ms", 45)
+    span.set_attribute("db.rows_returned", 100)
+    span.set_attribute("db.connection_pool_size", 5)
+    # Your database operation here
+    pass
+```
+
+For detailed examples of how to implement span metrics in common scenarios, see our <PlatformLink to="/tracing/span-metrics/examples/">Span Metrics Examples</PlatformLink> guide.
+
+## Adding Metrics to All Spans
+
+To consistently add metrics across all spans in your application, you can use the `before_send_transaction` callback:
+
+```python
+import sentry_sdk
+from sentry_sdk.types import Event, Hint
+
+def before_send_transaction(event: Event, hint: Hint) -> Event | None:
+    # Add metrics to the root span
+    if "trace" in event.get("contexts", {}):
+        if "data" not in event["contexts"]["trace"]:
+            event["contexts"]["trace"]["data"] = {}
+
+        event["contexts"]["trace"]["data"].update({
+            "app.version": "1.2.3",
+            "environment.region": "us-west-2"
+        })
+
+    # Add metrics to all child spans
+    for span in event.get("spans", []):
+        if "data" not in span:
+            span["data"] = {}
+
+        span["data"].update({
+            "app.component_version": "2.0.0",
+            "app.deployment_stage": "production"
+        })
+
+    return event
+
+sentry_sdk.init(
+    # ...
+    before_send_transaction=before_send_transaction
+)
+```
+
+For detailed examples of how to implement span metrics in common scenarios, see our <PlatformLink to="/tracing/span-metrics/examples/">Span Metrics Examples</PlatformLink> guide.