docs: adds sentry to plugin docs (#6475)
This commit is contained in:
Jessica Chowdhury
committed by
GitHub
GitHub
parent
425576be25
commit
511908a964
133
docs/plugins/sentry.mdx
Normal file
133
docs/plugins/sentry.mdx
Normal file
@@ -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
|
||||
---
|
||||
|
||||
[](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://61edebas776889984d323d777@o4505289711681536.ingest.sentry.io/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://61edebas777689984d323d777@o4505289711681536.ingest.sentry.io/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'
|
||||
```
|
||||
@@ -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://61edebas777889984d323d777@o4505289711681536.ingest.sentry.io/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://61edebas777889984d323d777@o4505289711681536.ingest.sentry.io/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)
|
||||
|
||||
Reference in New Issue
Block a user