Skip to content

docs(python): Update Python main quick start guide #18365

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
inventarSarah wants to merge 2 commits into
base: master
Choose a base branch
from
+260 −16
Open

docs(python): Update Python main quick start guide #18365

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3aad53d
draft Python qs guide
inventarSarah Jun 11, 2026
67d6879
refine qs draft
inventarSarah Jun 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
252 changes: 236 additions & 16 deletions docs/platforms/python/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -12,14 +12,26 @@ categories:

<AgentSkillsCallout skill="sentry-python-sdk" platformName="Python" />

## Prerequisites
<Alert level="warning" title="Using a framework?">

- 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 <PlatformLink to="/integrations/#web-frameworks">frameworks</PlatformLink> 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 <PlatformLink to="/integrations/#web-frameworks">frameworks</PlatformLink>.

</Alert>

<PlatformContent includePath="getting-started-prerequisites" />

<StepConnector selector="h2" showNumbers={true}>

## Install

Install the Sentry SDK using [`pip`](https://pip.pypa.io/en/stable/):
<SplitLayout>
<SplitSection>
<SplitSectionText>

Run the command for your preferred package manager to add the Sentry SDK to your application:

</SplitSectionText>
<SplitSectionCode>

```bash {tabTitle:pip}
pip install "sentry-sdk"
Expand All @@ -29,50 +41,111 @@ pip install "sentry-sdk"
uv add "sentry-sdk"
```

```bash {tabTitle:poetry}
poetry add "sentry-sdk"
```

</SplitSectionCode>
</SplitSection>
</SplitLayout>

## Configure

Choose the features you want to configure, and this guide will show you how:

<OnboardingOptionButtons
options={["error-monitoring", "performance", "profiling", "logs"]}
options={["error-monitoring", "performance", "profiling", "logs", "metrics"]}
/>

<Include name="quick-start-features-expandable" />

### Initialize the Sentry SDK

Configuration should happen as **early as possible** in your application's lifecycle.

<SplitLayout>
<SplitSection>
<SplitSectionText>

Import and initialize the SDK in your app's entry point:

</SplitSectionText>
<SplitSectionCode>

```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.
</SplitSectionCode>
</SplitSection>
</SplitLayout>

<OnboardingOption optionId="profiling">

<Alert level="warning" title="Continuous profiling vs transaction-based profiling">

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 <PlatformLink to="/profiling/">Profiling</PlatformLink> to learn more.

</Alert>
Comment on lines +124 to +129

@sentrivana sentrivana Jun 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd leave this out altogether since we'll be deprecating transaction-based profiling and dropping it in the next major. So for folks setting up the SDK for the first time, which is the target audience here, I'd just recommend to set up continuous profiling.

On the profiling page, we should absolutely talk about the distinction and the confusing options (I believe we already do).


</OnboardingOption>

<SplitLayout>
<SplitSection>
<SplitSectionText>

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:

</SplitSectionText>
<SplitSectionCode>

```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(
Expand All @@ -82,29 +155,176 @@ async def main():
asyncio.run(main())
```

## Verify
</SplitSectionCode>
</SplitSection>
</SplitLayout>

<OnboardingOption optionId="performance">
### 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.

@sentrivana sentrivana Jun 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Most integrations will auto enable but there's still a handful that need to be enabled manually -- the current wording makes it sound like all are auto-enabling.

Maybe something like this? Or a bigger rewording would make sense here?

Suggested change
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.
The Sentry SDK automatically detects your installed packages and enables matching integrations for the most popular frameworks and libraries, so operations like HTTP requests or database queries made with supported libraries will be captured as spans automatically.


<SplitLayout>
<SplitSection>
<SplitSectionText>

However, spans are only created within an existing transaction. If you're not using a <PlatformLink to="/tracing/instrumentation/automatic-instrumentation/">supported framework</PlatformLink> that creates transactions automatically, you'll need to create them manually using `sentry_sdk.start_transaction()`.

See <PlatformLink to="/tracing/instrumentation/custom-instrumentation/">Custom Instrumentation</PlatformLink> for more info.

</SplitSectionText>
<SplitSectionCode>

```python
import sentry_sdk

def some_function():
with sentry_sdk.start_transaction(op="task", name="Test Transaction"):
...
```

</SplitSectionCode>
</SplitSection>
</SplitLayout>

</OnboardingOption>

## Verify Your Setup

Let's test your setup and confirm that data reaches your Sentry project.

<Alert level="warning">

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.

</Alert>

Add this intentional error to your application to test that everything is working right away.
### Issues

<SplitLayout>
<SplitSection>
<SplitSectionText>

To verify that Sentry captures errors and creates issues in your Sentry project, add this intentional error to your application:

</SplitSectionText>
<SplitSectionCode>

```py
import sentry_sdk

division_by_zero = 1 / 0
```

<Alert>
</SplitSectionCode>
</SplitSection>
</SplitLayout>

Learn more about manually capturing an error or message in our <PlatformLink to="/usage/">Usage documentation</PlatformLink>.
<OnboardingOption optionId="performance">

</Alert>
### 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.
<SplitLayout>
<SplitSection>
<SplitSectionText>

<Alert>
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.
</SplitSectionText>
<SplitSectionCode>

</Alert>
```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()
```

</SplitSectionCode>
</SplitSection>
</SplitLayout>

</OnboardingOption>

<OnboardingOption optionId="logs">

### Logs

<SplitLayout>
<SplitSection>
<SplitSectionText>

To verify that Sentry catches your logs, add some log statements to your application:

</SplitSectionText>
<SplitSectionCode>

```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')
Comment on lines +266 to +268

@sentrivana sentrivana Jun 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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')
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")

No functional change; just to keep the quotes consistent on the page

```

</SplitSectionCode>
</SplitSection>
</SplitLayout>

</OnboardingOption>

<OnboardingOption optionId="metrics">

### Metrics

<SplitLayout>
<SplitSection>
<SplitSectionText>

Send test metrics from your app to verify metrics are arriving in Sentry:

</SplitSectionText>
<SplitSectionCode>

```py
from sentry_sdk import metrics

metrics.count("checkout.failed", 1)
metrics.gauge("queue.depth", 42)
metrics.distribution("cart.amount_usd", 187.5)

```

</SplitSectionCode>
</SplitSection>
</SplitLayout>

</OnboardingOption>

### 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).

<Include name="quick-start-locate-data-expandable" />

## 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 <PlatformLink to="/configuration/">customize your configuration</PlatformLink>
- Learn more about <PlatformLink to="/usage/">manually capturing errors or messages</PlatformLink>
- Dive straight into the API with our [API docs](https://getsentry.github.io/sentry-python/)

<Expandable permalink={false} title="Are you having problems setting up the SDK?">

- Find various topics in <PlatformLink to="/troubleshooting/">Troubleshooting</PlatformLink>
- [Get support](https://www.sentry.help/en/)

</Expandable>

</StepConnector>
9 changes: 9 additions & 0 deletions includes/quick-start-features-expandable.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,4 +50,13 @@ import { FeatureInfo } from "sentry-docs/components/featureInfo";

</PlatformSection>

<PlatformSection supported={["python"]}>

<FeatureInfo
features={["issues", "tracing", "profiling", "logs", "metrics"]}
type="learnMore"
/>

</PlatformSection>

</Expandable>
9 changes: 9 additions & 0 deletions includes/quick-start-locate-data-expandable.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,4 +50,13 @@ import { FeatureInfo } from "sentry-docs/components/featureInfo";

</PlatformSection>

<PlatformSection supported={["python"]}>

<FeatureInfo
features={["issues", "tracing", "profiling", "logs", "metrics"]}
type="findInSentry"
/>

</PlatformSection>

</Expandable>
6 changes: 6 additions & 0 deletions platform-includes/getting-started-prerequisites/python.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
## Prerequisites

You need:

- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/)
- Your application up and running
Loading