break out span lifecycle doc and resolve feedback from PR

Author: Shannon Anahata

docs/platforms/python/profiling/index.mdx

@@ -51,10 +51,6 @@ For Profiling to work, you have to first enable [Sentry’s tracing](/concepts/k
 
 </Alert>
 
-### Upgrading from Older Python SDK Versions
-
-Profiling was experimental in SDK versions `1.17.0` and older. Learn how to upgrade <PlatformLink to="/troubleshooting">here</PlatformLink>.
-
 ## Enable Continuous Profiling
 
 <Include name="feature-stage-beta.mdx" />

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

@@ -1,37 +1,53 @@
 ---
 title: Configure Sampling
 description: "Learn how to configure sampling in your app."
-sidebar_order: 30
+sidebar_order: 40
 ---
 
-Sentry's tracing functionality helps you monitor application performance by capturing distributed traces, attaching attributes, and adding span performance metrics across your application. However, capturing traces for every transaction can generate significant volumes of data. Sampling allows you to control the amount of spans that are sent to Sentry from your application.
+If you find that Sentry's tracing functionality is generating too much data, for example, if you notice your spans quota is quickly being exhausted, you can choose to sample your traces.
 
-Effective sampling is key to getting the most value from Sentry's performance monitoring while minimizing overhead. The `traces_sampler` function gives you precise control over which transactions to record, allowing you to focus on the most important parts of your application.
+Effective sampling is key to getting the most value from Sentry's performance monitoring while minimizing overhead. The Python SDK provides two ways to control the sampling rate. You can review the options and [examples](#trace-sampler-examples) below.
 
 ## Sampling Configuration Options
 
-The Python SDK provides two main options for controlling the sampling rate:
+### 1. Uniform Sample Rate (`traces_sample_rate`)
 
-1. Uniform Sample Rate (`traces_sample_rate`)
-
-This option sets a fixed percentage of transactions to be captured:
+`traces_sample_rate` is a floating-point value between `0.0` and `1.0`, inclusive, which controls the probability with which each transaction will be sampled:
 
 <PlatformContent includePath="/performance/traces-sample-rate" />
 
-With `traces_sample_rate` set to `0.25`, approximately 25% of transactions will be recorded and sent to Sentry. This provides an even cross-section of transactions regardless of where in your app they occur.
+With `traces_sample_rate` set to `0.25`, each transaction in your application is randomly sampled with a probability of `0.25`, so you can expect that one in every four transactions will be sent to Sentry. 
 
-2. Sampling Function (`traces_sampler`)
+### 2. Sampling Function (`traces_sampler`)
 
-For more granular control, you can use the `traces_sampler` function. This approach allows you to:
+For more granular control, you can provide a `traces_sampler` function. This approach allows you to:
 
 - Apply different sampling rates to different types of transactions
 - Filter out specific transactions entirely
 - Make sampling decisions based on transaction data
 - Control the inheritance of sampling decisions in distributed traces
 
+<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>
+
+```python
+    # Use the parent sampling decision if we have an incoming trace.
+    # Note: we strongly recommend respecting the parent sampling decision,
+    # as this ensures your traces will be complete!
+    parent_sampling_decision = sampling_context.get("parent_sampled")
+    if parent_sampling_decision is not None:
+        return float(parent_sampling_decision)
+```
+
 <PlatformContent includePath="/performance/traces-sampler-as-sampler" />
 
-### Trace Sampler Examples
+<details>
+<summary className="text-xl font-semibold">Trace Sampler Examples</summary>
+
+#### Trace Sampler Examples
 
 1. Prioritizing Critical User Flows
 
@@ -196,6 +212,7 @@ sentry_sdk.init(
     traces_sampler=traces_sampler,
 )
 ```
+</details>
 
 ## The Sampling Context Object
 
@@ -204,22 +221,23 @@ When the `traces_sampler` function is called, the Sentry SDK  passes a `sampling
 ```python
 {
     "transaction_context": {
-        "name": str,  # transaction title at creation time
-        "op": str,    # short description of transaction type, like "http.request"
-        # other transaction data...
+        "name": str,                    # transaction title at creation time
+        "op": str,                      # short description of transaction type, like "http.request"
+        "data": Optional[Dict[str, Any]] # other transaction data
     },
-    "parent_sampled": bool,  # whether the parent transaction was sampled (if any)
-    "parent_sample_rate": float,  # the sample rate used by the parent (if any)
-    # Custom context as passed to start_transaction
+    "parent_sampled  ": Optional[bool] | None,  # whether the parent transaction was sampled, `None` if no parent
+    "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
 }
 ```
 
-The sampling context contains:
-
-- `transaction_context`: Includes the transaction name, operation type, and other metadata
-- `parent_sampled`: Whether the parent transaction was sampled (for distributed tracing)
-- `parent_sample_rate`: The sample rate used in the parent transaction
-- Any custom sampling context data passed to `start_transaction`
+<b>Additional common types used in</b> `sampling_context`<b>:</b>
+    - str: for text values (names, operations, etc.)
+    - bool: for true/false values
+    - float: for decimal numbers (like sample rates)
+    - 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
 
@@ -250,39 +268,20 @@ This approach ensures consistent sampling decisions across your entire distribut
 When multiple sampling mechanisms could apply, Sentry follows this order of precedence:
 
 1. If a sampling decision is passed to `start_transaction`, that decision is used
-2. If `traces_sampler` is defined, its decision is used (can consider parent sampling)
-3. If no `traces_sampler` but parent sampling is available, parent decision is used
+2. If `traces_sampler` is defined, its decision is used. Although the `traces_sampler` can override the parent sampling decision, most users will want to ensure their `traces_sampler` respects the parent sampling decision
+3. If no `traces_sampler` is defined, but there is a parent sampling decision from an incoming distributed trace, we use the parent sampling decision 
 4. If neither of the above, `traces_sample_rate` is used
-5. If none of the above are set, no transactions are sampled (0%)
+5. If none of the above are set, no transactions are sampled. This is equivalent to setting `traces_sample_rate=0.0`
 
 ## How Sampling Propagates in Distributed Traces
 
 Sentry uses a "head-based" sampling approach:
 
 - A sampling decision is made in the originating service (the "head")
-- This decision is propagated to all downstream services via HTTP headers
+- This decision is propagated to all downstream services 
 
 The two key headers are:
 - `sentry-trace`: Contains trace ID, span ID, and sampling decision
 - `baggage`: Contains additional trace metadata including sample rate
 
-The Sentry Python SDK automatically attaches these headers to outgoing HTTP requests when using auto-instrumentation with libraries like `requests`, `urllib3`, or `httpx`. For other communication channels, you can manually propagate trace information:
-
-```python
-# Extract trace data from the current scope
-trace_data = sentry_sdk.get_current_scope().get_trace_context()
-sentry_trace_header = trace_data.get("sentry-trace")
-baggage_header = trace_data.get("baggage")
-
-# Add to your custom request (example using a message queue)
-message = {
-    "data": "Your data here",
-    "metadata": {
-        "sentry_trace": sentry_trace_header,
-        "baggage": baggage_header
-    }
-}
-queue.send(json.dumps(message))
-```
-
-By implementing a thoughtful sampling strategy, you'll get the performance insights you need without overwhelming your systems or your Sentry quota.
+The Sentry Python SDK automatically attaches these headers to outgoing HTTP requests when using auto-instrumentation with libraries like `requests`, `urllib3`, or `httpx`. For other communication channels, you can manually propagate trace information. Learn more about customizing tracing in [custom trace propagation](/platforms/python/tracing/distributed-tracing/custom-trace-propagation/).

docs/platforms/python/tracing/distributed-tracing/custom-instrumentation/index.mdx renamed to docs/platforms/python/tracing/distributed-tracing/custom-trace-propagation/index.mdx

@@ -1,5 +1,5 @@
 ---
-title: Custom Instrumentation
+title: Custom Trace Propagation
 sidebar_order: 10
 ---