diff --git a/docs/platforms/python/index.mdx b/docs/platforms/python/index.mdx index 245773b8724b1..871d81a8f54aa 100644 --- a/docs/platforms/python/index.mdx +++ b/docs/platforms/python/index.mdx @@ -1,6 +1,6 @@ --- title: Python -description: Learn how to set up Sentry in your Python app, capture your first errors and traces, and view them in Sentry. +description: Learn how to set up Sentry in your Python app, capture your first events and traces, and view them in Sentry. caseStyle: snake_case supportLevel: production sdk: sentry.python @@ -26,13 +26,12 @@ This guide focuses on plain Python. If you're working with Django, FastAPI, Star -## Configure +This guide requires `sentry-sdk` version 2.70.0 or later. If you already have the SDK installed, upgrade it with `pip install --upgrade sentry-sdk`. -Choose the features you want to configure, and this guide will show you how: +## Configure - +**Error Monitoring** starts working as soon as you call `sentry_sdk.init()`. **Logs** and **Application Metrics** need no extra configuration when using `sentry_sdk.logger` and `sentry_sdk.metrics`, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing** and **Profiling**. @@ -42,12 +41,16 @@ Configuration should happen as **early as possible** in your application's lifec Import and initialize the SDK in your app's entry point: +The snippet also turns on: + +- Collection of user data, such as the user's IP address: via `data_collection` +- Tracing: via `traces_sample_rate` +- Profiling: via `profile_session_sample_rate` and `profile_lifecycle` + +Don't need a feature? Remove its options from the snippet. + ```python import sentry_sdk -# ___PRODUCT_OPTION_START___ metrics -from sentry_sdk import metrics -# ___PRODUCT_OPTION_END___ metrics - sentry_sdk.init( dsn="___PUBLIC_DSN___", @@ -55,48 +58,36 @@ sentry_sdk.init( data_collection={ "user_info": True, }, - # ___PRODUCT_OPTION_START___ performance - # Set traces_sample_rate to 1.0 to capture 100% - # of transactions for tracing. - # see https://docs.sentry.io/platforms/python/configuration/options/#traces_sample_rate for more info + # Enables Tracing. + # Set to 1.0 to capture 100% of spans for tracing. + # We recommend reducing this value in production. traces_sample_rate=1.0, - # ___PRODUCT_OPTION_END___ performance - # ___PRODUCT_OPTION_START___ profiling - # Enables continuous profiling. - # To collect profiles for all profile sessions, - # set `profile_session_sample_rate` to 1.0. - # see https://docs.sentry.io/platforms/python/configuration/options/#profile_session_sample_rate for more info + # Enables Profiling. + # Set to 1.0 to profile 100% of sessions. profile_session_sample_rate=1.0, - - # Profiles will be automatically collected while - # there is an active span. - # see https://docs.sentry.io/platforms/python/configuration/options/#profile_lifecycle for more info + # Profiles are collected while a transaction is active. profile_lifecycle="trace", - # ___PRODUCT_OPTION_END___ profiling ) ``` -In async programs, we recommend to initialize the Sentry SDK inside an `async` function to ensure async code is instrumented properly. If possible, call `sentry_sdk.init()` at the beginning of the first `async` function you call: +In async programs, add the `AsyncioIntegration` to instrument your async code. This integration isn't enabled by default. Call `sentry_sdk.init()` at the beginning of the first `async` function you call: ```python import asyncio import sentry_sdk -# ___PRODUCT_OPTION_START___ metrics -from sentry_sdk import metrics -# ___PRODUCT_OPTION_END___ metrics - +from sentry_sdk.integrations.asyncio import AsyncioIntegration async def main(): sentry_sdk.init( - ... # same as above + ..., # same options as above + integrations=[AsyncioIntegration()], ) asyncio.run(main()) ``` - ### Instrumenting Your App The Sentry SDK automatically enables integrations for many popular libraries, so operations like HTTP requests or database queries made with supported libraries will be captured as spans automatically. @@ -113,41 +104,55 @@ def some_function(): ... ``` - +## Send Logs -## Verify Your Setup +Use `sentry_sdk.logger` to send structured logs at different levels. You can include searchable attributes with each message. -Let's test your setup and confirm that data reaches your Sentry project. +To capture records from Python's standard-library `logging` module or Loguru, configure `capture_sentry_logs=True` on the corresponding integration. See the standard logging and Loguru integration guides. - +See Set Up Logs for all available logging methods and formatting options. -### Issues +```python +import sentry_sdk -To verify that Sentry captures errors and creates issues in your Sentry project, add this intentional error to your application: +sentry_sdk.logger.info("Order processed {order_id}", order_id="order-123") +sentry_sdk.logger.warning("Rate limit reached", attributes={"endpoint": "/api/orders"}) +``` -```py +## Send Application Metrics + +Use `sentry_sdk.metrics` to send counters, gauges, and distributions from your app. Metrics are enabled by default after you initialize the SDK. + +See Set Up Metrics for all available metric types and configuration options. + +```python import sentry_sdk -division_by_zero = 1 / 0 +sentry_sdk.metrics.count("checkout.failed", 1) +sentry_sdk.metrics.gauge("active_connections", 42) +sentry_sdk.metrics.distribution("api_latency", 187, unit="millisecond") ``` - - - +## Verify Your Setup - +Let's test your setup and confirm that data reaches your Sentry project. - +Run this code after `sentry_sdk.init()` to send a test error, along with a trace, a log, and a metric: - +```python +import sentry_sdk - +with sentry_sdk.start_transaction(op="test", name="Verify Sentry setup"): + sentry_sdk.logger.info("Sentry verification log") + sentry_sdk.metrics.count("sentry.verification", 1) + 1 / 0 +``` - + - +The SDK sends profiles after a transaction finishes, so a script that exits right away, like the one above, might not send a profile. Profiles appear for applications that keep running after their transactions complete. - + ### View Captured Data in Sentry @@ -157,15 +162,11 @@ Now, head over to your project on [Sentry.io](https://sentry.io) to view the col ## Next Steps -At this point, you should have integrated Sentry into your Python 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: +At this point, you should have integrated Sentry into your Python application. Here's what to explore next: - Explore [practical guides](/get-started/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/) +- Set up Agent Tracing to monitor your AI systems +- Learn how to manually capture errors diff --git a/docs/platforms/python/integrations/celery/index.mdx b/docs/platforms/python/integrations/celery/index.mdx index e8aac80935497..74f6d04882f84 100644 --- a/docs/platforms/python/integrations/celery/index.mdx +++ b/docs/platforms/python/integrations/celery/index.mdx @@ -1,6 +1,6 @@ --- title: Celery -description: "Learn how to set up Sentry in your Celery app, capture your first errors and traces, and view them in Sentry." +description: "Learn how to set up Sentry in your Celery app, capture your first events and traces, and view them in Sentry." --- @@ -24,13 +24,12 @@ You need: -## Configure +This guide requires `sentry-sdk` version 2.70.0 or later. If you already have the SDK installed, upgrade it with `pip install --upgrade sentry-sdk`. -Choose the features you want to configure, and this guide will show you how: +## Configure - +**Error Monitoring** starts working as soon as you call `sentry_sdk.init()`. **Logs** and **Application Metrics** need no extra configuration when using `sentry_sdk.logger` and `sentry_sdk.metrics`, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing** and **Profiling**. @@ -38,6 +37,14 @@ Choose the features you want to configure, and this guide will show you how: Configuration should happen as **early as possible** in your application's lifecycle. +The init snippets also turn on: + +- Collection of task arguments in error events: via `data_collection` +- Tracing: via `traces_sample_rate` +- Profiling: via `profile_session_sample_rate` and `profile_lifecycle` + +Don't need a feature? Remove its options from the snippets. + If you have the `celery` package in your dependencies, the Celery integration will be enabled automatically when you initialize the Sentry SDK. @@ -55,9 +62,6 @@ When using Celery without Django, you'll need to initialize the Sentry SDK in bo ```python {filename:tasks.py} from celery import Celery, signals import sentry_sdk -# ___PRODUCT_OPTION_START___ metrics -from sentry_sdk import metrics -# ___PRODUCT_OPTION_END___ metrics # Initializing Celery app = Celery("tasks", broker="...") @@ -71,19 +75,15 @@ def init_sentry(**_kwargs): data_collection={ "queues": True, }, - # ___PRODUCT_OPTION_START___ performance - # Set traces_sample_rate to 1.0 to capture 100% - # of transactions for tracing. + # Enables Tracing. + # Set to 1.0 to capture 100% of spans for tracing. + # We recommend reducing this value in production. traces_sample_rate=1.0, - # ___PRODUCT_OPTION_END___ performance - # ___PRODUCT_OPTION_START___ profiling - # To collect profiles for all profile sessions, - # set `profile_session_sample_rate` to 1.0. + # Enables Profiling. + # Set to 1.0 to profile 100% of sessions. profile_session_sample_rate=1.0, - # Profiles will be automatically collected while - # there is an active span. + # Profiles are collected while a transaction is active. profile_lifecycle="trace", - # ___PRODUCT_OPTION_END___ profiling ) # Task definitions go here @@ -99,9 +99,6 @@ The [`celeryd_init`](https://docs.celeryq.dev/en/stable/userguide/signals.html?# ```python {filename:main.py} from tasks import add import sentry_sdk -# ___PRODUCT_OPTION_START___ metrics -from sentry_sdk import metrics -# ___PRODUCT_OPTION_END___ metrics def main(): # Initializing Sentry SDK in our process @@ -111,19 +108,15 @@ def main(): data_collection={ "queues": True, }, - # ___PRODUCT_OPTION_START___ performance - # Set traces_sample_rate to 1.0 to capture 100% - # of transactions for tracing. + # Enables Tracing. + # Set to 1.0 to capture 100% of spans for tracing. + # We recommend reducing this value in production. traces_sample_rate=1.0, - # ___PRODUCT_OPTION_END___ performance - # ___PRODUCT_OPTION_START___ profiling - # To collect profiles for all profile sessions, - # set `profile_session_sample_rate` to 1.0. + # Enables Profiling. + # Set to 1.0 to profile 100% of sessions. profile_session_sample_rate=1.0, - # Profiles will be automatically collected while - # there is an active span. + # Profiles are collected while a transaction is active. profile_lifecycle="trace", - # ___PRODUCT_OPTION_END___ profiling ) # Enqueueing a task to be processed by Celery @@ -147,7 +140,6 @@ Sentry automatically captures errors and exceptions raised in your Celery tasks To learn how to manually report issues, see Capturing Errors. - ### Instrumenting Your App The Sentry SDK automatically creates spans for your Celery tasks, and propagates the trace from the code that enqueues a task to the worker that runs it. @@ -198,52 +190,46 @@ my_task_b.apply_async( # Note: overriding the tracing behaviour using `task_x.delay()` is not possible. ``` - - -## Verify Your Setup +## Send Logs -Let's test your setup and confirm that data reaches your Sentry project. +Use `sentry_sdk.logger` to send structured logs at different levels. You can include searchable attributes with each message. -### Issues +To capture records from Python's standard-library `logging` module or Loguru, configure `capture_sentry_logs=True` on the corresponding integration. See the standard logging and Loguru integration guides. -To verify that Sentry captures errors and creates issues in your Sentry project, add this intentional error to your application: +See Set Up Logs for all available logging methods and formatting options. -```python {filename:tasks.py} -from celery import Celery, signals +```python import sentry_sdk -app = Celery("tasks", broker="...") - -@signals.celeryd_init.connect -def init_sentry(**_kwargs): - sentry_sdk.init(...) # same as above - -@app.task -def debug_sentry(): - 1/0 +sentry_sdk.logger.info("Order processed {order_id}", order_id="order-123") +sentry_sdk.logger.warning("Rate limit reached", attributes={"endpoint": "/api/orders"}) ``` -Trigger the error by calling `debug_sentry.delay()`. - -To confirm that your SDK is initialized on worker start, pass `debug=True` to `sentry_sdk.init()`. This will add extra output to your Celery logs when the SDK is initialized. If you see the output during worker startup, and not just after a task has started, then it's working correctly. - - +## Send Application Metrics - +Use `sentry_sdk.metrics` to send counters, gauges, and distributions from your app. Metrics are enabled by default after you initialize the SDK. - +See Set Up Metrics for all available metric types and configuration options. - +```python +import sentry_sdk - +sentry_sdk.metrics.count("checkout.failed", 1) +sentry_sdk.metrics.gauge("active_connections", 42) +sentry_sdk.metrics.distribution("api_latency", 187, unit="millisecond") +``` - +## Verify Your Setup - +Let's test your setup and confirm that data reaches your Sentry project. - +Add a task that raises an exception, then call `debug_sentry.delay()` from a running Celery worker: - +```python +@app.task +def debug_sentry(): + 1 / 0 +``` ### View Captured Data in Sentry @@ -286,12 +272,8 @@ If this is set to `False`: - errors in Celery tasks won't be matched to the triggering function. - your Celery tasks will start a new trace and won't be connected to the trace in the calling function. - - See [Distributed Traces](#distributed-traces) to learn how to get more fine-grained control over distributed tracing in Celery tasks. - - @@ -314,7 +296,11 @@ See Celery Beat Auto Discovery

+At this point, you should have integrated Sentry into your Celery application. Here's what to explore next: + +- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Set up Agent Tracing to monitor your AI systems +- Learn how to manually capture errors diff --git a/docs/platforms/python/integrations/django/index.mdx b/docs/platforms/python/integrations/django/index.mdx index 5eef058c81143..b848d8274af8e 100644 --- a/docs/platforms/python/integrations/django/index.mdx +++ b/docs/platforms/python/integrations/django/index.mdx @@ -2,7 +2,7 @@ title: Django caseStyle: snake_case supportLevel: production -description: "Learn how to set up Sentry in your Django app, capture your first errors and traces, and view them in Sentry." +description: "Learn how to set up Sentry in your Django app, capture your first events and traces, and view them in Sentry." --- @@ -26,13 +26,12 @@ You need: -## Configure +This guide requires `sentry-sdk` version 2.70.0 or later. If you already have the SDK installed, upgrade it with `pip install --upgrade sentry-sdk`. -Choose the features you want to configure, and this guide will show you how: +## Configure - +**Error Monitoring** starts working as soon as you call `sentry_sdk.init()`. **Logs** and **Application Metrics** need no extra configuration when using `sentry_sdk.logger` and `sentry_sdk.metrics`, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing** and **Profiling**. @@ -42,11 +41,16 @@ Configuration should happen as **early as possible** in your application's lifec To configure the Sentry SDK, initialize it in your `settings.py` file: +The snippet also turns on: + +- Collection of user data, such as the user's IP address: via `data_collection` +- Tracing: via `traces_sample_rate` +- Profiling: via `profile_session_sample_rate` and `profile_lifecycle` + +Don't need a feature? Remove its options from the snippet. + ```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___", @@ -54,19 +58,15 @@ sentry_sdk.init( data_collection={ "user_info": True, }, - # ___PRODUCT_OPTION_START___ performance - # Set traces_sample_rate to 1.0 to capture 100% - # of transactions for tracing. + # Enables Tracing. + # Set to 1.0 to capture 100% of spans for tracing. + # We recommend reducing this value in production. traces_sample_rate=1.0, - # ___PRODUCT_OPTION_END___ performance - # ___PRODUCT_OPTION_START___ profiling - # To collect profiles for all profile sessions, - # set `profile_session_sample_rate` to 1.0. + # Enables Profiling. + # Set to 1.0 to profile 100% of sessions. profile_session_sample_rate=1.0, - # Profiles will be automatically collected while - # there is an active span. + # Profiles are collected while a transaction is active. profile_lifecycle="trace", - # ___PRODUCT_OPTION_END___ profiling ) ``` @@ -83,7 +83,6 @@ You can also expect the following for your Django project: To learn how to manually report issues, see Capturing Errors. - ### Instrumenting Your App @@ -98,47 +97,49 @@ The Sentry SDK automatically monitors the following parts of your Django project You can also manually capture performance data – see Custom Instrumentation to learn more. - +## Send Logs -## Verify Your Setup +Use `sentry_sdk.logger` to send structured logs at different levels. You can include searchable attributes with each message. -Let's test your setup and confirm that data reaches your Sentry project. +To capture records from Python's standard-library `logging` module or Loguru, configure `capture_sentry_logs=True` on the corresponding integration. See the standard logging and Loguru integration guides. - - -### Issues - -To verify that Sentry captures errors and creates issues in your Sentry project, add this intentional error to your application: +See Set Up Logs for all available logging methods and formatting options. ```python -from django.urls import path - -def trigger_error(request): - division_by_zero = 1 / 0 +import sentry_sdk -urlpatterns = [ - path('sentry-debug/', trigger_error), - # ... -] +sentry_sdk.logger.info("Order processed {order_id}", order_id="order-123") +sentry_sdk.logger.warning("Rate limit reached", attributes={"endpoint": "/api/orders"}) ``` - +## Send Application Metrics - +Use `sentry_sdk.metrics` to send counters, gauges, and distributions from your app. Metrics are enabled by default after you initialize the SDK. - +See Set Up Metrics for all available metric types and configuration options. - +```python +import sentry_sdk - +sentry_sdk.metrics.count("checkout.failed", 1) +sentry_sdk.metrics.gauge("active_connections", 42) +sentry_sdk.metrics.distribution("api_latency", 187, unit="millisecond") +``` - +## Verify Your Setup - +Let's test your setup and confirm that data reaches your Sentry project. - +Add a view that raises an exception and route it in your Django application: - +```python +from django.urls import path + +def trigger_error(request): + 1 / 0 + +urlpatterns = [path("sentry-debug/", trigger_error)] +``` ### View Captured Data in Sentry @@ -246,7 +247,11 @@ The default is `{*range(500, 600)}`, meaning that all 5xx status codes are repor ## Next Steps - +At this point, you should have integrated Sentry into your Django application. Here's what to explore next: + +- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Set up Agent Tracing to monitor your AI systems +- Learn how to manually capture errors diff --git a/docs/platforms/python/integrations/fastapi/index.mdx b/docs/platforms/python/integrations/fastapi/index.mdx index 1d930ba2d3021..a8b591a8c6838 100644 --- a/docs/platforms/python/integrations/fastapi/index.mdx +++ b/docs/platforms/python/integrations/fastapi/index.mdx @@ -1,6 +1,6 @@ --- title: FastAPI -description: Learn how to set up Sentry in your FastAPI app, capture your first errors and traces, and view them in Sentry. +description: Learn how to set up Sentry in your FastAPI app, capture your first events and traces, and view them in Sentry. og_image: /og-images/platforms-python-integrations-fastapi.png --- @@ -23,13 +23,12 @@ You need: -## Configure +This guide requires `sentry-sdk` version 2.70.0 or later. If you already have the SDK installed, upgrade it with `pip install --upgrade sentry-sdk`. -Choose the features you want to configure, and this guide will show you how: +## Configure - +**Error Monitoring** starts working as soon as you call `sentry_sdk.init()`. **Logs** and **Application Metrics** need no extra configuration when using `sentry_sdk.logger` and `sentry_sdk.metrics`, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing** and **Profiling**. @@ -45,10 +44,37 @@ If you have the `fastapi` package in your dependencies, the Sentry FastAPI integ Import and initialize the SDK in your app's entry point: - +The snippet also turns on: + +- Collection of user data, such as the user's IP address: via `data_collection` +- Tracing: via `traces_sample_rate` +- Profiling: via `profile_session_sample_rate` and `profile_lifecycle` + +Don't need a feature? Remove its options from the snippet. + +```python +import sentry_sdk + +sentry_sdk.init( + dsn="___PUBLIC_DSN___", + + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, + + # Enables Tracing. + # Set to 1.0 to capture 100% of spans for tracing. + # We recommend reducing this value in production. + traces_sample_rate=1.0, + + # Enables Profiling. + # Set to 1.0 to profile 100% of sessions. + profile_session_sample_rate=1.0, + # Profiles are collected while a transaction is active. + profile_lifecycle="trace", +) +``` To further customize your setup, review the [Options section](#options) below. @@ -63,8 +89,6 @@ You can also expect the following for your FastAPI project: To learn how to manually report issues, see Capturing Errors. - - ### Instrumenting Your App The Sentry SDK automatically monitors the following parts of your FastAPI project: @@ -76,45 +100,46 @@ The Sentry SDK automatically monitors the following parts of your FastAPI projec You can also manually capture performance data – see Custom Instrumentation to learn more. - +## Send Logs -## Verify Your Setup - -Let's test your setup and confirm that data reaches your Sentry project. +Use `sentry_sdk.logger` to send structured logs at different levels. You can include searchable attributes with each message. -### Issues +To capture records from Python's standard-library `logging` module or Loguru, configure `capture_sentry_logs=True` on the corresponding integration. See the standard logging and Loguru integration guides. -To verify that Sentry captures errors and creates issues in your Sentry project, add this intentional error to your application: +See Set Up Logs for all available logging methods and formatting options. ```python -from fastapi import FastAPI +import sentry_sdk -sentry_sdk.init(...) # same as above - -app = FastAPI() - -@app.get("/sentry-debug") -async def trigger_error(): - division_by_zero = 1 / 0 +sentry_sdk.logger.info("Order processed {order_id}", order_id="order-123") +sentry_sdk.logger.warning("Rate limit reached", attributes={"endpoint": "/api/orders"}) ``` - +## Send Application Metrics - +Use `sentry_sdk.metrics` to send counters, gauges, and distributions from your app. Metrics are enabled by default after you initialize the SDK. - +See Set Up Metrics for all available metric types and configuration options. - +```python +import sentry_sdk - +sentry_sdk.metrics.count("checkout.failed", 1) +sentry_sdk.metrics.gauge("active_connections", 42) +sentry_sdk.metrics.distribution("api_latency", 187, unit="millisecond") +``` - +## Verify Your Setup - +Let's test your setup and confirm that data reaches your Sentry project. - +Add this route to your FastAPI app, then request `/sentry-debug`: - +```python +@app.get("/sentry-debug") +async def trigger_error(): + 1 / 0 +``` ### View Captured Data in Sentry @@ -229,7 +254,11 @@ Note that `OPTIONS` and `HEAD` are excluded by default. ## Next Steps - +At this point, you should have integrated Sentry into your FastAPI application. Here's what to explore next: + +- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Set up Agent Tracing to monitor your AI systems +- Learn how to manually capture errors diff --git a/docs/platforms/python/integrations/flask/index.mdx b/docs/platforms/python/integrations/flask/index.mdx index 475392cd9660a..cb6c15eb2d78c 100644 --- a/docs/platforms/python/integrations/flask/index.mdx +++ b/docs/platforms/python/integrations/flask/index.mdx @@ -1,6 +1,6 @@ --- title: Flask -description: "Learn how to set up Sentry in your Flask app, capture your first errors and traces, and view them in Sentry." +description: "Learn how to set up Sentry in your Flask app, capture your first events and traces, and view them in Sentry." --- @@ -24,13 +24,12 @@ You need: -## Configure +This guide requires `sentry-sdk` version 2.70.0 or later. If you already have the SDK installed, upgrade it with `pip install --upgrade sentry-sdk`. -Choose the features you want to configure, and this guide will show you how: +## Configure - +**Error Monitoring** starts working as soon as you call `sentry_sdk.init()`. **Logs** and **Application Metrics** need no extra configuration when using `sentry_sdk.logger` and `sentry_sdk.metrics`, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing** and **Profiling**. @@ -47,10 +46,37 @@ The SDK hooks into Flask's signals, not anything on the app object. Import and initialize the SDK in your app's entry point: - +The snippet also turns on: + +- Collection of user data, such as the user's IP address: via `data_collection` +- Tracing: via `traces_sample_rate` +- Profiling: via `profile_session_sample_rate` and `profile_lifecycle` + +Don't need a feature? Remove its options from the snippet. + +```python +import sentry_sdk + +sentry_sdk.init( + dsn="___PUBLIC_DSN___", + + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, + + # Enables Tracing. + # Set to 1.0 to capture 100% of spans for tracing. + # We recommend reducing this value in production. + traces_sample_rate=1.0, + + # Enables Profiling. + # Set to 1.0 to profile 100% of sessions. + profile_session_sample_rate=1.0, + # Profiles are collected while a transaction is active. + profile_lifecycle="trace", +) +``` To further customize your setup, review the [Options section](#options) below. @@ -63,53 +89,48 @@ You can also expect the following for your Flask app: - 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 `app.logger` or _any_ logger will be recorded by the [Logging](/platforms/python/integrations/logging/) integration (this integration is enabled by default). - - - - -## Verify Your Setup - -Let's test your setup and confirm that data reaches your Sentry project. +## Send Logs - +Use `sentry_sdk.logger` to send structured logs at different levels. You can include searchable attributes with each message. -### Issues +To capture records from Python's standard-library `logging` module or Loguru, configure `capture_sentry_logs=True` on the corresponding integration. See the standard logging and Loguru integration guides. -To verify that Sentry captures errors and creates issues in your Sentry project, add this intentional error to your application: +See Set Up Logs for all available logging methods and formatting options. ```python import sentry_sdk -from flask import Flask - -sentry_sdk.init(...) # same as above -app = Flask(__name__) - -@app.route("/") -def hello_world(): - 1 / 0 # raises an error - return "

Hello, World!

" +sentry_sdk.logger.info("Order processed {order_id}", order_id="order-123") +sentry_sdk.logger.warning("Rate limit reached", attributes={"endpoint": "/api/orders"}) ``` - +## Send Application Metrics - +Use `sentry_sdk.metrics` to send counters, gauges, and distributions from your app. Metrics are enabled by default after you initialize the SDK. - +See Set Up Metrics for all available metric types and configuration options. - +```python +import sentry_sdk - +sentry_sdk.metrics.count("checkout.failed", 1) +sentry_sdk.metrics.gauge("active_connections", 42) +sentry_sdk.metrics.distribution("api_latency", 187, unit="millisecond") +``` - +## Verify Your Setup - +Let's test your setup and confirm that data reaches your Sentry project. - +Add this route to your Flask app, then request `/sentry-debug`: - +```python +@app.route("/sentry-debug") +def trigger_error(): + 1 / 0 +``` ### View Captured Data in Sentry @@ -169,7 +190,11 @@ Note that `OPTIONS` and `HEAD` are excluded by default. ## Next Steps - +At this point, you should have integrated Sentry into your Flask application. Here's what to explore next: + +- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Set up Agent Tracing to monitor your AI systems +- Learn how to manually capture errors diff --git a/docs/platforms/python/integrations/starlette/index.mdx b/docs/platforms/python/integrations/starlette/index.mdx index 7c76cf26af4c4..7e9607c586fb5 100644 --- a/docs/platforms/python/integrations/starlette/index.mdx +++ b/docs/platforms/python/integrations/starlette/index.mdx @@ -1,6 +1,6 @@ --- title: Starlette -description: "Learn how to set up Sentry in your Starlette app, capture your first errors and traces, and view them in Sentry." +description: "Learn how to set up Sentry in your Starlette app, capture your first events and traces, and view them in Sentry." --- @@ -22,13 +22,12 @@ You need: -## Configure +This guide requires `sentry-sdk` version 2.70.0 or later. If you already have the SDK installed, upgrade it with `pip install --upgrade sentry-sdk`. -Choose the features you want to configure, and this guide will show you how: +## Configure - +**Error Monitoring** starts working as soon as you call `sentry_sdk.init()`. **Logs** and **Application Metrics** need no extra configuration when using `sentry_sdk.logger` and `sentry_sdk.metrics`, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing** and **Profiling**. @@ -44,10 +43,37 @@ If you have the `starlette` package in your dependencies, the Sentry Starlette i Import and initialize the SDK in your app's entry point: - +The snippet also turns on: + +- Collection of user data, such as the user's IP address: via `data_collection` +- Tracing: via `traces_sample_rate` +- Profiling: via `profile_session_sample_rate` and `profile_lifecycle` + +Don't need a feature? Remove its options from the snippet. + +```python +import sentry_sdk + +sentry_sdk.init( + dsn="___PUBLIC_DSN___", + + # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected + data_collection={ + "user_info": True, + }, + + # Enables Tracing. + # Set to 1.0 to capture 100% of spans for tracing. + # We recommend reducing this value in production. + traces_sample_rate=1.0, + + # Enables Profiling. + # Set to 1.0 to profile 100% of sessions. + profile_session_sample_rate=1.0, + # Profiles are collected while a transaction is active. + profile_lifecycle="trace", +) +``` To further customize your setup, review the [Options section](#options) below. @@ -62,47 +88,50 @@ You can also expect the following for your Starlette project: To learn how to manually report issues, see Capturing Errors. -## Verify Your Setup +## Send Logs -Let's test your setup and confirm that data reaches your Sentry project. +Use `sentry_sdk.logger` to send structured logs at different levels. You can include searchable attributes with each message. -### Issues +To capture records from Python's standard-library `logging` module or Loguru, configure `capture_sentry_logs=True` on the corresponding integration. See the standard logging and Loguru integration guides. -To verify that Sentry captures errors and creates issues in your Sentry project, add this intentional error to your application: +See Set Up Logs for all available logging methods and formatting options. ```python -from starlette.applications import Starlette -from starlette.routing import Route +import sentry_sdk -sentry_sdk.init(...) # same as above - -async def trigger_error(request): - division_by_zero = 1 / 0 - -app = Starlette(routes=[ - Route("/sentry-debug", trigger_error), -]) +sentry_sdk.logger.info("Order processed {order_id}", order_id="order-123") +sentry_sdk.logger.warning("Rate limit reached", attributes={"endpoint": "/api/orders"}) ``` -Point your browser to [http://localhost:8000/sentry-debug](http://localhost:8000/sentry-debug) to trigger the error which will be sent to Sentry. +## Send Application Metrics - +Use `sentry_sdk.metrics` to send counters, gauges, and distributions from your app. Metrics are enabled by default after you initialize the SDK. - +See Set Up Metrics for all available metric types and configuration options. - +```python +import sentry_sdk - +sentry_sdk.metrics.count("checkout.failed", 1) +sentry_sdk.metrics.gauge("active_connections", 42) +sentry_sdk.metrics.distribution("api_latency", 187, unit="millisecond") +``` + +## Verify Your Setup - +Let's test your setup and confirm that data reaches your Sentry project. - +Add this route to your Starlette app, then request `/sentry-debug`: - +```python +from starlette.applications import Starlette +from starlette.routing import Route - +async def trigger_error(request): + 1 / 0 - +app = Starlette(routes=[Route("/sentry-debug", trigger_error)]) +``` ### View Captured Data in Sentry @@ -191,7 +220,11 @@ Note that `OPTIONS` and `HEAD` are excluded by default. ## Next Steps - +At this point, you should have integrated Sentry into your Starlette application. Here's what to explore next: + +- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Set up Agent Tracing to monitor your AI systems +- Learn how to manually capture errors diff --git a/platform-includes/getting-started-prerequisites/python.mdx b/platform-includes/getting-started-prerequisites/python.mdx index b22b687efb7bc..b32708902e4d4 100644 --- a/platform-includes/getting-started-prerequisites/python.mdx +++ b/platform-includes/getting-started-prerequisites/python.mdx @@ -4,3 +4,4 @@ You need: - A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) - Your application up and running +- Python `3.6` or above