109 lines
3 KiB
Markdown
109 lines
3 KiB
Markdown
---
|
|
title: "Sentry Plugin"
|
|
aliases: [payload-sentry, sentry-error-tracking, plugin-sentry]
|
|
tags: [payloadcms, plugin, sentry, monitoring, error-tracking, observability]
|
|
sources: [raw/plugins__sentry.md]
|
|
created: 2026-05-15
|
|
updated: 2026-05-15
|
|
---
|
|
|
|
# Sentry Plugin
|
|
|
|
Integrates [Sentry](https://sentry.io/) error tracking and performance monitoring into a Payload application via `@payloadcms/plugin-sentry`.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pnpm add @payloadcms/plugin-sentry
|
|
```
|
|
|
|
**Prerequisite:** complete [Sentry + Next.js setup](https://docs.sentry.io/platforms/javascript/guides/nextjs/) first — either via wizard or manual setup.
|
|
|
|
```bash
|
|
npx @sentry/wizard@latest -i nextjs
|
|
```
|
|
|
|
## Basic Usage
|
|
|
|
Pass the imported `Sentry` instance to the plugin:
|
|
|
|
```ts
|
|
import { buildConfig } from 'payload'
|
|
import { sentryPlugin } from '@payloadcms/plugin-sentry'
|
|
import * as Sentry from '@sentry/nextjs'
|
|
|
|
export default buildConfig({
|
|
collections: [Pages, Media],
|
|
plugins: [sentryPlugin({ Sentry })],
|
|
})
|
|
```
|
|
|
|
## Instrumenting Database Queries (Postgres)
|
|
|
|
Inject the Sentry-patched `pg` driver so Sentry can trace DB calls:
|
|
|
|
```ts
|
|
import { postgresAdapter } from '@payloadcms/db-postgres'
|
|
import pg from 'pg'
|
|
|
|
export default buildConfig({
|
|
db: postgresAdapter({
|
|
pool: { connectionString: process.env.DATABASE_URL },
|
|
pg, // Sentry-patched driver
|
|
}),
|
|
plugins: [sentryPlugin({ Sentry })],
|
|
})
|
|
```
|
|
|
|
## Plugin Options
|
|
|
|
| Option | Type | Default | Description |
|
|
|--------|------|---------|-------------|
|
|
| `Sentry` | `Sentry` | **required** | Sentry instance |
|
|
| `enabled` | `boolean` | `true` | Disable plugin without removing config |
|
|
| `context` | `(args: ContextArgs) => Partial<ScopeContext>` | — | Add custom contextual data to Sentry events |
|
|
| `captureErrors` | `number[]` | — | Extra HTTP status codes to capture (default: 500+) |
|
|
|
|
## Full Config Example
|
|
|
|
```ts
|
|
plugins: [
|
|
sentryPlugin({
|
|
Sentry,
|
|
options: {
|
|
captureErrors: [400, 403],
|
|
context: ({ defaultContext, req }) => ({
|
|
...defaultContext,
|
|
tags: { locale: req.locale },
|
|
}),
|
|
debug: true,
|
|
},
|
|
}),
|
|
],
|
|
```
|
|
|
|
## TypeScript
|
|
|
|
```ts
|
|
import { PluginOptions } from '@payloadcms/plugin-sentry'
|
|
```
|
|
|
|
## Key Takeaways
|
|
|
|
- **Sentry for Next.js must be set up first** — the plugin wraps an already-initialised Sentry instance, it does not bootstrap Sentry itself.
|
|
- **Postgres query tracing** requires injecting the Sentry-patched `pg` driver into `postgresAdapter` via the `pg` option.
|
|
- **`captureErrors`** extends the default 500+ capture threshold to additional codes (e.g. `[400, 403]`).
|
|
- **`context`** callback lets you attach request-scoped tags (locale, user ID) to every captured event.
|
|
- Source: open-source at `packages/plugin-sentry` in the Payload monorepo.
|
|
|
|
## Related
|
|
|
|
- [[wiki/payloadcms/plugins|Plugins Overview + Official]]
|
|
- [[wiki/payloadcms/plugins-api|Plugin API]]
|
|
- [[wiki/payloadcms/database-postgres|Database — Postgres]]
|
|
- [[wiki/payloadcms/hooks|PayloadCMS — Hooks]]
|
|
|
|
## Sources
|
|
|
|
- `raw/plugins__sentry.md`
|
|
- https://payloadcms.com/docs/plugins/sentry
|