Skip to content

Commit 9d8f73b

Browse files
Zylphrexcoolguyzoneindragiek
authored and
bitsandfoxes
committed
docs(python): Update python continuous profiling docs (#13250)
* docs(python): Update python continuous profiling docs This updates the profiling docs for python to make continuous profiling the default. * address feedback * fix links * fix typos * Apply suggestions from code review Co-authored-by: Alex Krawiec <[email protected]> * Update docs/platforms/python/profiling/index.mdx --------- Co-authored-by: Alex Krawiec <[email protected]> Co-authored-by: Indragie Karunaratne <[email protected]>
1 parent 23fd821 commit 9d8f73b

File tree

2 files changed

+83
-56
lines changed

2 files changed

+83
-56
lines changed

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

Lines changed: 71 additions & 54 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,104 +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 profiling 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 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>
45+
### Enabling Manual Lifecycle Profiling
4746

48-
The <PlatformIdentifier name="profiles_sample_rate" /> setting is _relative_ to the <PlatformIdentifier name="traces_sample_rate" /> setting.
47+
```python
48+
import sentry_sdk
4949

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.
50+
sentry_sdk.init(
51+
dsn="___PUBLIC_DSN___",
52+
send_default_pii=True,
53+
traces_sample_rate=1.0,
5154

52-
</Alert>
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+
)
5363

54-
## Enable Continuous Profiling
64+
sentry_sdk.profiler.start_profiler()
5565

56-
<Include name="feature-stage-beta.mdx" />
66+
# run some code here
5767

58-
_(New in version 2.24.1)_
68+
sentry_sdk.profiler.stop_profiler()
69+
```
5970

60-
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.
71+
### Managing Profile Sampling Rates
6172

62-
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`.
73+
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.
6374

64-
### Sampling
75+
This is useful for cases where you deploy your service many times, but would only like a subset of those deployments to be profiled.
6576

66-
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.
77+
### Upgrading From Older SDK Versions
6778

68-
Set `profile_session_sample_rate=1.0` to collect continuous profiles for 100% of profile sessions.
79+
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 <PlatformLink to="/troubleshooting/#continuous-profiling">here</PlatformLink>.
80+
81+
## Enable Transaction-Based Profiling
6982

7083
<Alert>
7184

72-
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`.
7386

7487
</Alert>
7588

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+
7691
```python
7792
import sentry_sdk
7893

94+
def profiles_sampler(sampling_context):
95+
# ...
96+
# return a number between 0 and 1 or a boolean
97+
7998
sentry_sdk.init(
8099
dsn="___PUBLIC_DSN___",
100+
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
81103
send_default_pii=True,
104+
82105
traces_sample_rate=1.0,
83106

84-
# To collect profiles for all profile sessions, set `profile_session_sample_rate` to 1.0.
85-
profile_session_sample_rate=1.0,
86-
)
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,
87112

88-
sentry_sdk.profiler.start_profiler()
113+
# Alternatively, to control sampling dynamically
114+
profiles_sampler=profiles_sampler
115+
)
116+
```
89117

90-
# run some code here
118+
<Alert>
91119

92-
sentry_sdk.profiler.stop_profiler()
93-
```
94-
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.
120+
The <PlatformIdentifier name="profiles_sample_rate" /> setting is _relative_ to the <PlatformIdentifier name="traces_sample_rate" /> setting.
95121

96-
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.
122+
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 <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.
97123

98-
```python
99-
import sentry_sdk
124+
</Alert>
100125

101-
sentry_sdk.init(
102-
dsn="___PUBLIC_DSN___",
103-
send_default_pii=True,
104-
traces_sample_rate=1.0,
105-
# To collect profiles for all profile sessions, set `profile_session_sample_rate` to 1.0.
106-
profile_session_sample_rate=1.0,
107-
profile_lifecycle="trace",
108-
)
109-
```
126+
### Upgrading From Older Python SDK Versions
110127

111-
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="/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)