Next
Sentry Plugin
This plugin allows you to integrate Sentry seamlessly with your Payload application.
What is Sentry?
Sentry is a powerful error tracking and performance monitoring tool that helps developers identify, diagnose, and resolve issues in their applications.
This multi-faceted software offers a range of features that will help you manage errors with greater ease and ultimately ensure your application is running smoothly:
Core Features
- Error Tracking: Instantly captures and logs errors as they occur in your application
- Performance Monitoring: Tracks application performance to identify slowdowns and bottlenecks
- Detailed Reports: Provides comprehensive insights into errors, including stack traces and context
- Alerts and Notifications: Send and customize event-triggered notifications
- Issue Grouping, Filtering and Search: Automatically groups similar errors, and allows filtering and searching issues by custom criteria
- Breadcrumbs: Records user actions and events leading up to an error
- Integrations: Connects with various tools and services for enhanced workflow and issue management
Installation
Install the plugin using any JavaScript package manager like pnpm, npm, or Yarn:
1
pnpm add @payloadcms/plugin-sentry
Sentry for Next.js setup
This plugin requires to complete the Sentry + Next.js setup before.
You can use either the automatic setup with the installation wizard:
1
npx @sentry/wizard@latest -i nextjs
Or the Manual Setup
Basic Usage
In the plugins array of your Payload Config, call the plugin and pass in your Sentry DSN as an option.
1
import { buildConfig } from 'payload'
2
import { sentryPlugin } from '@payloadcms/plugin-sentry'
3
import { Pages, Media } from './collections'
4
5
import * as Sentry from '@sentry/nextjs'
6
7
const config = buildConfig({
8
collections: [Pages, Media],
9
plugins: [sentryPlugin({ Sentry })],
10
})
11
12
export default config
Instrumenting Database Queries
If you want Sentry to capture Postgres query performance traces, you need to inject the Sentry-patched pg driver into the Postgres adapter. This ensures Sentry’s instrumentation hooks into your database calls.
1
import * as Sentry from '@sentry/nextjs'
2
import { buildConfig } from 'payload'
3
import { sentryPlugin } from '@payloadcms/plugin-sentry'
4
import { postgresAdapter } from '@payloadcms/db-postgres'
5
import pg from 'pg'
6
7
export default buildConfig({
8
db: postgresAdapter({
9
pool: { connectionString: process.env.DATABASE_URL },
10
pg, // Inject the patched pg driver for Sentry instrumentation
11
}),
12
plugins: [sentryPlugin({ Sentry })],
13
})
Options
Sentry: Sentry | required
The Sentry instance
enabled: boolean | optional
Set to false to disable the plugin. Defaults to true.
context:(args: ContextArgs) => Partial<ScopeContext> | Promise<Partial<ScopeContext>>
Pass additional contextual data to Sentry
captureErrors: number[] | optional
By default, Sentry.errorHandler will capture only errors with a status code of 500 or higher. To capture additional error codes, pass the values as numbers in an array.
Example
Configure any of these options by passing them to the plugin:
1
import { buildConfig } from 'payload'
2
import { sentryPlugin } from '@payloadcms/plugin-sentry'
3
4
import * as Sentry from '@sentry/nextjs'
5
6
import { Pages, Media } from './collections'
7
8
const config = buildConfig({
9
collections: [Pages, Media],
10
plugins: [
11
sentryPlugin({
12
options: {
13
captureErrors: [400, 403],
14
context: ({ defaultContext, req }) => {
15
return {
16
...defaultContext,
17
tags: {
18
locale: req.locale,
19
},
20
}
21
},
22
debug: true,
23
},
24
Sentry,
25
}),
26
],
27
})
28
29
export default config
TypeScript
All types can be directly imported:
1
import { PluginOptions } from '@payloadcms/plugin-sentry'