Sentry

页面摘要： Sentry 插件将 Strapi 连接到 Sentry，以报告错误并附加调试元数据。本文档详述了安装、基于环境的配置，以及在生产环境之外禁用或跳过发送事件的方法。

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

• 位置：仅可通过服务器代码使用与配置
• 包名称：@strapi/plugin-sentry
• 其他资源：Strapi Marketplace 页面 Sentry 页面

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

• 在 Strapi 应用启动时初始化一个 Sentry 实例
• 将 Strapi 应用错误作为事件发送到 Sentry
• 在 Sentry 事件中包含额外的元数据，以辅助调试
• 暴露一个可供 Strapi 服务器使用的全局 Sentry 服务

安装

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

yarn

yarn add @strapi/plugin-sentry

npm

npm install @strapi/plugin-sentry

配置

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

以下是一个基础的配置示例：

JavaScript

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

TypeScript

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

在非生产环境中禁用

如果 dsn 属性被设为空值（null 或 undefined），而 sentry.enabled 为 true，则 Sentry 插件在运行的 Strapi 实例中仍然可用，但服务不会真正将错误发送到 Sentry。这样你就可以编写在每个环境都运行的代码而无需额外判断，但只在生产环境中向 Sentry 发送错误。

当你以空的 dsn 配置属性启动 Strapi 时，插件会打印如下警告： info: @strapi/plugin-sentry is disabled because no Sentry DSN was provided

你可以利用这一点，使用 env 工具 根据环境来设置 dsn 配置属性。

JavaScript

module.exports = ({ env }) => ({
  // …
  sentry: {
    enabled: true,
    config: {
      // 仅在 production（生产）环境中设置 `dsn` 属性
      dsn: env('NODE_ENV') === 'production' ? env('SENTRY_DSN') : null,
    },
  },
  // …
});

TypeScript

export default ({ env }) => ({
  // …
  sentry: {
    enabled: true,
    config: {
      // 仅在 production（生产）环境中设置 `dsn` 属性
      dsn: env('NODE_ENV') === 'production' ? env('SENTRY_DSN') : null,
    },
  },
  // …
});

完全禁用插件

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

JavaScript

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

TypeScript

export default ({ env }) => ({
  // …
  sentry: {
    enabled: false,
  },
  // …
});

用法

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

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

该服务暴露以下方法：

• error：要发送的错误。
• configureScope：可选。用于自定义错误事件。 更多详情请参阅官方 Sentry 文档。 | | getInstance() | 用于直接访问 Sentry 实例。 | - |

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

try {
  // 在此编写你的代码
} catch (error) {
  // 发送一个简单的错误
  strapi
    .plugin('sentry')
    .service('sentry')
    .sendError(error);

  // 或者发送一个带有自定义 Sentry scope 的错误
  strapi
    .plugin('sentry')
    .service('sentry')
    .sendError(error, (scope, sentryInstance) => {
      // 在此自定义 scope
      scope.setTag('my_custom_tag', 'Tag value');
    });
  throw error;
}

getInstance() 方法可如下访问：

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