From 3aad53d7bd87da33c521ba875f14f016c0388bbd Mon Sep 17 00:00:00 2001 From: inventarSarah Date: Thu, 11 Jun 2026 08:18:48 +0200 Subject: [PATCH 1/2] draft Python qs guide --- docs/platforms/python/index.mdx | 249 ++++++++++++++++-- includes/quick-start-features-expandable.mdx | 9 + .../quick-start-locate-data-expandable.mdx | 9 + .../getting-started-prerequisites/python.mdx | 6 + 4 files changed, 257 insertions(+), 16 deletions(-) create mode 100644 platform-includes/getting-started-prerequisites/python.mdx diff --git a/docs/platforms/python/index.mdx b/docs/platforms/python/index.mdx index ea91f63a272aa..6ca616315be2e 100644 --- a/docs/platforms/python/index.mdx +++ b/docs/platforms/python/index.mdx @@ -1,6 +1,6 @@ --- title: Python -description: Sentry's Python SDK enables automatic reporting of errors and performance data in your application. +description: Learn how to set up Sentry in your Python app, capture your first errors and traces, and view them in Sentry. caseStyle: snake_case supportLevel: production sdk: sentry.python @@ -12,14 +12,24 @@ categories: -## Prerequisites + -- You need a Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) -- Read one of our dedicated guides if you use any of the frameworks we support +This guide focuses on plain Python. If you're working with Django, FastAPI, Starlette, or any other web framework, choose the respective guide from the list of supported web frameworks. + + + + ## Install -Install the Sentry SDK using [`pip`](https://pip.pypa.io/en/stable/): + + + + +Run the command for your preferred package manager to add the Sentry SDK to your application: + + + ```bash {tabTitle:pip} pip install "sentry-sdk" @@ -29,18 +39,42 @@ pip install "sentry-sdk" uv add "sentry-sdk" ``` +```bash {tabTitle:poetry} +poetry 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. + + + + +Import and Initialize the SDK in your app's entry point: + + + + ```python import sentry_sdk +# ___PRODUCT_OPTION_START___ metrics +from sentry_sdk import metrics +# ___PRODUCT_OPTION_END___ metrics sentry_sdk.init( dsn="___PUBLIC_DSN___", @@ -50,29 +84,59 @@ sentry_sdk.init( # ___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 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. + can 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 profile_lifecycle="trace", # ___PRODUCT_OPTION_END___ profiling # ___PRODUCT_OPTION_START___ logs # Enable logs to be sent to Sentry + # see https://docs.sentry.io/platforms/python/configuration/options/#enable_logs for more info enable_logs=True, # ___PRODUCT_OPTION_END___ logs ) ``` -In async programs, it's recommended to call `sentry_sdk.init()` inside an `async` function to ensure async code is instrumented properly. If possible, we recommend calling `sentry_sdk.init()` at the beginning of the first `async` function you call. + + + + + + + + +The configuration above enables continuous profiling in trace mode. The SDK supports two profiling which are mutually exclusive: continuous and transaction-based profiling. The configuration options for each mode have similar names, so make sure you're using the right ones for your chosen mode. +See Profiling to learn more about these modes. + + + + + + + + + +In async programs, we recommended to Initialize the Sentry SDK inside an `async` function to make sure async code is instrumented properly. If possible, 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 + async def main(): sentry_sdk.init( @@ -82,29 +146,182 @@ async def main(): asyncio.run(main()) ``` -## Verify + + + + + +### Instrumenting Your App + +The Sentry SDK automatically detects your installed packages and enables matching integrations, so operations like HTTP requests or database queries made with supported libraries will be captured as spans automatically. + + + + + +However, spans are only created within an existing transaction. If you're not using a supported framework, no transactions are created automatically and you'll need to create one manually using `sentry_sdk.start_transaction()`. As a result, any auto-instrumented spans will attach to the transaction automatically. + +See Custom Instrumentation for more info. + + + + +```python +import sentry_sdk + +def eat_slice(slice): + ... + +def eat_pizza(pizza): + with sentry_sdk.start_transaction(op="task", name="Eat Pizza"): + while pizza.slices > 0: + eat_slice(pizza.slices.pop()) +``` + + + + + + + +## Verify Your Setup + +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 + + + + -Add this intentional error to your application to test that everything is working right away. +To verify that Sentry captures errors and creates issues in your Sentry project, add this intentional error to your application: + + + ```py +import sentry_sdk + division_by_zero = 1 / 0 ``` - + + + -Learn more about manually capturing an error or message in our Usage documentation. + - +### Tracing -To view and resolve the recorded error, log into [sentry.io](https://sentry.io) and select your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved. + + + - +To test your tracing configuration, create a custom transaction and span: -Not seeing your error in Sentry? Make sure you're running the above example from a file and not from a Python shell like IPython. + + - +```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 + +# Send logs directly to Sentry +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 + +# Emit metrics +metrics.count("checkout.failed", 1) +metrics.gauge("queue.depth", 42) +metrics.distribution("cart.amount_usd", 187.5) + +``` + + + + + + + +### 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). + + ## 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: + - 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/) + + + +- Find various topics in Troubleshooting +- [Get support](https://www.sentry.help/en/) + + + + diff --git a/includes/quick-start-features-expandable.mdx b/includes/quick-start-features-expandable.mdx index 270b195ab9e1a..be0cf30e3ebb7 100644 --- a/includes/quick-start-features-expandable.mdx +++ b/includes/quick-start-features-expandable.mdx @@ -50,4 +50,13 @@ import { FeatureInfo } from "sentry-docs/components/featureInfo"; + + + + + + diff --git a/includes/quick-start-locate-data-expandable.mdx b/includes/quick-start-locate-data-expandable.mdx index 86fc1f2f9dc4a..3235e9d516024 100644 --- a/includes/quick-start-locate-data-expandable.mdx +++ b/includes/quick-start-locate-data-expandable.mdx @@ -50,4 +50,13 @@ import { FeatureInfo } from "sentry-docs/components/featureInfo"; + + + + + + diff --git a/platform-includes/getting-started-prerequisites/python.mdx b/platform-includes/getting-started-prerequisites/python.mdx new file mode 100644 index 0000000000000..ce71f06721646 --- /dev/null +++ b/platform-includes/getting-started-prerequisites/python.mdx @@ -0,0 +1,6 @@ +## Prerequisites + +You need: + +- You need a Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) +- Read one of our dedicated guides if you use any of the frameworks we support From 67d68796789d0635d41430f191f49ba9d206a2ee Mon Sep 17 00:00:00 2001 From: inventarSarah Date: Thu, 11 Jun 2026 09:25:03 +0200 Subject: [PATCH 2/2] refine qs draft --- docs/platforms/python/index.mdx | 41 ++++++++++--------- .../getting-started-prerequisites/python.mdx | 4 +- 2 files changed, 24 insertions(+), 21 deletions(-) diff --git a/docs/platforms/python/index.mdx b/docs/platforms/python/index.mdx index 6ca616315be2e..1ac4345aca055 100644 --- a/docs/platforms/python/index.mdx +++ b/docs/platforms/python/index.mdx @@ -12,12 +12,14 @@ categories: - + -This guide focuses on plain Python. If you're working with Django, FastAPI, Starlette, or any other web framework, choose the respective guide from the list of supported web frameworks. +This guide focuses on plain Python. If you're working with Django, FastAPI, Starlette, or any other web framework, choose the respective guide from the list of supported frameworks. + + ## Install @@ -65,7 +67,7 @@ Configuration should happen as **early as possible** in your application's lifec -Import and Initialize the SDK in your app's entry point: +Import and initialize the SDK in your app's entry point: @@ -78,20 +80,27 @@ from sentry_sdk import metrics sentry_sdk.init( dsn="___PUBLIC_DSN___", + # Add request headers and IP for users, # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info send_default_pii=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 traces_sample_rate=1.0, # ___PRODUCT_OPTION_END___ performance # ___PRODUCT_OPTION_START___ profiling + + # Enables continuous profiling. + # For transaction-based profiling, + # use `profiles_sample_rate` instead. # To collect profiles for all profile sessions, # set `profile_session_sample_rate` to 1.0. - can + # see https://docs.sentry.io/platforms/python/configuration/options/#profile_session_sample_rate for more info 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 @@ -112,10 +121,10 @@ sentry_sdk.init( - + -The configuration above enables continuous profiling in trace mode. The SDK supports two profiling which are mutually exclusive: continuous and transaction-based profiling. The configuration options for each mode have similar names, so make sure you're using the right ones for your chosen mode. -See Profiling to learn more about these modes. +With the configuration above, you enable continuous profiling. However, the SDK also supports transaction-based profiling via the `profiles_sample_rate` option. These profiling mode options have similar names, so make sure you're using the right one for your chosen mode. +See Profiling to learn more. @@ -125,7 +134,7 @@ See Profiling to learn more about -In async programs, we recommended to Initialize the Sentry SDK inside an `async` function to make sure async code is instrumented properly. If possible, call `sentry_sdk.init()` at the beginning of the first `async` function you call: +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: @@ -159,9 +168,9 @@ The Sentry SDK automatically detects your installed packages and enables matchin -However, spans are only created within an existing transaction. If you're not using a supported framework, no transactions are created automatically and you'll need to create one manually using `sentry_sdk.start_transaction()`. As a result, any auto-instrumented spans will attach to the transaction automatically. +However, spans are only created within an existing transaction. If you're not using a supported framework that creates transactions automatically, you'll need to create them manually using `sentry_sdk.start_transaction()`. -See Custom Instrumentation for more info. +See Custom Instrumentation for more info. @@ -169,13 +178,9 @@ See Custom Instrument ```python import sentry_sdk -def eat_slice(slice): - ... - -def eat_pizza(pizza): - with sentry_sdk.start_transaction(op="task", name="Eat Pizza"): - while pizza.slices > 0: - eat_slice(pizza.slices.pop()) +def some_function(): + with sentry_sdk.start_transaction(op="task", name="Test Transaction"): + ... ``` @@ -258,7 +263,6 @@ To verify that Sentry catches your logs, add some log statements to your applica ```py import sentry_sdk -# Send logs directly to Sentry 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') @@ -286,7 +290,6 @@ Send test metrics from your app to verify metrics are arriving in Sentry: ```py from sentry_sdk import metrics -# Emit metrics metrics.count("checkout.failed", 1) metrics.gauge("queue.depth", 42) metrics.distribution("cart.amount_usd", 187.5) diff --git a/platform-includes/getting-started-prerequisites/python.mdx b/platform-includes/getting-started-prerequisites/python.mdx index ce71f06721646..b22b687efb7bc 100644 --- a/platform-includes/getting-started-prerequisites/python.mdx +++ b/platform-includes/getting-started-prerequisites/python.mdx @@ -2,5 +2,5 @@ You need: -- You need a Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) -- Read one of our dedicated guides if you use any of the frameworks we support +- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) +- Your application up and running