docs(python): Update python continuous profiling docs

docs/platforms/python/profiling/index.mdx

@@ -1,5 +1,5 @@
 ---
-title: Set Up Profiling for Python
+title: Set Up Profiling
 description: "Learn how to enable profiling in your app if it is not already set up."
 sidebar_order: 5000
 ---
@@ -8,109 +8,121 @@ sidebar_order: 5000
 
 With [profiling](/product/explore/profiling/), Sentry tracks your software's performance by sampling your program's call stack in a variety of environments. This feature collects function-level information about your code and enables you to fine-tune your program's performance. [Sentry's profiler](https://sentry.io/for/profiling/) captures function calls and their exact locations, aggregates them, and shows you the most common code paths of your program. This highlights areas you could optimize to help increase both the performance of your code and increase user satisfaction, as well as drive down costs. Learn how to enable and configure profiling in Python with Sentry's stable [Python SDK](https://sentry.io/for/python/)
 
-## Enable Profiling in Python
+## Enabling Continuous Profiling
 
 <Alert>
 
-Python profiling is stable as of SDK version `1.18.0`.
+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`.
 
 </Alert>
 
+Continuous rofiling supports two modes - `manual` and `trace`. The two modes are mutually exclusive, and cannot be used at the same time.
+
+In `manual` mode, the profiling data collection can be managed via calls to `sentry_sdk.profiler.start_profiler` and `sentry_sdk.profiler.stop_profiler`. You are entirely in the in control of when the profiler runs.
+
+In `trace` mode, the profiler manages its own start and stop calls, which are based on spans: the profiler continues to run while there is at least one active span, and stops when there are no active spans.
+
+### Enabling Trace Lifecycle Profiling
+
 ```python
 import sentry_sdk
 
-def profiles_sampler(sampling_context):
-    # ...
-    # return a number between 0 and 1 or a boolean
-
 sentry_sdk.init(
     dsn="___PUBLIC_DSN___",
-
-    # Add data like request headers and IP for users, if applicable;
-    # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info
     send_default_pii=True,
-
     traces_sample_rate=1.0,
-
-    # To set a uniform sample rate
-    # Set profiles_sample_rate to 1.0 to profile 100%
-    # of sampled transactions.
-    # We recommend adjusting this value in production,
-    profiles_sample_rate=1.0,
-
-    # Alternatively, to control sampling dynamically
-    profiles_sampler=profiles_sampler
+    # To collect profiles for all profile sessions,
+    # set `profile_session_sample_rate` to 1.0.
+    profile_session_sample_rate=1.0,
+    # Profiles will be automatically collected while
+    # there is an active span.
+    profile_lifecycle="trace",
 )
 ```
 
-<Alert>
-
-The <PlatformIdentifier name="profiles_sample_rate" /> setting is _relative_ to the <PlatformIdentifier name="traces_sample_rate" /> setting.
+### Enabling Manual Lifecycle Profiling
 
-For Profiling to work, you have to first enable [Sentry’s tracing](/concepts/key-terms/tracing/) via `traces_sample_rate` (like in the example above). Read our <PlatformLink to="/tracing/">tracing setup documentation</PlatformLink> to learn how to configure sampling. If you set your sample rate to 1.0, all transactions will be captured.
+```python
+import sentry_sdk
 
-</Alert>
+sentry_sdk.init(
+    dsn="___PUBLIC_DSN___",
+    send_default_pii=True,
+    traces_sample_rate=1.0,
 
-### Upgrading from Older Python SDK Versions
+    # To collect profiles for all profile sessions,
+    # set `profile_session_sample_rate` to 1.0.
+    profile_session_sample_rate=1.0,
+    # Profiles will be collected when
+    # `sentry_sdk.profiler.start_profiler` is called and
+    # stopped when `sentry_sdk.profiler.stop_profiler` is called.
+    profile_lifecycle="manual",
+)
 
-Profiling was experimental in SDK versions `1.17.0` and older. Learn how to upgrade <PlatformLink to="/profiling/troubleshooting/#ipgrading-from-older-sdk-versions">here</PlatformLink>.
+sentry_sdk.profiler.start_profiler()
 
-## Enable Continuous Profiling
+# run some code here
 
-<Include name="feature-stage-beta.mdx" />
+sentry_sdk.profiler.stop_profiler()
+```
 
-_(New in version 2.24.1)_
+### Managing profile sampling rates
 
-The current profiling implementation stops the profiler automatically after 30 seconds (unless you manually stop it earlier). Naturally, this limitation makes it difficult to get full coverage of your app's execution. We now offer an experimental continuous mode, where profiling data is periodically uploaded while running, with no limit on how long the profiler may run.
+Sentry SDK supports an additional `profile_session_sample_rate` that will enable or disable profiling for the entire session. This can be used if you want to control session sampling rates at the service level as the sampling decision is evaluated only once at SDK init.
 
-To get started with continuous profiling, you can start and stop the profiler directly with `sentry_sdk.profiler.start_profiler` and `sentry_sdk.profiler.stop_profiler`.
+This is useful for cases where you deploy your service many times, but would only like a subset of those services to be profiled.
 
-### Sampling
+### Upgrading from Older SDK versions
 
-Sampling for continuous profiling is determined only once when the SDK is configured. That sampling decision is used to decide if the profiles will be collected or not for the entirety of the process.
+Continuous profiling was experimental in SDK versions prior to `2.24.1`. Learn how to upgrade <PlatformLink to="/profiling/troubleshooting/#continuous-profiling">here</PlatformLink>.
 
-Set `profile_session_sample_rate=1.0` to collect continuous profiles for 100% of profile sessions.
+## Enable Transaction Based Profiling
 
 <Alert>
 
-If you previously set `profiles_sample_rate` or `profilers_sampler` to use transaction-based profiling, you must remove those lines of code from your configuration in order to use continuous profiling.
+Transaction based profiling is available starting in SDK version `1.18.0`.
 
 </Alert>
 
+Transaction based profiling only runs in tandem with performance transactions that were started either automatically or manually with `sentry_sdk.start_transaction`, and stops after the transaction ends or after 30 seconds.
+
 ```python
 import sentry_sdk
 
+def profiles_sampler(sampling_context):
+    # ...
+    # return a number between 0 and 1 or a boolean
+
 sentry_sdk.init(
     dsn="___PUBLIC_DSN___",
-    send_default_pii=True,
-    traces_sample_rate=1.0,
 
-    # To collect profiles for all profile sessions, set `profile_session_sample_rate` to 1.0.
-    profile_session_sample_rate=1.0,
-)
+    # Add data like request headers and IP for users, if applicable;
+    # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info
+    send_default_pii=True,
 
-sentry_sdk.profiler.start_profiler()
+    traces_sample_rate=1.0,
 
-# run some code here
+    # To set a uniform sample rate
+    # Set profiles_sample_rate to 1.0 to profile 100%
+    # of sampled transactions.
+    # We recommend adjusting this value in production,
+    profiles_sample_rate=1.0,
 
-sentry_sdk.profiler.stop_profiler()
+    # Alternatively, to control sampling dynamically
+    profiles_sampler=profiles_sampler
+)
 ```
 
-For some applications such as web servers, it may be difficult to call `sentry_sdk.profiler.start_profiler` in every process. Instead, you can use the `profile_lifecycle` option to automatically profile anytime a transaction is active.
+<Alert>
 
-```python
-import sentry_sdk
+The <PlatformIdentifier name="profiles_sample_rate" /> setting is _relative_ to the <PlatformIdentifier name="traces_sample_rate" /> setting.
 
-sentry_sdk.init(
-    dsn="___PUBLIC_DSN___",
-    send_default_pii=True,
-    traces_sample_rate=1.0,
-    # To collect profiles for all profile sessions, set `profile_session_sample_rate` to 1.0.
-    profile_session_sample_rate=1.0,
-    profile_lifecycle="trace",
-)
-```
+For Profiling to work, you have to first enable [Sentry’s tracing](/concepts/key-terms/tracing/) via `traces_sample_rate` (like in the example above). Read our <PlatformLink to="/tracing/">tracing setup documentation</PlatformLink> to learn how to configure sampling. If you set your sample rate to 1.0, all transactions will be captured.
 
-These new APIs do not offer any sampling functionality—every call to start the profiler will start it, and the same goes for launch profiles if you've configured that. If you are interested in reducing the amount of profiles that run, you must take care to do it at the callsites.
+</Alert>
+
+### Upgrading from Older Python SDK Versions
 
-Continuous profiling has implications for your org's billing structure. This feature is only available for subscription plans that enrolled after June 5, 2024.
+Transaction based profiling was experimental in SDK versions prior to `1.18.0`. Learn how to upgrade <PlatformLink to="/profiling/troubleshooting/#transaction-based-profiling">here</PlatformLink>.

docs/platforms/python/troubleshooting.mdx

@@ -193,17 +193,27 @@ If you don't see any profiling data in [sentry.io](https://sentry.io), you can t
 
 ### Upgrading From Older SDK Versions
 
-The feature was experimental prior to version `1.17.0`. To update your SDK to the latest version, remove `profiles_sample_rate` from `_experiments` and set it in the top-level options.
+#### Transaction Based Profiling
+
+The transaction based profiling feature was experimental prior to version `1.18.0`. To update your SDK to the latest version, remove `profiles_sample_rate` from `_experiments` and set it in the top-level options.
 
 ```python
 sentry_sdk.init(
     dsn="___PUBLIC_DSN___",
     traces_sample_rate=1.0,
     _experiments={
-      "profiles_sample_rate": 1.0,  # for versions before 1.17.0
+      "profiles_sample_rate": 1.0,  # for versions before 1.18.0
     },
 )
 ```
+
+#### Continuous Profiling
+
+The continuous profiling feature was experimental prior to version `2.24.1`. To upgrade your SDK to the latest version:
+
+- Remove `continuous_profiling_auto_start` from `_experiments` and set `profile_lifecycle="trace"` in the top-level options.
+- Add `profile_session_sample_rate` to the top-level options.
+
 </Expandable>