Skip to content

Commit 7a7fede

Browse files
sentrivanasentrivana
authored
feat(python): Document default span attrs in WSGI, update for 3.0 (#14367)
Document what span attributes will be attached to transactions by default by our builtin integrations. This PR updates WSGI. Rest will follow. I created a new 3.x page for this since it's new behavior in 3.0.
1 parent 12ae445 commit 7a7fede

File tree

2 files changed

+121
-1
lines changed

2 files changed

+121
-1
lines changed

‎docs/platforms/python/integrations/wsgi/index.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ app = SentryWsgiMiddleware(app)
6565

6666
## Verify
6767

68-
This minimal WSGI application will create a transaction and send it to Sentry. The error will also be sent to Sentry and associated with the transaction:
68+
This minimal WSGI application will create a transaction and send it to Sentry as long as you have tracing enabled. The error will also be sent to Sentry and associated with the transaction:
6969

7070
```python
7171
import sentry_sdk

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

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
title: WSGI
3+
description: "Learn about the WSGI integration and how it adds support for WSGI applications."
4+
---
5+
6+
If you use a WSGI framework not directly supported by the SDK, or you wrote a raw WSGI app, you can use this generic WSGI middleware. It captures errors and attaches a basic amount of information for incoming requests.
7+
8+
<Alert>
9+
10+
Please check our list of [supported integrations](/platforms/python/integrations/) as there might already be a specific integration (like [Django](/platforms/python/integrations/django/) or [Flask](/platforms/python/integrations/flask/)) that is easier to use and captures more useful information than our generic WSGI middleware. If that's the case, you should use the specific integration instead of this middleware.
11+
</Alert>
12+
13+
## Install
14+
15+
```bash {tabTitle:pip}
16+
pip install "sentry-sdk"
17+
```
18+
```bash {tabTitle:uv}
19+
uv add "sentry-sdk"
20+
```
21+
22+
## Configure
23+
24+
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/).
25+
26+
Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below.
27+
28+
<OnboardingOptionButtons
29+
options={[
30+
'error-monitoring',
31+
'performance',
32+
'profiling',
33+
]}
34+
/>
35+
36+
```python
37+
import sentry_sdk
38+
from sentry_sdk.integrations.wsgi import SentryWsgiMiddleware
39+
40+
from my_wsgi_app import app
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+
app = SentryWsgiMiddleware(app)
63+
```
64+
65+
## Verify
66+
67+
This minimal WSGI application will create a transaction and send it to Sentry as long as you have tracing enabled. The error will also be sent to Sentry and associated with the transaction:
68+
69+
```python
70+
import sentry_sdk
71+
from sentry_sdk.integrations.wsgi import SentryWsgiMiddleware
72+
73+
sentry_sdk.init(...) # same as above
74+
75+
def app(env, start_response):
76+
start_response('200 OK', [('Content-Type', 'text/plain')])
77+
response_body = 'Hello World'
78+
1 / 0 # this raises an error
79+
return [response_body.encode()]
80+
81+
app = SentryWsgiMiddleware(app)
82+
83+
# Run the application in a mini WSGI server.
84+
from wsgiref.simple_server import make_server
85+
make_server('', 8000, app).serve_forever()
86+
```
87+
88+
## Behavior
89+
90+
<Include name="python-uwsgi-warning.mdx" />
91+
92+
- Request data is attached to all events: **HTTP method, URL, headers**. Sentry excludes raw bodies and multipart file uploads. Sentry also excludes personally identifiable information (such as user IDs, usernames, cookies, authorization headers, IP addresses) unless you set `send_default_pii` to `True`.
93+
94+
Each request has a separate scope. Changes to the scope within a view, for example setting a tag, will only apply to events sent as part of the request being handled.
95+
96+
- The WSGI middleware does not behave like a regular integration. It is not initialized through an extra parameter to `init` and is not attached to a client. When capturing or supplementing events, it just uses the currently active scopes.
97+
98+
### Default Span Attributes
99+
100+
A set of predefined span attributes will be attached to WSGI 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).
101+
102+
| Span Attribute | Description |
103+
| ------------------------------------------------- | ---------------------------------------------------------- |
104+
| `url.path` | `PATH_INFO` from WSGI environ |
105+
| `url.query` | `QUERY_STRING` from WSGI environ |
106+
| `http.request.method` | `REQUEST_METHOD` from WSGI environ |
107+
| `server.address` | `SERVER_NAME` from WSGI environ |
108+
| `server.port` | `SERVER_PORT` from WSGI environ |
109+
| `server.protocol.name`, `server.protocol.version` | `SERVER_PROTOCOL` from WSGI environ |
110+
| `url.scheme` | `wsgi.url_scheme` from WSGI environ |
111+
| `url.full` | full URL, reconstructed from individual WSGI environ parts |
112+
| `http.request.header.{header}` | `HTTP_*` from WSGI environ |
113+
114+
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.
115+
116+
## Supported Versions
117+
118+
- Python: 3.7+
119+
120+
<Include name="python-use-older-sdk-for-legacy-support.mdx" />

0 commit comments

Comments
 (0)