diff --git a/docs/platforms/python/index.mdx b/docs/platforms/python/index.mdx index c2203dd21b56d..6eb8d910f44e7 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 9e1522bf42dff..5d5b1df16d2bf 100644 --- a/docs/platforms/python/integrations/django/index.mdx +++ b/docs/platforms/python/integrations/django/index.mdx @@ -2,45 +2,52 @@ 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___", @@ -68,9 +75,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. + + + +### Issues + + + + + +To verify that Sentry captures errors and creates issues in your Sentry project, add this intentional error to your application: -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: + + ```python from django.urls import path @@ -84,35 +138,31 @@ 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,54 +190,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 0000000000000..451f98e83bfa3 --- /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 0000000000000..2447bc48de22b --- /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 0000000000000..ed2a5a3be9394 --- /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 e93c8a8051f11..457d7fe969f58 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 0000000000000..9eb6f0698eff2 --- /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 0000000000000..7fb779b7a08c7 --- /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 3ef1e8734745c..23e111ded923a 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/)