Sentry Plugin

Integrates Sentry error tracking and performance monitoring into a Payload application via @payloadcms/plugin-sentry.

Installation

pnpm add @payloadcms/plugin-sentry

Prerequisite: complete Sentry + Next.js setup first — either via wizard or manual setup.

npx @sentry/wizard@latest -i nextjs

Basic Usage

Pass the imported Sentry instance to the plugin:

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:

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

plugins: [
  sentryPlugin({
    Sentry,
    options: {
      captureErrors: [400, 403],
      context: ({ defaultContext, req }) => ({
        ...defaultContext,
        tags: { locale: req.locale },
      }),
      debug: true,
    },
  }),
],

TypeScript

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.

Sources

raw/plugins__sentry.md
https://payloadcms.com/docs/plugins/sentry

3 KiB Raw Permalink Blame History