Skip to content

Commit 351456d

Browse files
ZylphrexZylphrex
committed
docs(python): Update python continuous profiling docs
This updates the profiling docs for python to make continuous profiling the default.
1 parent 2aae768 commit 351456d

File tree

2 files changed

+82
-60
lines changed

2 files changed

+82
-60
lines changed

‎docs/platforms/python/profiling/index.mdx‎

Lines changed: 70 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Set Up Profiling for Python
2+
title: Set Up Profiling
33
description: "Learn how to enable profiling in your app if it is not already set up."
44
sidebar_order: 5000
55
---
@@ -8,109 +8,121 @@ sidebar_order: 5000
88

99
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/)
1010

11-
## Enable Profiling in Python
11+
## Enabling Continuous Profiling
1212

1313
<Alert>
1414

15-
Python profiling is stable as of SDK version `1.18.0`.
15+
Continuous profiling is available starting in SDK version `2.24.1`.
16+
17+
<PlatformLink to="/profiling/#enable-transaction-based-profiling">Transaction based profiling</PlatformLink> is available starting in SDK version `1.18.0`.
1618

1719
</Alert>
1820

21+
Continuous rofiling supports two modes - `manual` and `trace`. The two modes are mutually exclusive, and cannot be used at the same time.
22+
23+
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.
24+
25+
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.
26+
27+
### Enabling Trace Lifecycle Profiling
28+
1929
```python
2030
import sentry_sdk
2131

22-
def profiles_sampler(sampling_context):
23-
# ...
24-
# return a number between 0 and 1 or a boolean
25-
2632
sentry_sdk.init(
2733
dsn="___PUBLIC_DSN___",
28-
29-
# Add data like request headers and IP for users, if applicable;
30-
# see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info
3134
send_default_pii=True,
32-
3335
traces_sample_rate=1.0,
34-
35-
# To set a uniform sample rate
36-
# Set profiles_sample_rate to 1.0 to profile 100%
37-
# of sampled transactions.
38-
# We recommend adjusting this value in production,
39-
profiles_sample_rate=1.0,
40-
41-
# Alternatively, to control sampling dynamically
42-
profiles_sampler=profiles_sampler
36+
# To collect profiles for all profile sessions,
37+
# set `profile_session_sample_rate` to 1.0.
38+
profile_session_sample_rate=1.0,
39+
# Profiles will be automatically collected while
40+
# there is an active span.
41+
profile_lifecycle="trace",
4342
)
4443
```
4544

46-
<Alert>
47-
48-
The <PlatformIdentifier name="profiles_sample_rate" /> setting is _relative_ to the <PlatformIdentifier name="traces_sample_rate" /> setting.
45+
### Enabling Manual Lifecycle Profiling
4946

50-
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.
47+
```python
48+
import sentry_sdk
5149

52-
</Alert>
50+
sentry_sdk.init(
51+
dsn="___PUBLIC_DSN___",
52+
send_default_pii=True,
53+
traces_sample_rate=1.0,
5354

54-
### Upgrading from Older Python SDK Versions
55+
# To collect profiles for all profile sessions,
56+
# set `profile_session_sample_rate` to 1.0.
57+
profile_session_sample_rate=1.0,
58+
# Profiles will be collected when
59+
# `sentry_sdk.profiler.start_profiler` is called and
60+
# stopped when `sentry_sdk.profiler.stop_profiler` is called.
61+
profile_lifecycle="manual",
62+
)
5563

56-
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>.
64+
sentry_sdk.profiler.start_profiler()
5765

58-
## Enable Continuous Profiling
66+
# run some code here
5967

60-
<Include name="feature-stage-beta.mdx" />
68+
sentry_sdk.profiler.stop_profiler()
69+
```
6170

62-
_(New in version 2.24.1)_
71+
### Managing profile sampling rates
6372

64-
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.
73+
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.
6574

66-
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`.
75+
This is useful for cases where you deploy your service many times, but would only like a subset of those services to be profiled.
6776

68-
### Sampling
77+
### Upgrading from Older SDK versions
6978

70-
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.
79+
Continuous profiling was experimental in SDK versions prior to `2.24.1`. Learn how to upgrade <PlatformLink to="/profiling/troubleshooting/#continuous-profiling">here</PlatformLink>.
7180

72-
Set `profile_session_sample_rate=1.0` to collect continuous profiles for 100% of profile sessions.
81+
## Enable Transaction Based Profiling
7382

7483
<Alert>
7584

76-
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.
85+
Transaction based profiling is available starting in SDK version `1.18.0`.
7786

7887
</Alert>
7988

89+
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.
90+
8091
```python
8192
import sentry_sdk
8293

94+
def profiles_sampler(sampling_context):
95+
# ...
96+
# return a number between 0 and 1 or a boolean
97+
8398
sentry_sdk.init(
8499
dsn="___PUBLIC_DSN___",
85-
send_default_pii=True,
86-
traces_sample_rate=1.0,
87100

88-
# To collect profiles for all profile sessions, set `profile_session_sample_rate` to 1.0.
89-
profile_session_sample_rate=1.0,
90-
)
101+
# Add data like request headers and IP for users, if applicable;
102+
# see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info
103+
send_default_pii=True,
91104

92-
sentry_sdk.profiler.start_profiler()
105+
traces_sample_rate=1.0,
93106

94-
# run some code here
107+
# To set a uniform sample rate
108+
# Set profiles_sample_rate to 1.0 to profile 100%
109+
# of sampled transactions.
110+
# We recommend adjusting this value in production,
111+
profiles_sample_rate=1.0,
95112

96-
sentry_sdk.profiler.stop_profiler()
113+
# Alternatively, to control sampling dynamically
114+
profiles_sampler=profiles_sampler
115+
)
97116
```
98117

99-
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.
118+
<Alert>
100119

101-
```python
102-
import sentry_sdk
120+
The <PlatformIdentifier name="profiles_sample_rate" /> setting is _relative_ to the <PlatformIdentifier name="traces_sample_rate" /> setting.
103121

104-
sentry_sdk.init(
105-
dsn="___PUBLIC_DSN___",
106-
send_default_pii=True,
107-
traces_sample_rate=1.0,
108-
# To collect profiles for all profile sessions, set `profile_session_sample_rate` to 1.0.
109-
profile_session_sample_rate=1.0,
110-
profile_lifecycle="trace",
111-
)
112-
```
122+
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.
113123

114-
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.
124+
</Alert>
125+
126+
### Upgrading from Older Python SDK Versions
115127

116-
Continuous profiling has implications for your org's billing structure. This feature is only available for subscription plans that enrolled after June 5, 2024.
128+
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‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -193,17 +193,27 @@ If you don't see any profiling data in [sentry.io](https://sentry.io), you can t
193193

194194
### Upgrading From Older SDK Versions
195195

196-
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.
196+
#### Transaction Based Profiling
197+
198+
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.
197199

198200
```python
199201
sentry_sdk.init(
200202
dsn="___PUBLIC_DSN___",
201203
traces_sample_rate=1.0,
202204
_experiments={
203-
"profiles_sample_rate": 1.0, # for versions before 1.17.0
205+
"profiles_sample_rate": 1.0, # for versions before 1.18.0
204206
},
205207
)
206208
```
209+
210+
#### Continuous Profiling
211+
212+
The continuous profiling feature was experimental prior to version `2.24.1`. To upgrade your SDK to the latest version:
213+
214+
- Remove `continuous_profiling_auto_start` from `_experiments` and set `profile_lifecycle="trace"` in the top-level options.
215+
- Add `profile_session_sample_rate` to the top-level options.
216+
207217
</Expandable>
208218

209219

0 commit comments

Comments
 (0)