From 351456d21fb6a603b21f1262f08527cb29595b01 Mon Sep 17 00:00:00 2001 From: Tony Xiao Date: Fri, 4 Apr 2025 16:19:48 -0400 Subject: [PATCH 1/6] docs(python): Update python continuous profiling docs This updates the profiling docs for python to make continuous profiling the default. --- docs/platforms/python/profiling/index.mdx | 128 ++++++++++++---------- docs/platforms/python/troubleshooting.mdx | 14 ++- 2 files changed, 82 insertions(+), 60 deletions(-) diff --git a/docs/platforms/python/profiling/index.mdx b/docs/platforms/python/profiling/index.mdx index dc11984f426327..015e409ca0d807 100644 --- a/docs/platforms/python/profiling/index.mdx +++ b/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 -Python profiling is stable as of SDK version `1.18.0`. +Continuous profiling is available starting in SDK version `2.24.1`. + +Transaction based profiling is available starting in SDK version `1.18.0`. +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", ) ``` - - -The setting is _relative_ to the 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 tracing setup documentation to learn how to configure sampling. If you set your sample rate to 1.0, all transactions will be captured. +```python +import sentry_sdk - +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 here. +sentry_sdk.profiler.start_profiler() -## Enable Continuous Profiling +# run some code here - +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 here. -Set `profile_session_sample_rate=1.0` to collect continuous profiles for 100% of profile sessions. +## Enable Transaction Based Profiling -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`. +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. + -```python -import sentry_sdk +The setting is _relative_ to the 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 tracing setup documentation 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. + + +### 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 here. diff --git a/docs/platforms/python/troubleshooting.mdx b/docs/platforms/python/troubleshooting.mdx index bf5f2430228027..ce8c1feb1effe3 100644 --- a/docs/platforms/python/troubleshooting.mdx +++ b/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. + From a3700ac619c39a5043c7d301f40cd245be1aeb38 Mon Sep 17 00:00:00 2001 From: Tony Xiao Date: Fri, 4 Apr 2025 17:40:44 -0400 Subject: [PATCH 2/6] address feedback --- docs/platforms/python/profiling/index.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/platforms/python/profiling/index.mdx b/docs/platforms/python/profiling/index.mdx index 015e409ca0d807..767a4a93a32ad8 100644 --- a/docs/platforms/python/profiling/index.mdx +++ b/docs/platforms/python/profiling/index.mdx @@ -18,7 +18,7 @@ Continuous profiling is available starting in SDK version `2.24.1`. -Continuous rofiling supports two modes - `manual` and `trace`. The two modes are mutually exclusive, and cannot be used at the same time. +Continuous profiling 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. @@ -70,13 +70,13 @@ sentry_sdk.profiler.stop_profiler() ### Managing profile sampling rates -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. +Sentry SDK supports an additional `profile_session_sample_rate` that must be set to a non-zero value to enable continuous profiling. This can be used to control session sampling rates at the service level as the sampling decision is evaluated only once at SDK init. This is useful for cases where you deploy your service many times, but would only like a subset of those services to be profiled. ### Upgrading from Older SDK versions -Continuous profiling was experimental in SDK versions prior to `2.24.1`. Learn how to upgrade here. +Continuous profiling was experimental in SDK versions prior to `2.24.1` and will be deprecated. Data sent by these older versions will not be accepted in the near future. Learn how to upgrade here. ## Enable Transaction Based Profiling From 4883e26bc091889d7dd9f8ed5ae9c104b3a506e9 Mon Sep 17 00:00:00 2001 From: Tony Xiao Date: Mon, 7 Apr 2025 18:07:08 -0400 Subject: [PATCH 3/6] fix links --- docs/platforms/python/profiling/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/python/profiling/index.mdx b/docs/platforms/python/profiling/index.mdx index 767a4a93a32ad8..5c2fc0170bab51 100644 --- a/docs/platforms/python/profiling/index.mdx +++ b/docs/platforms/python/profiling/index.mdx @@ -76,7 +76,7 @@ This is useful for cases where you deploy your service many times, but would onl ### Upgrading from Older SDK versions -Continuous profiling was experimental in SDK versions prior to `2.24.1` and will be deprecated. Data sent by these older versions will not be accepted in the near future. Learn how to upgrade here. +Continuous profiling was experimental in SDK versions prior to `2.24.1` and will be deprecated. Data sent by these older versions will not be accepted in the near future. Learn how to upgrade here. ## Enable Transaction Based Profiling @@ -125,4 +125,4 @@ For Profiling to work, you have to first enable [Sentry’s tracing](/concepts/k ### Upgrading from Older Python SDK Versions -Transaction based profiling was experimental in SDK versions prior to `1.18.0`. Learn how to upgrade here. +Transaction based profiling was experimental in SDK versions prior to `1.18.0`. Learn how to upgrade here. From ddd692d633468227279b4b4022f19dc47433dd85 Mon Sep 17 00:00:00 2001 From: Tony Xiao Date: Wed, 9 Apr 2025 16:36:10 -0400 Subject: [PATCH 4/6] fix typos --- docs/platforms/python/profiling/index.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/platforms/python/profiling/index.mdx b/docs/platforms/python/profiling/index.mdx index 5c2fc0170bab51..cf5796bbb524ad 100644 --- a/docs/platforms/python/profiling/index.mdx +++ b/docs/platforms/python/profiling/index.mdx @@ -14,13 +14,13 @@ With [profiling](/product/explore/profiling/), Sentry tracks your software's per Continuous profiling is available starting in SDK version `2.24.1`. -Transaction based profiling is available starting in SDK version `1.18.0`. +Transaction-based profiling is available starting in SDK version `1.18.0`. Continuous profiling 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 `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 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. @@ -70,7 +70,7 @@ sentry_sdk.profiler.stop_profiler() ### Managing profile sampling rates -Sentry SDK supports an additional `profile_session_sample_rate` that must be set to a non-zero value to enable continuous profiling. This can be used to control session sampling rates at the service level as the sampling decision is evaluated only once at SDK init. +Sentry SDK supports an additional `profile_session_sample_rate` that must be set to a non-zero value to enable continuous profiling. This can be used to control session sampling rates at the service level as the sampling decision is evaluated only once at SDK initialization. This is useful for cases where you deploy your service many times, but would only like a subset of those services to be profiled. From a4ae7bf147239b8efc777ba0be0b8380bd374455 Mon Sep 17 00:00:00 2001 From: Tony Xiao Date: Wed, 9 Apr 2025 16:52:06 -0400 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Alex Krawiec --- docs/platforms/python/profiling/index.mdx | 16 ++++++++-------- docs/platforms/python/troubleshooting.mdx | 4 ++-- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/platforms/python/profiling/index.mdx b/docs/platforms/python/profiling/index.mdx index cf5796bbb524ad..013da1c8006122 100644 --- a/docs/platforms/python/profiling/index.mdx +++ b/docs/platforms/python/profiling/index.mdx @@ -68,25 +68,25 @@ sentry_sdk.profiler.start_profiler() sentry_sdk.profiler.stop_profiler() ``` -### Managing profile sampling rates +### Managing Profile Sampling Rates Sentry SDK supports an additional `profile_session_sample_rate` that must be set to a non-zero value to enable continuous profiling. This can be used to control session sampling rates at the service level as the sampling decision is evaluated only once at SDK initialization. -This is useful for cases where you deploy your service many times, but would only like a subset of those services to be profiled. +This is useful for cases where you deploy your service many times, but would only like a subset of those deployments to be profiled. -### Upgrading from Older SDK versions +### Upgrading From Older SDK Versions Continuous profiling was experimental in SDK versions prior to `2.24.1` and will be deprecated. Data sent by these older versions will not be accepted in the near future. Learn how to upgrade here. -## Enable Transaction Based Profiling +## Enable Transaction-Based Profiling -Transaction based profiling is available starting in SDK version `1.18.0`. +Transaction-based profiling is available starting in SDK version `1.18.0`. -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. +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 @@ -123,6 +123,6 @@ For Profiling to work, you have to first enable [Sentry’s tracing](/concepts/k -### Upgrading from Older Python SDK Versions +### Upgrading From Older Python SDK Versions -Transaction based profiling was experimental in SDK versions prior to `1.18.0`. Learn how to upgrade here. +Transaction-based profiling was experimental in SDK versions prior to `1.18.0`. Learn how to upgrade here. diff --git a/docs/platforms/python/troubleshooting.mdx b/docs/platforms/python/troubleshooting.mdx index ce8c1feb1effe3..79bd3d212ea7af 100644 --- a/docs/platforms/python/troubleshooting.mdx +++ b/docs/platforms/python/troubleshooting.mdx @@ -193,9 +193,9 @@ If you don't see any profiling data in [sentry.io](https://sentry.io), you can t ### Upgrading From Older SDK Versions -#### Transaction Based Profiling +#### 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. +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( From 9001fd43cc4d2186499835a9b27bcebaafe33660 Mon Sep 17 00:00:00 2001 From: Indragie Karunaratne Date: Mon, 14 Apr 2025 10:18:30 -0700 Subject: [PATCH 6/6] Update docs/platforms/python/profiling/index.mdx --- docs/platforms/python/profiling/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/python/profiling/index.mdx b/docs/platforms/python/profiling/index.mdx index 013da1c8006122..f39468851ed145 100644 --- a/docs/platforms/python/profiling/index.mdx +++ b/docs/platforms/python/profiling/index.mdx @@ -119,7 +119,7 @@ sentry_sdk.init( The setting is _relative_ to the setting. -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 tracing setup documentation to learn how to configure sampling. If you set your sample rate to 1.0, all transactions will be captured. +For transaction-based 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 tracing setup documentation to learn how to configure sampling. If you set your sample rate to 1.0, all transactions will be captured.