From 6492566b6a6d32a39f0aec95472b8622b302a007 Mon Sep 17 00:00:00 2001 From: inventarSarah Date: Tue, 28 Jul 2026 11:16:27 +0200 Subject: [PATCH 1/9] update Django quick start guide and create some includes --- docs/platforms/python/index.mdx | 101 +--------- .../python/integrations/django/index.mdx | 188 ++++++++++++------ ...on-quick-start-verify-logs-splitlayout.mdx | 21 ++ ...quick-start-verify-metrics-splitlayout.mdx | 23 +++ includes/python-quick-start-shell-warning.mdx | 5 + includes/python-uwsgi-warning.mdx | 6 +- ...quick-start-verify-tracing-splitlayout.mdx | 22 ++ .../getting-started-install/python.mdx | 24 +++ .../getting-started-next-steps/python.mdx | 10 +- 9 files changed, 240 insertions(+), 160 deletions(-) create mode 100644 includes/logs/python-quick-start-verify-logs-splitlayout.mdx create mode 100644 includes/metrics/python-quick-start-verify-metrics-splitlayout.mdx create mode 100644 includes/python-quick-start-shell-warning.mdx create mode 100644 includes/tracing/python-quick-start-verify-tracing-splitlayout.mdx create mode 100644 platform-includes/getting-started-install/python.mdx diff --git a/docs/platforms/python/index.mdx b/docs/platforms/python/index.mdx index c2203dd21b56db..6eb8d910f44e7d 100644 --- a/docs/platforms/python/index.mdx +++ b/docs/platforms/python/index.mdx @@ -24,30 +24,7 @@ This guide focuses on plain Python. If you're working with Django, FastAPI, Star ## Install - - - - -Run the command for your preferred package manager to add the Sentry SDK to your application: - - - - -```bash {tabTitle:pip} -pip install "sentry-sdk" -``` - -```bash {tabTitle:uv} -uv add "sentry-sdk" -``` - -```bash {tabTitle:poetry} -poetry add "sentry-sdk" -``` - - - - + ## Configure @@ -180,11 +157,7 @@ def some_function(): Let's test your setup and confirm that data reaches your Sentry project. - - -Errors triggered from a Python shell like IPython will not trigger Sentry's error monitoring. Make sure you're running the examples from a file instead. - - + ### Issues @@ -209,83 +182,19 @@ division_by_zero = 1 / 0 -### Tracing - - - - - -To test your tracing configuration, create a custom transaction and span: - - - - -```py -import sentry_sdk - -with sentry_sdk.start_transaction(op="task", name="Transaction Name"): - span = sentry_sdk.start_span(name="Custom Span Name") - span.finish() -``` - - - - + -### Logs - - - - - -To verify that Sentry catches your logs, add some log statements to your application: - - - - -```py -import sentry_sdk - -sentry_sdk.logger.info("This is an info log message") -sentry_sdk.logger.warning("This is a warning message") -sentry_sdk.logger.error("This is an error message") -``` - - - - + -### Metrics - - - - - -Send test metrics from your app to verify metrics are arriving in Sentry: - - - - -```py -from sentry_sdk import metrics - -metrics.count("checkout.failed", 1) -metrics.gauge("queue.depth", 42) -metrics.distribution("cart.amount_usd", 187.5) - -``` - - - - + diff --git a/docs/platforms/python/integrations/django/index.mdx b/docs/platforms/python/integrations/django/index.mdx index 36844cffd53870..76bfc183f9107a 100644 --- a/docs/platforms/python/integrations/django/index.mdx +++ b/docs/platforms/python/integrations/django/index.mdx @@ -2,43 +2,54 @@ title: Django caseStyle: snake_case supportLevel: production -description: "Learn about using Sentry with Django." +description: "Learn how to set up Sentry in your Django app, capture your first errors and traces, and view them in Sentry." --- -Sentry's [Django](https://www.djangoproject.com/) integration adds support for the Django framework. It enables automatic reporting of errors and exceptions as well as tracing. In order to get started using the integration, you should have a [Sentry account](https://sentry.io) and a project set up. +## Prerequisites - +You need: -If you're using Python 3.7, Django applications with `channels` 2.0 will be correctly instrumented. Older versions of Python will require the installation of [aiocontextvars](https://pypi.org/project/aiocontextvars/). +- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) +- Your application up and running +- Django `1.8+` +- Python `3.6+` - + ## Install -Install `sentry-sdk` from PyPI: - -```bash {tabTitle:pip} -pip install sentry-sdk -``` - -```bash {tabTitle:uv} -uv add sentry-sdk -``` + ## Configure Choose the features you want to configure, and this guide will show you how: + + +### Initialize the Sentry SDK + +Configuration should happen as **early as possible** in your application's lifecycle. + + + + + To configure the Sentry SDK, initialize it in your `settings.py` file: + + + ```python {filename:settings.py} import sentry_sdk +# ___PRODUCT_OPTION_START___ metrics +from sentry_sdk import metrics +# ___PRODUCT_OPTION_END___ metrics sentry_sdk.init( dsn="___PUBLIC_DSN___", @@ -66,9 +77,56 @@ sentry_sdk.init( ) ``` -## Verify + + + + +To further customize your setup, review the [Options section](#options) below. + +### Capturing Errors + +Sentry automatically captures errors and reports issues for you. +You can also expect the following for your Django project: + +- If you use `django.contrib.auth`, and you've set `send_default_pii=True` in your call to `init`, user data (such as current user ID, email address, username) will be attached to error events. +- Request data will be attached to all events: **HTTP method, URL, headers, form data, JSON payloads**. Sentry excludes raw bodies and multipart file uploads. +- Logs emitted by any logger will be recorded as breadcrumbs by the [Logging](/platforms/python/integrations/logging/) integration (this integration is enabled by default). + +To learn how to manually report issues, see Capturing Errors. + + +### Instrumenting Your App + + + +The Sentry SDK automatically monitors the following parts of your Django project: + +- Middleware stack +- Signals +- Database queries +- Redis commands +- Access to Django caches + +You can also manually capture performance data – see Custom Instrumentation to learn more. + + + +## Verify Your Setup + +Let's test your setup and confirm that data reaches your Sentry project. -The snippet below includes an intentional error that will be captured by Sentry when triggered. This will allow you to make sure that everything is working as soon as you set it up: + + +### Issues + + + + + +To verify that Sentry captures errors and creates issues in your Sentry project, add this intentional error to your application: + + + ```python from django.urls import path @@ -82,37 +140,35 @@ urlpatterns = [ ] ``` -## Behavior + + + - + -### Issue Reporting + -- If you use `django.contrib.auth` and you've set `send_default_pii=True` in your call to `init`, user data (such as current user id, email address, username) will be attached to error events. -- Request data will be attached to all events: **HTTP method, URL, headers, form data, JSON payloads**. Sentry excludes raw bodies and multipart file uploads. -- Logs emitted by any logger will be recorded as breadcrumbs by the [Logging](/platforms/python/integrations/logging/) integration (this integration is enabled by default). + -### Tracing + -The following parts of your Django project are monitored: + -- Middleware stack -- Signals -- Database queries -- Redis commands -- Access to Django caches + - + -The parameter [traces_sample_rate](/platforms/python/configuration/options/#traces-sample-rate) needs to be set when initializing the Sentry SDK for performance measurements to be recorded. + - + ## Options -By adding `DjangoIntegration` explicitly to your `sentry_sdk.init()` call you can set options for `DjangoIntegration` to change its behavior: + + +Add `DjangoIntegration` explicitly to your `sentry_sdk.init()` call to set options for `DjangoIntegration` to change its behavior: ```python import django.db.models.signals @@ -140,51 +196,63 @@ sentry_sdk.init( You can pass the following keyword arguments to `DjangoIntegration()`: -- `transaction_style`: + + +How to name transactions that show up in Sentry tracing. + +- `"/myproject/myview/"` if you set `transaction_style="url"`. +- `"myproject.myview"` if you set `transaction_style="function_name"`. + +The default is `"url"`. + + - How to name transactions that show up in Sentry tracing. - - `"/myproject/myview/"` if you set `transaction_style="url"`. - - `"myproject.myview"` if you set `transaction_style="function_name"`. + - The default is `"url"`. +Create spans and track performance of all middleware layers in your Django project. Set to `True` to enable. +The default is `False`. -- `middleware_spans`: + - Create spans and track performance of all middleware layers in your Django project. Set to `True` to enable. + - The default is `False`. +Create spans and track performance of all synchronous [Django signals](https://docs.djangoproject.com/en/dev/topics/signals/) receiver functions in your Django project. Set to `False` to disable. +The default is `True`. -- `signals_spans`: + - Create spans and track performance of all synchronous [Django signals](https://docs.djangoproject.com/en/dev/topics/signals/) receiver functions in your Django project. Set to `False` to disable. + - The default is `True`. +A list of signals to exclude from performance tracking. No spans will be created for these. +The default is `[]`. -- `signals_denylist`: + - A list of signals to exclude from performance tracking. No spans will be created for these. + - The default is `[]`. +Create spans and track performance of all read operations to configured caches. The spans also include information if the cache access was a hit or a miss. Set to `True` to enable. +The default is `False`. -- `cache_spans`: + - Create spans and track performance of all read operations to configured caches. The spans also include information if the cache access was a hit or a miss. Set to `True` to enable. + - The default is `False`. +A tuple containing all the HTTP methods (as uppercase strings) that should create a transaction in Sentry. +The default is `("CONNECT", "DELETE", "GET", "PATCH", "POST", "PUT", "TRACE",)`. -- `http_methods_to_capture`: +Note that `OPTIONS` and `HEAD` are excluded by default. - A tuple containing all the HTTP methods that should create a transaction in Sentry. + - The default is `("CONNECT", "DELETE", "GET", "PATCH", "POST", "PUT", "TRACE",)`. +## Next Steps - (Note that `OPTIONS` and `HEAD` are missing by default.) + - The `http_methods_to_capture` option. + -## Supported Versions +- Find various topics in Troubleshooting +- [Get support](https://www.sentry.help/en/) -- Django 1.8+ -- Python 3.6+ + - + diff --git a/includes/logs/python-quick-start-verify-logs-splitlayout.mdx b/includes/logs/python-quick-start-verify-logs-splitlayout.mdx new file mode 100644 index 00000000000000..451f98e83bfa3c --- /dev/null +++ b/includes/logs/python-quick-start-verify-logs-splitlayout.mdx @@ -0,0 +1,21 @@ +### Logs + + + + +To verify that Sentry catches your logs, add some log statements to your application: + + + + + +```python +import sentry_sdk +sentry_sdk.logger.info("This is an info log message") +sentry_sdk.logger.warning("This is a warning message") +sentry_sdk.logger.error("This is an error message") +``` + + + + diff --git a/includes/metrics/python-quick-start-verify-metrics-splitlayout.mdx b/includes/metrics/python-quick-start-verify-metrics-splitlayout.mdx new file mode 100644 index 00000000000000..2447bc48de22b5 --- /dev/null +++ b/includes/metrics/python-quick-start-verify-metrics-splitlayout.mdx @@ -0,0 +1,23 @@ +### Metrics + + + + + +Send test metrics from your app to verify metrics are arriving in Sentry: + + + + +```py +from sentry_sdk import metrics + +metrics.count("checkout.failed", 1) +metrics.gauge("queue.depth", 42) +metrics.distribution("cart.amount_usd", 187.5) + +``` + + + + diff --git a/includes/python-quick-start-shell-warning.mdx b/includes/python-quick-start-shell-warning.mdx new file mode 100644 index 00000000000000..ed2a5a3be9394b --- /dev/null +++ b/includes/python-quick-start-shell-warning.mdx @@ -0,0 +1,5 @@ + + +Errors triggered from a Python shell like IPython will not trigger Sentry's error monitoring. Make sure you're running the examples from a file instead. + + diff --git a/includes/python-uwsgi-warning.mdx b/includes/python-uwsgi-warning.mdx index e93c8a8051f11f..457d7fe969f583 100644 --- a/includes/python-uwsgi-warning.mdx +++ b/includes/python-uwsgi-warning.mdx @@ -1,9 +1,9 @@ - + If you're using uWSGI, note that it doesn't support threads by default. This might lead to unexpected behavior when using the Sentry SDK, from features not working properly to uWSGI workers crashing. To enable threading support in uWSGI, make sure you have both `--enable-threads` and `--py-call-uwsgi-fork-hooks` on. -Note that automatic tracing on file-like responses when `offloading` is configured is disabled (see [here](https://github.com/getsentry/sentry-python/pull/5556) for why). If you wish to enable tracing on these types of responses, you will need to manually instrument them. +Note that automatic tracing on file-like responses when `offloading` is configured is disabled (see [here](https://github.com/getsentry/sentry-python/pull/5556) for why). If you wish to enable tracing on these types of responses, you will need to manually instrument them. - + diff --git a/includes/tracing/python-quick-start-verify-tracing-splitlayout.mdx b/includes/tracing/python-quick-start-verify-tracing-splitlayout.mdx new file mode 100644 index 00000000000000..9eb6f0698eff25 --- /dev/null +++ b/includes/tracing/python-quick-start-verify-tracing-splitlayout.mdx @@ -0,0 +1,22 @@ +### Tracing + + + + + +To test your tracing configuration, create a custom transaction and span: + + + + +```py +import sentry_sdk + +with sentry_sdk.start_transaction(op="task", name="Transaction Name"): + span = sentry_sdk.start_span(name="Custom Span Name") + span.finish() +``` + + + + diff --git a/platform-includes/getting-started-install/python.mdx b/platform-includes/getting-started-install/python.mdx new file mode 100644 index 00000000000000..7fb779b7a08c7c --- /dev/null +++ b/platform-includes/getting-started-install/python.mdx @@ -0,0 +1,24 @@ + + + + +Run the command for your preferred package manager to add the Sentry SDK to your application: + + + + +```bash {tabTitle:pip} +pip install "sentry-sdk" +``` + +```bash {tabTitle:uv} +uv add "sentry-sdk" +``` + +```bash {tabTitle:poetry} +poetry add "sentry-sdk" +``` + + + + diff --git a/platform-includes/getting-started-next-steps/python.mdx b/platform-includes/getting-started-next-steps/python.mdx index 3ef1e8734745c4..23e111ded923a7 100644 --- a/platform-includes/getting-started-next-steps/python.mdx +++ b/platform-includes/getting-started-next-steps/python.mdx @@ -1 +1,9 @@ -- [_integrating with the Python ecosystem_](/platforms/python/) +At this point, you should have integrated Sentry into your application and should already be sending data to your Sentry project. + +Now's a good time to customize your setup and look into more advanced topics. +Our next recommended steps for you are: + +- Explore [practical guides](/guides/) on what to monitor, log, track, and investigate after setup +- Continue to customize your configuration +- Learn more about manually capturing errors or messages +- Dive straight into the API with our [API docs](https://getsentry.github.io/sentry-python/) From fa1a0e4a835ba8452b1ce3df8b4243805d99ad11 Mon Sep 17 00:00:00 2001 From: inventarSarah Date: Tue, 11 Aug 2026 08:44:17 +0200 Subject: [PATCH 2/9] finalize docs update --- docs/platforms/python/integrations/django/index.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/platforms/python/integrations/django/index.mdx b/docs/platforms/python/integrations/django/index.mdx index 76bfc183f9107a..4e32407c0aa606 100644 --- a/docs/platforms/python/integrations/django/index.mdx +++ b/docs/platforms/python/integrations/django/index.mdx @@ -5,6 +5,8 @@ supportLevel: production description: "Learn how to set up Sentry in your Django app, capture your first errors and traces, and view them in Sentry." --- + + ## Prerequisites You need: @@ -16,8 +18,6 @@ You need: - - ## Install @@ -166,8 +166,6 @@ urlpatterns = [ - - Add `DjangoIntegration` explicitly to your `sentry_sdk.init()` call to set options for `DjangoIntegration` to change its behavior: ```python From 5c916b140329018c567a4eb94db2eac57226a876 Mon Sep 17 00:00:00 2001 From: inventarSarah Date: Tue, 11 Aug 2026 09:54:51 +0200 Subject: [PATCH 3/9] add view in Sentry section --- docs/platforms/python/integrations/django/index.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/platforms/python/integrations/django/index.mdx b/docs/platforms/python/integrations/django/index.mdx index 4e32407c0aa606..5b6a2954d009db 100644 --- a/docs/platforms/python/integrations/django/index.mdx +++ b/docs/platforms/python/integrations/django/index.mdx @@ -162,6 +162,12 @@ urlpatterns = [ +### View Captured Data in Sentry + +Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear). + + + ## Options From be1af7d13bfdfdffc62548811d6e479ebc61991d Mon Sep 17 00:00:00 2001 From: inventarSarah Date: Tue, 11 Aug 2026 12:11:16 +0200 Subject: [PATCH 4/9] add back python 3.7 note --- docs/platforms/python/integrations/django/index.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/platforms/python/integrations/django/index.mdx b/docs/platforms/python/integrations/django/index.mdx index 5b6a2954d009db..96aaacc28089d0 100644 --- a/docs/platforms/python/integrations/django/index.mdx +++ b/docs/platforms/python/integrations/django/index.mdx @@ -16,6 +16,12 @@ You need: - Django `1.8+` - Python `3.6+` + + +If you're using Python 3.7, Django applications with `channels` 2.0 will be correctly instrumented. Older versions of Python will require the installation of [aiocontextvars](https://pypi.org/project/aiocontextvars/). + + + ## Install From cc6db0dcdf0df6ff2498094ee254c9bc4a02132d Mon Sep 17 00:00:00 2001 From: Sarah Mischinger Date: Tue, 11 Aug 2026 12:12:46 +0200 Subject: [PATCH 5/9] Update includes/logs/python-quick-start-verify-logs-splitlayout.mdx Co-authored-by: Ivana Kellyer --- includes/logs/python-quick-start-verify-logs-splitlayout.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/includes/logs/python-quick-start-verify-logs-splitlayout.mdx b/includes/logs/python-quick-start-verify-logs-splitlayout.mdx index 451f98e83bfa3c..01a92c96a54ae1 100644 --- a/includes/logs/python-quick-start-verify-logs-splitlayout.mdx +++ b/includes/logs/python-quick-start-verify-logs-splitlayout.mdx @@ -11,6 +11,7 @@ To verify that Sentry catches your logs, add some log statements to your applica ```python import sentry_sdk + sentry_sdk.logger.info("This is an info log message") sentry_sdk.logger.warning("This is a warning message") sentry_sdk.logger.error("This is an error message") From c5be6feb2fa0e2576efa52e6687eae69ea7c19f6 Mon Sep 17 00:00:00 2001 From: Sarah Mischinger Date: Tue, 11 Aug 2026 12:12:56 +0200 Subject: [PATCH 6/9] Update includes/metrics/python-quick-start-verify-metrics-splitlayout.mdx Co-authored-by: Ivana Kellyer --- .../metrics/python-quick-start-verify-metrics-splitlayout.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/includes/metrics/python-quick-start-verify-metrics-splitlayout.mdx b/includes/metrics/python-quick-start-verify-metrics-splitlayout.mdx index 2447bc48de22b5..f3a5bccaf7e863 100644 --- a/includes/metrics/python-quick-start-verify-metrics-splitlayout.mdx +++ b/includes/metrics/python-quick-start-verify-metrics-splitlayout.mdx @@ -15,7 +15,6 @@ from sentry_sdk import metrics metrics.count("checkout.failed", 1) metrics.gauge("queue.depth", 42) metrics.distribution("cart.amount_usd", 187.5) - ``` From 25fb007196a00d6338c7b63bbd79f2e4932c3fd6 Mon Sep 17 00:00:00 2001 From: inventarSarah Date: Thu, 13 Aug 2026 08:48:29 +0200 Subject: [PATCH 7/9] remove enableLogs --- docs/platforms/python/integrations/django/index.mdx | 7 +------ .../logs/python-quick-start-verify-logs-splitlayout.mdx | 2 +- includes/quick-start-features-expandable.mdx | 2 +- 3 files changed, 3 insertions(+), 8 deletions(-) diff --git a/docs/platforms/python/integrations/django/index.mdx b/docs/platforms/python/integrations/django/index.mdx index 96aaacc28089d0..5d61e48f8767b2 100644 --- a/docs/platforms/python/integrations/django/index.mdx +++ b/docs/platforms/python/integrations/django/index.mdx @@ -33,7 +33,7 @@ If you're using Python 3.7, Django applications with `channels` 2.0 will be corr Choose the features you want to configure, and this guide will show you how: @@ -75,11 +75,6 @@ sentry_sdk.init( # there is an active span. profile_lifecycle="trace", # ___PRODUCT_OPTION_END___ profiling - # ___PRODUCT_OPTION_START___ logs - - # Enable logs to be sent to Sentry - enable_logs=True, - # ___PRODUCT_OPTION_END___ logs ) ``` diff --git a/includes/logs/python-quick-start-verify-logs-splitlayout.mdx b/includes/logs/python-quick-start-verify-logs-splitlayout.mdx index 01a92c96a54ae1..4b62cc00047970 100644 --- a/includes/logs/python-quick-start-verify-logs-splitlayout.mdx +++ b/includes/logs/python-quick-start-verify-logs-splitlayout.mdx @@ -3,7 +3,7 @@ -To verify that Sentry catches your logs, add some log statements to your application: +To verify that Sentry catches your logs (which are enabled by default), add some log statements to your application: diff --git a/includes/quick-start-features-expandable.mdx b/includes/quick-start-features-expandable.mdx index be0cf30e3ebb71..373a9472625cbd 100644 --- a/includes/quick-start-features-expandable.mdx +++ b/includes/quick-start-features-expandable.mdx @@ -53,7 +53,7 @@ import { FeatureInfo } from "sentry-docs/components/featureInfo"; From 4142c521fa14cc8a6c3059c961d305038a4050c2 Mon Sep 17 00:00:00 2001 From: inventarSarah Date: Thu, 13 Aug 2026 09:15:39 +0200 Subject: [PATCH 8/9] pr review fixes --- docs/platforms/python/integrations/django/index.mdx | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/platforms/python/integrations/django/index.mdx b/docs/platforms/python/integrations/django/index.mdx index 5d61e48f8767b2..6c161b317fe9ae 100644 --- a/docs/platforms/python/integrations/django/index.mdx +++ b/docs/platforms/python/integrations/django/index.mdx @@ -151,12 +151,8 @@ urlpatterns = [ - - - - @@ -219,7 +215,7 @@ The default is `False`. - + Create spans and track performance of all synchronous [Django signals](https://docs.djangoproject.com/en/dev/topics/signals/) receiver functions in your Django project. Set to `False` to disable. The default is `True`. From 194ab122941344fbf79618e578eb091f1d0b3a8d Mon Sep 17 00:00:00 2001 From: inventarSarah Date: Mon, 17 Aug 2026 11:00:03 +0200 Subject: [PATCH 9/9] add back logs to onboarding options to toggle verify logs code block --- docs/platforms/python/integrations/django/index.mdx | 6 +++++- includes/quick-start-features-expandable.mdx | 2 +- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/platforms/python/integrations/django/index.mdx b/docs/platforms/python/integrations/django/index.mdx index 6c161b317fe9ae..2644651231f394 100644 --- a/docs/platforms/python/integrations/django/index.mdx +++ b/docs/platforms/python/integrations/django/index.mdx @@ -33,7 +33,7 @@ If you're using Python 3.7, Django applications with `channels` 2.0 will be corr Choose the features you want to configure, and this guide will show you how: @@ -151,8 +151,12 @@ urlpatterns = [ + + + + diff --git a/includes/quick-start-features-expandable.mdx b/includes/quick-start-features-expandable.mdx index 373a9472625cbd..be0cf30e3ebb71 100644 --- a/includes/quick-start-features-expandable.mdx +++ b/includes/quick-start-features-expandable.mdx @@ -53,7 +53,7 @@ import { FeatureInfo } from "sentry-docs/components/featureInfo";