diff --git a/docs/platforms/python/index.mdx b/docs/platforms/python/index.mdx
index ea91f63a272aa..1ac4345aca055 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,26 @@ 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 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,50 +41,111 @@ 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___",
+
# 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.
+ # 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
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.
+
+
+
+
+
+
+
+
+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.
+
+
+
+
+
+
+
+
+
+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:
+
+
+
```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 +155,176 @@ 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 that creates transactions automatically, you'll need to create them manually using `sentry_sdk.start_transaction()`.
+
+See Custom Instrumentation for more info.
+
+
+
+
+```python
+import sentry_sdk
+
+def some_function():
+ with sentry_sdk.start_transaction(op="task", name="Test Transaction"):
+ ...
+```
+
+
+
+
+
+
+
+## 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.
+
+
-Add this intentional error to your application to test that everything is working right away.
+### Issues
+
+
+
+
+
+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
+
+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)
+
+```
+
+
+
+
+
+
+
+### 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..b22b687efb7bc
--- /dev/null
+++ b/platform-includes/getting-started-prerequisites/python.mdx
@@ -0,0 +1,6 @@
+## Prerequisites
+
+You need:
+
+- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/)
+- Your application up and running