Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: adds sentry to plugin docs #6475

Merged
merged 2 commits into from
May 29, 2024
+138 −118
Merged

docs: adds sentry to plugin docs #6475

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
98a909f
docs: adds sentry to plugin docs for 3.0
JessChowdhury May 23, 2024
bbbe725
chore: update sentry plugin readme
JessChowdhury May 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 133 additions & 0 deletions docs/plugins/sentry.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
---
title: Sentry Plugin
label: Sentry
order: 20
desc: Integrate Sentry error tracking into your Payload application
keywords: plugins, sentry, error, tracking, monitoring, logging, bug, reporting, performance
---

[![NPM](https://img.shields.io/npm/v/@payloadcms/plugin-sentry)](https://www.npmjs.com/package/@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.

<Banner type="success">
Sentry does smart stuff with error data to make bugs easier to find and fix. - [sentry.io](https://sentry.io/)
</Banner>

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

<Banner type="info">
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-seo%3A) with as much detail as possible.
</Banner>

## Installation

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

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

## Basic Usage

In the `plugins` array of your [Payload config](https://payloadcms.com/docs/configuration/overview), call the plugin and pass in your Sentry DSN as an option.

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

const config = buildConfig({
collections: [Pages, Media],
plugins: [
sentry({
dsn: 'https://[email protected]/4505357433352176',
}),
],
})

export default config
```

## Options

- `dsn` : string | **required**

Sentry automatically assigns a DSN when you create a project, the unique DSN informs Sentry where to send events so they are associated with the correct project.

<Banner type="warning">
You can find your project DSN (Data Source Name) by visiting [sentry.io](sentry.io) and navigating to your [Project] > Settings > Client Keys (DSN).
</Banner>

- `enabled`: boolean | optional

Set to false to disable the plugin. Defaults to true.

- `init` : ClientOptions | optional

Sentry allows a variety of options to be passed into the Sentry.init() function, see the full list of options [here](https://docs.sentry.io/platforms/node/guides/express/configuration/options).

- `requestHandler` : RequestHandlerOptions | optional

Accepts options that let you decide what data should be included in the event sent to Sentry, checkout the options [here](https://docs.sentry.io/platforms/node/guides/express/configuration/options).

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

To see all options available, visit the [Sentry Docs](https://docs.sentry.io/platforms/node/guides/express/configuration/options).

### Example

Configure any of these options by passing them to the plugin:

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

const config = buildConfig({
collections: [Pages, Media],
plugins: [
sentry({
dsn: 'https://[email protected]/4505357433352176',
options: {
init: {
debug: true,
environment: 'development',
tracesSampleRate: 1.0,
},
requestHandler: {
serverName: false,
user: ['email'],
},
captureErrors: [400, 403, 404],
},
}),
],
})

export default config
```

## TypeScript

All types can be directly imported:

```ts
import { PluginOptions } from '@payloadcms/plugin-sentry/types'
```
123 changes: 5 additions & 118 deletions packages/plugin-sentry/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,120 +1,7 @@
# Sentry Plugin for Payload
# Payload Sentry Plugin

This plugin seamlessly integrates [Sentry](https://sentry.io/) with [Payload](https://github.com/payloadcms/payload) for performance monitoring and error tracking.
This plugin allows you to integrate [Sentry](https://sentry.io/) seamlessly with your [Payload](https://github.com/payloadcms/payload) application.

## Installation

```bash
yarn add @payloadcms/plugin-sentry
# OR
npm i @payloadcms/plugin-sentry
```

## Basic Usage

1. Import `sentry` from `'@payloadcms/plugin-sentry'`
2. Add it to the `plugins` array of your [Payload config](https://payloadcms.com/docs/configuration/overview)
3. Pass in your Data Source Name (DSN)
4. Pass [additional options](#additional-options) - _not required_

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

const config = buildConfig({
collections: [Pages, Media],
plugins: [
sentry({
dsn: 'https://[email protected]/4505357433352176',
}),
],
})

export default config
```

## Options

### Data Source Name (DSN) and where to find it

- `dsn` : string | required

Sentry automatically assigns a DSN when you create a project, the unique DSN informs Sentry where to send events so they are associated with the correct project.

#### :rotating_light: You can find the DSN in your project settings by navigating to [Project] > Settings > Client Keys (DSN) in [sentry.io](sentry.io).

### Additional Options

- `enabled`: boolean | optional

Set to false to disable the plugin. Defaults to true.

- `init` : ClientOptions | optional

Sentry allows a variety of options to be passed into the Sentry.init() function, see the full list of options [here](https://docs.sentry.io/platforms/node/guides/express/configuration/options).

- `requestHandler` : RequestHandlerOptions | optional

Accepts options that let you decide what data should be included in the event sent to Sentry, checkout the options [here](https://docs.sentry.io/platforms/node/guides/express/configuration/options).

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

You can configure any of these options by passing them to the plugin under options:

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

const config = buildConfig({
collections: [Pages, Media],
plugins: [
sentry({
dsn: 'https://[email protected]/4505357433352176',
options: {
init: {
debug: true,
environment: 'development',
tracesSampleRate: 1.0,
},
requestHandler: {
serverName: false,
user: ['email'],
},
captureErrors: [400, 403, 404],
},
}),
],
})

export default config
```

To learn more about these options and when to use them, visit the [Sentry Docs](https://docs.sentry.io/platforms/node/guides/express/configuration/options).

## TypeScript

All types can be directly imported:

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

## Development

To actively develop or debug this plugin you can either work directly within the demo directory of this repo, or link your own project.

#### Internal Demo

This repo includes a demo of Payload that installs the plugin directly from the source code. This is the easiest way to get started. To spin up this demo, follow these steps:

1. First clone the repo
2. Then, `cd plugin-sentry && yarn && cd dev && yarn && yarn dev`
3. Now open `http://localhost:3000/admin` in your browser
4. Create a new user and sign in
5. Use the buttons to throw test errors

That's it! Changes made in `./src` will be reflected in the demo.
- [Source code](https://github.com/payloadcms/payload/tree/main/packages/plugin-sentry)
- [Documentation](https://payloadcms.com/docs/plugins/sentry)
- [Documentation source](https://github.com/payloadcms/payload/tree/main/docs/plugins/sentry.mdx)