Skip to main content

Sentry 插件

¥Sentry plugin

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

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

插件的身份证

位置:仅可通过服务器代码使用和配置。
包名称：@strapi/plugin-sentry
其他资源：Strapi 市场页面 , Sentry 页面 

¥ Location: Only usable and configurable via server code.
Package name: @strapi/plugin-sentry
Additional resources: Strapi Marketplace page , Sentry page 

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

¥By using the Sentry plugin you can:

  • 在 Strapi 应用启动时初始化 Sentry 实例

    ¥Initialize a Sentry instance upon startup of a Strapi application

  • 将 Strapi 应用错误作为事件发送到 Sentry

    ¥Send Strapi application errors as events to Sentry

  • 在 Sentry 事件中包含其他元数据以协助调试

    ¥Include additional metadata in Sentry events to assist in debugging

  • 公开 Strapi 服务器可用的全局 Sentry 服务

    ¥Expose a global Sentry service usable by the Strapi server

安装​

¥Installation

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

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

yarn add @strapi/plugin-sentry

配置​

¥Configuration

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

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

属性类型默认值描述
dsnstringnull你的 Sentry 数据源名称 。
sendMetadata布尔值true插件是否应将其他信息（例如操作系统、浏览器等）附加到发送到 Sentry 的事件。
initobject{}初始化期间直接传递给 Sentry 的配置对象（有关可用选项，请参阅官方 Sentry 文档 ）。

以下是基本配置示例：

¥The following is an example basic configuration:

/config/plugins.js

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

在非生产环境中禁用​

¥Disabling for non-production environments

如果 dsn 属性设置为零值（null 或 undefined），而 sentry.enabled 为真，则 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 时，插件将打印以下警告：
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:
info: @strapi/plugin-sentry is disabled because no Sentry DSN was provided

你可以利用 env 实用程序 根据环境设置 dsn 配置属性来利用它。

¥You can make use of that by using the env utility to set the dsn configuration property depending on the environment.

/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,
    },
  },
  // …
});

完全禁用插件​

¥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:

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

用法​

¥Usage

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

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



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


该服务公开了以下方法：

¥This service exposes the following methods:

方法描述参数
sendError()手动将错误发送到 Sentry。
getInstance()用于直接访问 Sentry 实例。*

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

¥The sendError() method can be used as follows:

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:



const sentryInstance = strapi


  .plugin('sentry')
  .service('sentry')
  .getInstance();