# Sentry 插件

> Source: https://strapi.nodejs.cn/cms/plugins/sentry

🌐 Sentry plugin

Sentry 插件将 Strapi 连接到 Sentry，以报告错误并附加调试元数据。本说明文档详细介绍了安装、基于环境的配置以及在非生产环境中禁用或跳过发送事件的方法。

此插件使你能够使用 Sentry 跟踪 Strapi 应用中的错误。

🌐 This plugin enables you to track errors in your Strapi application using Sentry.

**位置**

Only usable and configurable via server code

**包名**

`@strapi/plugin-sentry`

**附加资源**

[Strapi Marketplace page](https://market.strapi.io/plugins/@strapi-plugin-sentry) [Sentry page](https://sentry.io/)

通过使用 Sentry 插件，你可以：

🌐 By using the Sentry plugin you can:

* 在 Strapi 应用启动时初始化 Sentry 实例
* 将 Strapi 应用错误作为事件发送到 Sentry
* 在 Sentry 事件中包含其他元数据以协助调试
* 公开 Strapi 服务器可用的全局 Sentry 服务

## 安装 {#installation}

🌐 Installation

通过将依赖添加到 Strapi 应用来安装 Sentry 插件，如下所示：

🌐 Install the Sentry plugin by adding the dependency to your Strapi application as follows:

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

```bash
npm install @strapi/plugin-sentry
```

## 配置 {#configuration}

🌐 Configuration

创建或编辑你的 `/config/plugins` 文件以配置 Sentry 插件。以下属性可用：

🌐 Create or edit your `/config/plugins` file to configure the Sentry plugin. The following properties are available:

| 属性 | 类型 | 默认值 | 描述 |
| --- | --- | --- |--- |
| `dsn` | 字符串 | `null` | 你的 Sentry [data source name](https://docs.sentry.io/product/sentry-basics/dsn-explainer/)。 |
| `sendMetadata` | 布尔值 | `true` | 插件是否应将附加信息（例如操作系统、浏览器等）附加到发送到 Sentry 的事件中。 |
| `init` | 对象 | `{}` | 一个在初始化期间直接传递给 Sentry 的配置对象（有关可用选项，请参见官方 [Sentry documentation](https://docs.sentry.io/platforms/node/configuration/options/) ）。 |

以下是基本配置示例：

🌐 The following is an example basic configuration:

```js title="/config/plugins.js"

module.exports = ({ env }) => ({
  // ...
  sentry: {
    enabled: true,
    config: {
      dsn: env('SENTRY_DSN'),
      sendMetadata: true,
    },
  },
  // ...
});
```

```ts title="/config/plugins.ts"

  // ...
  sentry: {
    enabled: true,
    config: {
      dsn: env('SENTRY_DSN'),
      sendMetadata: true,
    },
  },
  // ...
});
```

### 为非生产环境禁用 {#disabling-for-non-production-environments}

🌐 Disabling for non-production environments

如果在 `sentry.enabled` 为 true 的情况下将 `dsn` 属性设置为 nil 值（`null` 或 `undefined`），Sentry 插件将在正在运行的 Strapi 实例中可用，但该服务实际上不会将错误发送到 Sentry。这样可以让你编写在每个环境中都能运行的代码，而无需额外检查，但只在生产环境中将错误发送到 Sentry。

🌐 If the `dsn` property is set to a nil value (`null` or `undefined`) while `sentry.enabled` is true, the Sentry plugin will be available to use in the running Strapi instance, but the service will not actually send errors to Sentry. That allows you to write code that runs on every environment without additional checks, but only send errors to Sentry in production.

当你使用值为 nil 的 `dsn` 配置属性启动 Strapi 时，该插件将打印以下警告：<br/>`info: @strapi/plugin-sentry is disabled because no Sentry DSN was provided`

🌐 When you start Strapi with a nil `dsn` config property, the plugin will print the following warning:<br/>`info: @strapi/plugin-sentry is disabled because no Sentry DSN was provided`

你可以通过使用[`env` 工具](/cms/configurations/guides/access-cast-environment-variables)来根据环境设置 `dsn` 配置属性，从而利用这一点。

🌐 You can make use of that by using the [`env` utility](/cms/configurations/guides/access-cast-environment-variables) to set the `dsn` configuration property depending on the environment.

```js title="/config/plugins.js"
module.exports = ({ env }) => ({
  // …
  sentry: {
    enabled: true,
    config: {
      // Only set `dsn` property in production
      dsn: env('NODE_ENV') === 'production' ? env('SENTRY_DSN') : null,
    },
  },
  // …
});
```

```ts title="/config/plugins.ts"

  // …
  sentry: {
    enabled: true,
    config: {
      // Only set `dsn` property in production
      dsn: env('NODE_ENV') === 'production' ? env('SENTRY_DSN') : null,
    },
  },
  // …
});
```

### 完全禁用插件 {#disabling-the-plugin-completely}

🌐 Disabling the plugin completely

像其他所有 Strapi 插件一样，你也可以在插件配置文件中禁用此插件。这将导致 `strapi.plugins('sentry')` 返回 `undefined`：

🌐 Like every other Strapi plugin, you can also disable this plugin in the plugins configuration file. This will cause `strapi.plugins('sentry')` to return `undefined`:

```js title="/config/plugins.js"
module.exports = ({ env }) => ({
  // …
  sentry: {
    enabled: false,
  },
  // …
});
```

```ts title="/config/plugins.ts"

  // …
  sentry: {
    enabled: false,
  },
  // …
});
```

## 使用 {#usage}

🌐 Usage

安装并配置插件后，你可以在 Strapi 应用中访问 Sentry 服务，如下所示：

🌐 After installing and configuring the plugin, you can access a Sentry service in your Strapi application as follows:

```js
const sentryService = strapi.plugin('sentry').service('sentry');
```

该服务公开了以下方法：

🌐 This service exposes the following methods:

| 方法 | 描述 | 参数 |
| --- | --- | --- |
| `sendError()` | 手动将错误发送到 Sentry。 | <ul><li><code>error</code>：要发送的错误。</li><li><code>configureScope</code>：可选。允许你自定义错误事件。</li></ul> 详情请参见官方 [Sentry documentation](https://docs.sentry.io/platforms/node/enriching-events/scopes/#configuring-the-scope) 。 |
| `getInstance()` | 用于直接访问 Sentry 实例。 | - |

`sendError()` 方法可以如下使用：

🌐 The `sendError()` method can be used as follows:

```js
try {
  // Your code here
} catch (error) {
  // Either send a simple error
  strapi
    .plugin('sentry')
    .service('sentry')
    .sendError(error);

  // Or send an error with a customized Sentry scope
  strapi
    .plugin('sentry')
    .service('sentry')
    .sendError(error, (scope, sentryInstance) => {
      // Customize the scope here
      scope.setTag('my_custom_tag', 'Tag value');
    });
  throw error;
}
```

`getInstance()` 方法可通过以下方式访问：

🌐 The `getInstance()` method is accessible as follows:

```js
const sentryInstance = strapi
  .plugin('sentry')
  .service('sentry')
  .getInstance();
```