Skip to content

Commit 1f39d9e

Browse files
sentrivanalucas-zimerman
sentrivana
authored and
lucas-zimerman
committed
feat(python): Document default span attrs in RQ, update for 3.0 (#14369)
Document what span attributes will be attached to transactions by default by our builtin integrations. This PR updates RQ. Rest will follow. I created a new 3.x page for this since it's new behavior in 3.0.
1 parent 4c4216f commit 1f39d9e

File tree

1 file changed

+220
-0
lines changed

1 file changed

+220
-0
lines changed

‎docs/platforms/python/integrations/rq/index__v3.x.mdx

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
---
2+
title: RQ (Redis Queue)
3+
description: "Learn about using Sentry with RQ."
4+
---
5+
6+
The RQ integration adds support for the [RQ job queue system](https://python-rq.org/).
7+
8+
## Install
9+
10+
Install `sentry-sdk` from PyPI with the `rq` extra:
11+
12+
```bash {tabTitle:pip}
13+
pip install "sentry-sdk[rq]"
14+
```
15+
```bash {tabTitle:uv}
16+
uv add "sentry-sdk[rq]"
17+
```
18+
19+
## Configure
20+
21+
If you have the `rq` package in your dependencies, the RQ integration will be enabled automatically when you initialize the Sentry SDK.
22+
23+
Create a file called `mysettings.py` with the following content:
24+
25+
26+
In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). You can also collect and analyze performance profiles from real users with [profiling](/product/explore/profiling/).
27+
28+
Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below.
29+
30+
<OnboardingOptionButtons
31+
options={[
32+
'error-monitoring',
33+
'performance',
34+
'profiling',
35+
]}
36+
/>
37+
38+
```python {filename:mysettings.py}
39+
# mysettings.py
40+
import sentry_sdk
41+
42+
sentry_sdk.init(
43+
dsn="___PUBLIC_DSN___",
44+
# Add data like request headers and IP for users, if applicable;
45+
# see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info
46+
send_default_pii=True,
47+
# ___PRODUCT_OPTION_START___ performance
48+
# Set traces_sample_rate to 1.0 to capture 100%
49+
# of transactions for tracing.
50+
traces_sample_rate=1.0,
51+
# ___PRODUCT_OPTION_END___ performance
52+
# ___PRODUCT_OPTION_START___ profiling
53+
# To collect profiles for all profile sessions,
54+
# set `profile_session_sample_rate` to 1.0.
55+
profile_session_sample_rate=1.0,
56+
# Profiles will be automatically collected while
57+
# there is an active span.
58+
profile_lifecycle="trace",
59+
# ___PRODUCT_OPTION_END___ profiling
60+
)
61+
```
62+
63+
Start your worker with:
64+
65+
```shell
66+
rq worker \
67+
-c mysettings \ # module name of mysettings.py
68+
--sentry-dsn="___PUBLIC_DSN___" # only necessary for RQ < 1.0
69+
```
70+
71+
The integration will automatically report errors from all RQ jobs.
72+
73+
Generally, make sure that the **call to `init` is loaded on worker startup**, and not only in the module where your jobs are defined. Otherwise, the initialization happens too late and events might end up not being reported.
74+
75+
In addition, make sure that **`init` is called only once** in your app. For example, if you have a `Flask` app and a worker that depends on the app, we recommend only initializing Sentry once. Note that because the Flask integration is enabled automatically, you don't need to change the configuration shown above.
76+
77+
78+
```python {filename:app.py}
79+
# app.py
80+
import sentry_sdk
81+
82+
sentry_sdk.init(
83+
dsn="___PUBLIC_DSN___",
84+
# Add data like request headers and IP for users, if applicable;
85+
# see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info
86+
send_default_pii=True,
87+
# ___PRODUCT_OPTION_START___ performance
88+
# Set traces_sample_rate to 1.0 to capture 100%
89+
# of transactions for tracing.
90+
traces_sample_rate=1.0,
91+
# ___PRODUCT_OPTION_END___ performance
92+
# ___PRODUCT_OPTION_START___ profiling
93+
# To collect profiles for all profile sessions,
94+
# set `profile_session_sample_rate` to 1.0.
95+
profile_session_sample_rate=1.0,
96+
# Profiles will be automatically collected while
97+
# there is an active span.
98+
profile_lifecycle="trace",
99+
# ___PRODUCT_OPTION_END___ profiling
100+
)
101+
```
102+
103+
The worker configuration `mysettings.py` then becomes:
104+
105+
```python {filename:mysettings.py}
106+
# mysettings.py
107+
# This import causes the Sentry SDK to be initialized
108+
import app
109+
```
110+
111+
## Verify
112+
113+
To verify, create a `main.py` script that enqueues a function in RQ, then start an RQ worker to run the function:
114+
115+
### Job definition:
116+
117+
```python {filename:jobs.py}
118+
# jobs.py
119+
def hello(name):
120+
1 / 0 # raises an error
121+
return f"Hello {name}!"
122+
```
123+
124+
### Settings for worker
125+
126+
```python {filename:mysettings.py}
127+
# mysettings.py
128+
import sentry_sdk
129+
130+
# Sentry configuration for RQ worker processes
131+
sentry_sdk.init(
132+
dsn="___PUBLIC_DSN___",
133+
# Add data like request headers and IP for users, if applicable;
134+
# see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info
135+
send_default_pii=True,
136+
# ___PRODUCT_OPTION_START___ performance
137+
# Set traces_sample_rate to 1.0 to capture 100%
138+
# of transactions for tracing.
139+
traces_sample_rate=1.0,
140+
# ___PRODUCT_OPTION_END___ performance
141+
# ___PRODUCT_OPTION_START___ profiling
142+
# To collect profiles for all profile sessions,
143+
# set `profile_session_sample_rate` to 1.0.
144+
profile_session_sample_rate=1.0,
145+
# Profiles will be automatically collected while
146+
# there is an active span.
147+
profile_lifecycle="trace",
148+
# ___PRODUCT_OPTION_END___ profiling
149+
)
150+
```
151+
152+
### Main Python Script
153+
154+
```python {filename:main.py}
155+
# main.py
156+
from redis import Redis
157+
from rq import Queue
158+
159+
from jobs import hello
160+
161+
import sentry_sdk
162+
163+
# Sentry configuration for main.py process
164+
sentry_sdk.init(
165+
dsn="___PUBLIC_DSN___",
166+
# Add data like request headers and IP for users, if applicable;
167+
# see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info
168+
send_default_pii=True,
169+
# ___PRODUCT_OPTION_START___ performance
170+
# Set traces_sample_rate to 1.0 to capture 100%
171+
# of transactions for tracing.
172+
traces_sample_rate=1.0,
173+
# ___PRODUCT_OPTION_END___ performance
174+
# ___PRODUCT_OPTION_START___ profiling
175+
# To collect profiles for all profile sessions,
176+
# set `profile_session_sample_rate` to 1.0.
177+
profile_session_sample_rate=1.0,
178+
# Profiles will be automatically collected while
179+
# there is an active span.
180+
profile_lifecycle="trace",
181+
# ___PRODUCT_OPTION_END___ profiling
182+
)
183+
184+
q = Queue(connection=Redis())
185+
with sentry_sdk.start_transaction(name="testing_sentry"):
186+
result = q.enqueue(hello, "World")
187+
```
188+
189+
When you run `python main.py` a transaction named `testing_sentry` will be created in the Performance section of [sentry.io](https://sentry.io) and spans for the enqueueing will be created.
190+
191+
If you run the RQ worker with `rq worker -c mysettings`, a transaction for the execution of `hello()` will be created. Additionally, an error event will be sent to [sentry.io](https://sentry.io) and will be connected to the transaction.
192+
193+
It takes a couple of moments for the data to appear in [sentry.io](https://sentry.io).
194+
195+
## The `--sentry-dsn` CLI option
196+
197+
Passing `--sentry-dsn=""` to RQ forcibly disables [RQ's shortcut for using Sentry](https://python-rq.org/patterns/sentry/). For RQ versions before 1.0 this is necessary to avoid conflicts, because back then RQ would attempt to use the `raven` package instead of this SDK. Since RQ 1.0 it's possible to use this CLI option and the associated RQ settings for initializing the SDK.
198+
199+
We still recommend against using those shortcuts because it would be harder to provide options to the SDK at a later point. See [the GitHub issue about RQ's Sentry integration](https://github.com/rq/rq/issues/1003) for discussion.
200+
201+
## Default Span Attributes
202+
203+
A set of predefined span attributes will be attached to RQ transactions by default. These can also be used for sampling since they will also be accessible via the `sampling_context` dictionary in the [`traces_sampler`](/platforms/python/configuration/options/#traces_sampler).
204+
205+
| Span Attribute | Description |
206+
| ---------------------------- | ------------------------------- |
207+
| `rq.job.args.{index}` | Positional job args, serialized |
208+
| `rq.job.kwargs.{kwarg}` | Keyword job args, serialized |
209+
| `rq.job.func` | Job `func`, serialized |
210+
| `messaging.destination.name` | Queue name |
211+
| `messaging.message.id` | Job ID |
212+
213+
These attributes will also be sent to Sentry. If you don't want that, you can filter them out using a custom [`before_send`](/platforms/python/configuration/options/#before_send) function.
214+
215+
## Supported Versions
216+
217+
- RQ: 0.6+
218+
- Python: 3.7+
219+
220+
<Include name="python-use-older-sdk-for-legacy-support.mdx" />

0 commit comments

Comments
 (0)