Skip to content

Docs for PyMongo integration #5469

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.

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

Merged
merged 13 commits into from
Nov 14, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
70 changes: 70 additions & 0 deletions src/platforms/python/guides/pymongo/index.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
---
title: PyMongo
description: "Learn about using Sentry with PyMongo."
---

The PyMongo integration adds support for [PyMongo](https://www.mongodb.com/docs/drivers/pymongo/), the official MongoDB driver.


## Install

Install `sentry-sdk` from PyPI with the `pymongo` extra:

```bash
pip install --upgrade 'sentry-sdk[pymongo]'
```

## Configure

To configure the SDK, initialize it before creating any of PyMongo's MongoClient instances:

```python
import sentry_sdk
from sentry_sdk.integrations.pymongo import PyMongoIntegration


sentry_sdk.init(
dsn="___PUBLIC_DSN___",
integrations=[
PyMongoIntegration(),
],

# Set traces_sample_rate to 1.0 to capture 100%
# of transactions for performance monitoring.
# We recommend adjusting this value in production,
traces_sample_rate=1.0,
)
```

<Note>

In the future, we will make this auto-enabling, so you won't need to add the `PyMongoIntegration` to your
`sentry_sdk.init()` call. Instead, the Sentry SDK will detect the presence of PyMongo and will set up the integration
automatically.

</Note>


## Behavior

The following information about your MonogDB queries will be available to you on Sentry.io:

- Performance traces for all MongoDB queries
- Breadcrumbs for all MongoDB queries
- Personal identifiable information (PII) will be stripped from all MongoDB queries if `send_default_pii` is disabled in the SDK. (This was tested for PyMongo 4.2 and below, but "should" also be future proof)

![MongoDB query details are shown as a waterfall diagram](mongodb-query-performance-details.png)

### Other MongoDB libraries

PyMongo is an official synchronous driver for MongoDB. It means that many other Python libraries interacting with
MongoDB use it under the hood, like, for example `mongoengine` (always) or `umongo` (if selected from multiple available
drivers). Official async MongoDB driver called `Motor` uses PyMongo under the hood as well.
Queries generated by those libraries will also be monitored.

If you use a different driver (for example, `TxMongo`), this integration won't work.

### Mongomock

While `mongomock` can be used to replace `PyMongo` in tests, it doesn't implement all features available in the official
driver. This integration will not generate any breadcrumbs or spans from `mongomock`'s clients.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
38 changes: 38 additions & 0 deletions src/wizard/python/pymongo.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
name: PyMongo
doc_link: https://docs.sentry.io/platforms/python/guides/pymongo/
support_level: production
type: library
---

The PyMongo integration adds support for [PyMongo](https://www.mongodb.com/docs/drivers/pymongo/), the official MongoDB
driver. It adds breadcrumbs and performace traces for all queries.

1. Install `sentry-sdk` from PyPI with the `pymongo` extra:

```bash
pip install --upgrade 'sentry-sdk[pymongo]'
```

2. To configure the SDK, initialize it before creating any of PyMongo's MongoClient instances:

```python
import sentry_sdk
from sentry_sdk.integrations.pymongo import PyMongoIntegration


sentry_sdk.init(
dsn="___PUBLIC_DSN___",
integrations=[
PyMongoIntegration(),
],

# Set traces_sample_rate to 1.0 to capture 100%
# of transactions for performance monitoring.
# We recommend adjusting this value in production,
traces_sample_rate=1.0,
)
```

The above configuration captures both breadcrumbs and performance data. To reduce the volume of performance data
captured, change `traces_sample_rate` to a value between 0 and 1.