fix span.attributes mix-up, more feedback from reviewers

Author: Shannon Anahata

docs/platforms/python/tracing/configure-sampling/index.mdx

@@ -26,13 +26,16 @@ For more granular control, you can provide a `traces_sampler` function. This app
 - Filter out specific transactions entirely
 - Make sampling decisions based on transaction data
 - Control the inheritance of sampling decisions in distributed traces
+- Use custom attributes to modify sampling
 
 <Alert>
 
 It is strongly recommended when using a custom `traces_sampler` that you respect the parent sampling decision. This ensures your traces will be complete. 
 
 </Alert>
 
+In distributed systems, implement inheritance logic when trace information is propagated between services. This ensures consistent sampling decisions across your entire distributed trace
+
 <PlatformContent includePath="/performance/traces-sampler-as-sampler" />
 
 <details>
@@ -52,7 +55,7 @@ def traces_sampler(sampling_context):
         return float(parent_sampling_decision)
 
     ctx = sampling_context.get("transaction_context", {})
-    name = ctx.get("name", "")
+    name = ctx.get("name")
 
     # Sample all checkout transactions
     if name and ('/checkout' in name or 
@@ -91,8 +94,8 @@ def traces_sampler(sampling_context):
     if environment == "development":
         return 1.0
 
-    # Sample more transactions if there are recent errors
-    if ctx.get("data", {}).get("hasRecentErrors"):
+    # Sample more transactions if there are recent errors by using custom attributes
+    if ctx.get("data", {}).get("hasRecentErrors"): 
         return 0.8
 
     # Sample based on environment
@@ -101,7 +104,8 @@ def traces_sampler(sampling_context):
     elif environment == "staging":
         return 0.2   # 20% in staging
 
-    return 0.1  # 10% default
+    # Default sampling rate
+    return 0.1  
 
 sentry_sdk.init(
     dsn="your-dsn",
@@ -132,17 +136,13 @@ def traces_sampler(sampling_context):
         return 0.8
 
     # Sample less for high-volume, low-value paths
-    if ctx.get("name", "").startswith("/api/metrics"):
+   if (ctx.get("name") or "").startswith("/api/metrics"):
         return 0.01
 
     # Sample more for slow transactions
     if data.get("duration_ms", 0) > 1000:  # Transactions over 1 second
         return 0.5
 
-    # If there's a parent sampling decision, respect it
-    if sampling_context.get("parent_sampled") is not None:
-        return sampling_context["parent_sampled"]
-    
     # Default sampling rate
     return 0.2
 
@@ -187,10 +187,6 @@ def traces_sampler(sampling_context):
     if error_rate > 0.05:  # Error rate above 5%
         return 0.9
 
-    # Inherit parent sampling decision if available
-    if sampling_context.get("parent_sampled") is not None:
-        return sampling_context["parent_sampled"]
-    
     # Default sampling rate
     return 0.1
 
@@ -226,7 +222,7 @@ def traces_sampler(sampling_context):
     if data.get("cpu_percent", 0) > 80:  # Over 80% CPU
         return 0.8
 
-    # Sample more transactions with high database load
+    # Sample more transactions with high database load using custom attributes
     if data.get("db_connections", 0) > 100:  # Over 100 connections
         return 0.7
 
@@ -242,7 +238,7 @@ sentry_sdk.init(
 
 ## The Sampling Context Object
 
-When the `traces_sampler` function is called, the Sentry SDK  passes a `sampling_context` object with information from the relevant span to help make sampling decisions:
+When the `traces_sampler` function is called, the Sentry SDK passes a `sampling_context` object with information from the relevant span to help make sampling decisions:
 
 ```python
 {
@@ -251,7 +247,7 @@ When the `traces_sampler` function is called, the Sentry SDK  passes a `sampling
         "op": str,                      # short description of transaction type, like "http.request"
         "data": Optional[Dict[str, Any]] # other transaction data
     },
-    "parent_sampled  ": Optional[bool] | None,  # whether the parent transaction was sampled, `None` if no parent
+    "parent_sampled ": Optional[bool],  # whether the parent transaction was sampled, `None` if no parent or if the parent has no sampling decision
     "parent_sample_rate": Optional[float], # the sample rate used by the parent (if any)
     "transaction_context": Optional[Dict[str, Any]],  # custom context data
     "custom_sampling_context": Optional[Dict[str, Any]]  # additional custom data for sampling
@@ -265,30 +261,6 @@ When the `traces_sampler` function is called, the Sentry SDK  passes a `sampling
     - Dict[str, Any]: for dictionaries with string keys and any type of values
     - Optional[Type]: for values that might be None
 
-## Inheritance in Distributed Tracing
-
-In distributed systems, trace information is propagated between services. You can implement inheritance logic like this:
-
-```python
-def traces_sampler(sampling_context):
-    # Examine provided context data
-    if "transaction_context" in sampling_context:
-        name = sampling_context["transaction_context"].get("name", "")
-        
-        # Apply specific rules first
-        if "critical-path" in name:
-            return 1.0  # Always sample
-            
-    # Inherit parent sampling decision if available
-    if sampling_context.get("parent_sampled") is not None:
-        return sampling_context["parent_sampled"]
-        
-    # Otherwise use a default rate
-    return 0.1
-```
-
-This approach ensures consistent sampling decisions across your entire distributed trace. All transactions in a given trace will share the same sampling decision, preventing broken or incomplete traces.
-
 ## Sampling Decision Precedence
 
 When multiple sampling mechanisms could apply, Sentry follows this order of precedence:

docs/platforms/python/tracing/span-lifecycle/index.mdx

@@ -10,7 +10,7 @@ To capture transactions and spans customized to your organization's needs, you m
 
 </Alert>
 
-To add custom attributes or performance data to your applications traces, you need to attach these attributes to the trace's [spans](/concepts/key-terms/tracing/distributed-tracing/#traces-transactions-and-spans). Spans represent the individual actions that occur within an overall application interaction. This might include items loading, database calls, API returns, or more.  
+To add custom performance data to your application, you need to add custom instrumentation in the form of [spans](/concepts/key-terms/tracing/distributed-tracing/#traces-transactions-and-spans). Spans are a way to measure the time it takes for a specific action to occur. For example, you can create a span to measure the time it takes for a function to execute.
 
 <PlatformContent includePath="enriching-events/import" />
 
@@ -35,20 +35,7 @@ with sentry_sdk.start_span(op="task", name="Create User"):
     # The span automatically ends here when the 'with' block exits
 ```
 
-Alternatively, you can create spans manually and control their lifecycle yourself, which gives you more flexibility but also more responsibility:
-
-```python
-import sentry_sdk
-
-span = sentry_sdk.start_span(op="task", name="Create User")
-try:
-    # Your code here
-finally:
-    # Remember to always end your spans
-    # If you don't call span.finish(), the span will remain open indefinitely,
-    # causing memory leaks and incorrect timing data
-    span.finish()
-```
+You can call the context manager's `__enter__` and `__exit__` methods to more explicitly control the span's lifecycle.
 
 ## Span Context and Nesting
 
@@ -77,7 +64,6 @@ The following options can be used when creating spans:
 | ------------- | --------------- | ----------------------------------------------- |
 | `op`          | `string`        | The operation of the span.                      |
 | `name`        | `string`        | The name of the span.                           |
-| `attributes`  | `dict`          | Additional attributes to set on the span.       |
 | `start_time`  | `datetime/float`| The start time of the span.                     |
 
 ## Using the Context Manager
@@ -91,8 +77,8 @@ with sentry_sdk.start_span(op="db", name="Query Users") as span:
     # Perform a database query
     users = db.query("SELECT * FROM users")
 
-    # You can set attributes on the span
-    span.set_attribute("user_count", len(users))
+    # You can set data on the span
+    span.set_data("user_count", len(users))
 ```
 
 The context manager also correctly handles exceptions, marking the span as failed if an exception occurs:
@@ -110,41 +96,6 @@ except Exception:
     pass
 ```
 
-## Creating Spans Manually
-
-In some cases, you might need more control over when a span starts and ends. For this, you can create spans manually:
-
-```python
-import sentry_sdk
-
-def process_file(file_path):
-    # Create a span
-    span = sentry_sdk.start_span(op="file", name="Process File")
-    
-    try:
-        # Your processing logic
-        with open(file_path, 'r') as f:
-            content = f.read()
-        
-        # Set additional attributes
-        span.set_attribute("file_size", len(content))
-        
-        # Process the content
-        result = process_content(content)
-        
-        return result
-    except Exception as e:
-        # Mark the span as failed
-        span.set_status("error")
-        # You can also add error details as attributes
-        span.set_attribute("error_type", type(e).__name__)
-        span.set_attribute("error_message", str(e))
-        raise
-    finally:
-        # Always end the span
-        span.finish()
-```
-
 ## Getting the Current Span
 
 You can access the currently active span using `sentry_sdk.get_current_span()`:
@@ -155,7 +106,7 @@ import sentry_sdk
 # Get the current active span
 current_span = sentry_sdk.get_current_span()
 if current_span:
-    current_span.set_attribute("key", "value")
+    current_span.set_data("key", "value")
 ```
 
 ## Working with Transactions
@@ -174,6 +125,10 @@ with sentry_sdk.start_transaction(name="Background Task", op="task") as transact
         pass
 ```
 
+## Distributed Tracing
+
+See <PlatformLink to="/tracing/distributed-tracing/">Distributed Tracing</PlatformLink> for details on how to propagate trace information across different services or applications. 
+
 ## Improving Span Data
 
 ### Adding Span Attributes
@@ -183,16 +138,12 @@ Span attributes customize information you can get through tracing. This informat
 ```python
 import sentry_sdk
 
-with sentry_sdk.start_span(op="db", name="Query Users", attributes={
-    "db.query": "SELECT * FROM users WHERE active = true",
-    "db.system": "postgresql",
-    "server.address": "db.example.com"
-}) as span:
+with sentry_sdk.start_span(op="db", name="Query Users") as span:
     # Execute the query
     users = db.query("SELECT * FROM users WHERE active = true")
 
-    # You can add more attributes during execution
-    span.set_attribute("result_count", len(users))
+    # You can add more data during execution
+    span.set_data("result_count", len(users))
 ```
 
 You can also add attributes to an existing span:
@@ -203,9 +154,9 @@ import sentry_sdk
 # Get the current span
 span = sentry_sdk.get_current_span()
 if span:
-    # Set individual attributes
-    span.set_attribute("user_id", user.id)
-    span.set_attribute("request_size", len(request.body))
+    # Set individual data points
+    span.set_data("user_id", user.id)
+    span.set_data("request_size", len(request.body))
 ```
 
 ### Adding Attributes to All Spans
@@ -259,8 +210,10 @@ with sentry_sdk.start_span(op="http.client", name="Fetch User Data"):
 
 # Database operation
 with sentry_sdk.start_span(op="db", name="Save User"):
-    db.execute("INSERT INTO users (name, email) VALUES (%s, %s)", 
-              (user.name, user.email))
+        db.execute(
+        "INSERT INTO users (name, email) VALUES (%s, %s)", 
+        (user.name, user.email),
+    )
 
 # File I/O operation
 with sentry_sdk.start_span(op="file.read", name="Read Config"):
@@ -284,7 +237,7 @@ with sentry_sdk.start_span(op="task", name="Process Payment") as span:
         else:
             # Mark the span as failed
             span.set_status("error")
-            span.set_attribute("error_reason", result.error)
+            span.set_data("error_reason", result.error)
     except Exception:
         # Span will automatically be marked as failed when an exception occurs
         raise