# Sentry Plugin

Source: https://payloadcms.com/docs/beta/plugins/sentry

![https://www.npmjs.com/package/@payloadcms/plugin-sentry](https://img.shields.io/npm/v/@payloadcms/plugin-sentry)

This plugin allows you to integrate [Sentry](https://sentry.io/) seamlessly with your [Payload](https://github.com/payloadcms/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.

> **Success**
>
> Sentry does smart stuff with error data to make bugs easier to find and fix. -
> [sentry.io](https://sentry.io/)

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

> **Note**
>
> This plugin is completely open-source and the [source code can be found
> here](https://github.com/payloadcms/payload/tree/main/packages/plugin-sentry).
> If you need help, check out our [Community
> Help](https://payloadcms.com/community-help). If you think you've found a bug,
> please [open a new
> issue](https://github.com/payloadcms/payload/issues/new?assignees=&labels=plugin%3A%20seo&template=bug_report.md&title=plugin-sentry%3A)
> with as much detail as possible.

## Installation

Install the plugin using any JavaScript package manager like [pnpm](https://pnpm.io), [npm](https://npmjs.com), or [Yarn](https://yarnpkg.com):

```bash
  pnpm add @payloadcms/plugin-sentry
```

## Sentry for Next.js setup

This plugin requires to complete the [Sentry + Next.js setup](https://docs.sentry.io/platforms/javascript/guides/nextjs/) before.

You can use either the [automatic setup](https://docs.sentry.io/platforms/javascript/guides/nextjs/#install) with the installation wizard:

```sh
npx @sentry/wizard@latest -i nextjs
```

Or the [Manual Setup](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/)

## Basic Usage

In the `plugins` array of your [Payload Config](/docs/v4/configuration/overview.md), call the plugin and pass in your Sentry DSN as an option.

```ts
import { buildConfig } from 'payload'
import { sentryPlugin } from '@payloadcms/plugin-sentry'
import { Pages, Media } from './collections'

import * as Sentry from '@sentry/nextjs'

const config = buildConfig({
  collections: [Pages, Media],
  plugins: [sentryPlugin({ Sentry })],
})

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.

```ts
import * as Sentry from '@sentry/nextjs'
import { buildConfig } from 'payload'
import { sentryPlugin } from '@payloadcms/plugin-sentry'
import { postgresAdapter } from '@payloadcms/db-postgres'
import pg from 'pg'

export default buildConfig({
  db: postgresAdapter({
    pool: { connectionString: process.env.DATABASE_URL },
    pg, // Inject the patched pg driver for Sentry instrumentation
  }),
  plugins: [sentryPlugin({ Sentry })],
})
```

## Options

- `Sentry` : Sentry | **required**

  The `Sentry` instance

> **Warning**
>
> Make sure to complete the [Sentry for Next.js Setup](#sentry-for-nextjs-setup)
> before.

- `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](https://docs.sentry.io/platforms/javascript/enriching-events/context/#passing-context-directly) 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:

```ts
import { buildConfig } from 'payload'
import { sentryPlugin } from '@payloadcms/plugin-sentry'

import * as Sentry from '@sentry/nextjs'

import { Pages, Media } from './collections'

const config = buildConfig({
  collections: [Pages, Media],
  plugins: [
    sentryPlugin({
      options: {
        captureErrors: [400, 403],
        context: ({ defaultContext, req }) => {
          return {
            ...defaultContext,
            tags: {
              locale: req.locale,
            },
          }
        },
        debug: true,
      },
      Sentry,
    }),
  ],
})

export default config
```

## TypeScript

All types can be directly imported:

```ts
import { PluginOptions } from '@payloadcms/plugin-sentry'
```