---
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