Sentry For React 完整接入详解(2021 Sentry v21.8.x)前方高能预警！三万字，慎入！（二）

Release & 运行状况

Release 是部署到环境中的代码版本。当您向 Sentry 提供有关您的版本的信息时，您可以：

• 确定新版本中引入的问题和回归
  
• 预测哪个提交导致了问题以及谁可能负责
  
• 通过在提交消息中包含问题编号来解决问题
  
• 部署代码时接收电子邮件通知
  

此外，release用于将 source maps 应用于被压缩的 JavaScript 以查看原始的、未转换的源代码。

绑定版本

配置客户端 SDK 时包含 release ID（通常称为“版本 version”）。

release 名称不能：

• 包含换行符、制表符、正斜杠 (/) 或反斜杠 (\)
  
• 是（全部）句号 (.)、双句号 (..) 或空格 ( )
  
• 超过 200 个字符
  

该值可以是任意的，但我们推荐以下任一命名策略：

• 语义版本控制：package@version 或 package@version+build（例如，my.project.name@2.3.12+1234）
  

• package 是 project/app 的唯一标识符（iOS 上的 CFBundleIdentifier，Android 上的 packageName）
  
• version 是类似于 semver 的结构 ...-（iOS 上的 CFBundleShortVersionString，Android 上的 versionName）
  
• build 是标识 app 迭代的数字（iOS 上的 CFBundleVersion，Android 上的 versionCode）
  

• Commit SHA： 如果您使用 DVCS，我们建议使用标识哈希 identifying hash（例如，commit SHA，da39a3ee5e6b4b0d3255bfef95601890afd80709）。您可以让 Sentry CLI 使用 sentry-clireleases proposal-version 为支持的版本控制系统自动确定此哈希值。
  

每个组织的发布都是全局性的；为它们添加特定于项目的前缀，以便于区分。

Sentry.init({
  release: "my-project-name@2.3.12",
});

在 Node/npm 环境中使用 JavaScript 执行此操作的一种常见方法是使用 process.env.npm_package_version ，如下所示：

• 更多：https://docs.npmjs.com/misc/scripts#packagejson-vars

Sentry.init({
  release: "my-project-name@" + process.env.npm_package_version,
});

您如何使版本(version)可用于您的代码取决于您。例如，您可以使用在构建过程中设置的环境变量。

这用 release 值标记每个事件。我们建议您在部署之前告诉 Sentry 一个新 release，因为这将解锁我们关于 releases 的文档中讨论的更多功能。但是，如果您不这样做，Sentry 将在第一次看到具有该 release ID 的事件时自动在系统中创建一个 release 实体。

• release:https://docs.sentry.io/product/releases/
  

配置您的 SDK 后，您可以安装 repository integration 或手动为 Sentry 提供您自己的 commit metadata。阅读我们关于设置 releases 的文档，以获取有关集成 integrations、关联提交 associating commits以及在部署 releases 时通知 Sentry 的更多信息。

• 设置 releases: https://docs.sentry.io/product/releases/setup/
  

Release 运行状况

通过观察用户采用情况、应用程序使用情况、崩溃百分比和会话数据来监控 release 的运行状况。 release 运行状况将深入了解与用户体验相关的崩溃和错误的影响，并通过 release 详细信息、图表和过滤器揭示每个新问题的趋势。

• health of releases : https://docs.sentry.io/product/releases/health/
  
• crashes：https://docs.sentry.io/product/releases/health/#crash
  
• session data：https://docs.sentry.io/product/releases/health/#session
  

SDK 将在 SDK 初始化时自动管理会话的开始和结束。

我们为每个页面加载创建一个会话。对于单页应用程序，我们将为每次导航更改（History API）创建一个新会话。

我们将会话标记为：

• 如果unhandled error 或 unhandled promise rejection 冒泡到全局处理程序，则崩溃。
  
• 如果 SDK 捕获包含异常的事件（这包括手动捕获的错误），则会出现错误。
  

要接收有关用户采用的数据，例如用户崩溃率百分比和采用特定版本的用户数，请在初始化 SDK 时将用户设置在 initialScope 上。

默认情况下，JavaScript SDK 正在发送会话。要禁用发送会话，请将 autoSessionTracking 标志设置为 false：

Sentry.init({
  autoSessionTracking: false // default: true
});

环境

Sentry 在收到带有 environment 标签的事件时会自动创建环境。环境区分大小写。环境名称不能包含换行符、空格或正斜杠，不能是字符串“None”或超过 64 个字符。您无法删除环境，但可以隐藏它们。

• hidden-environments: https://docs.sentry.io/product/sentry-basics/environments/#hidden-environments

Sentry.init({
  environment: "production",
});

环境可帮助您在 sentry.io 的问题详细信息页面中更好地过滤问题、版本和用户反馈，您可以在我们涵盖使用环境的文档中了解更多信息。

• environments：https://docs.sentry.io/product/sentry-basics/environments/

过滤

将 Sentry 添加到您的应用程序可为您提供大量关于错误和性能的非常有价值的信息，否则您将无法获得这些信息。大量的信息是好的——只要它是正确的信息，并且数量合理。

Sentry SDK 有几个配置选项可以帮助您过滤事件。

我们还提供入站过滤器 Inbound Filters来过滤 sentry.io 中的事件。不过，我们建议在客户端级别进行过滤，因为它消除了发送您实际上不想要的事件的开销。了解有关事件中可用字段的更多信息。

• Inbound Filters: https://docs.sentry.io/product/data-management-settings/filtering/
  
• fields available in an event：https://develop.sentry.dev/sdk/event-payloads/

过滤错误事件

通过使用 beforeSend 回调方法和配置、启用或禁用集成来配置您的 SDK 以过滤错误事件。

使用 beforeSend

所有 Sentry SDK 都支持 beforeSend 回调方法。beforeSend 在事件发送到服务器之前立即调用，因此它是您可以编辑其数据的最后位置。它将事件对象作为参数接收，因此您可以使用该参数根据自定义逻辑和事件上可用的数据修改事件的数据或完全删除它（通过返回 null）。

Sentry.init({
  // ...
  beforeSend(event, hint) {
    const error = hint.originalException;
    if (
      error &&
      error.message &&
      error.message.match(/database unavailable/i)
    ) {
      event.fingerprint = ["database-unavailable"];
    }
    return event;
  },
});

还要注意，正如我们的 breadcrumbs 文档中所讨论的，breadcrumbs 可以被过滤。

• breadcrumbs: https://docs.sentry.io/product/error-monitoring/breadcrumbs/
  

Event Hints

before-send 回调传递 event 和第二个参数 hint，该参数包含一个或多个 hints。

通常，hint 保存原始异常，以便可以提取附加数据或影响分组。在本例中，如果捕获到某种类型的异常，指纹将被强制为一个公共值：

Sentry.init({
  // ...
  beforeSend(event, hint) {
    const error = hint.originalException;
    if (
      error &&
      error.message &&
      error.message.match(/database unavailable/i)
    ) {
      event.fingerprint = ["database-unavailable"];
    }
    return event;
  },
});

有关哪些 hints 可用的信息，请参阅：

• hints in JavaScript: https://docs.sentry.io/platforms/javascript/guides/react/configuration/filtering/#using-hints

当 SDK 创建用于传输(transmission)的事件或面包屑时，该传输通常是从某种源对象创建的。例如，错误事件通常是从日志记录或异常实例中创建的。为了更好地定制，SDK 将这些对象发送到某些回调（beforeSend、beforeBreadcrumb 或 SDK 中的事件处理器系统）。

使用 Hints

Hints 可在两个地方获得：

1. beforeSend / beforeBreadcrumb
   
2. eventProcessors
   

事件和面包屑 hints 是包含用于组合事件或面包屑的各种信息的对象。通常 hints 保存原始异常，以便可以提取附加数据或影响分组。

对于事件，例如 event_id、originalException、syntheticException（在内部用于生成更清晰的堆栈跟踪）以及您附加的任何其他任意数据。

对于面包屑，hints 的使用取决于实现。对于 XHR 请求，hint 包含 xhr 对象本身；对于用户交互，提示包含 DOM 元素和事件名称等。

在本例中，如果捕获到某种类型的异常，指纹将被强制为一个公共值：

Sentry.init({
  // ...
  beforeSend(event, hint) {
    const error = hint.originalException;
    if (
      error &&
      error.message &&
      error.message.match(/database unavailable/i)
    ) {
      event.fingerprint = ["database-unavailable"];
    }
    return event;
  },
});

Hints for Events

originalException

导致 Sentry SDK 创建事件的原始异常。这对于更改 Sentry SDK 分组事件的方式或提取附加信息很有用。

syntheticException

当引发字符串(string)或非错误(non-error)对象时，Sentry 会创建一个合成异常(synthetic exception)，以便您可以获得基本的堆栈跟踪。此异常存储在此处以供进一步提取数据。

Hints for Breadcrumbs

event

对于从浏览器事件创建的面包屑，Sentry SDK 通常将事件作为 hint 提供给面包屑。例如，这可用于将目标 DOM 元素中的数据提取到面包屑中。

level / input

对于从控制台日志(console.log)拦截创建的面包屑。这保存了原始 console log level 和 log function 的原始输入数据。

response / input

对于从 HTTP 请求创建的面包屑。它保存响应对象（来自 fetch API）和 fetch 函数的输入参数。

request / response / event

对于从 HTTP 请求创建的面包屑。这包含请求和响应对象（来自 node HTTP API）以及 node event（response或error）。

xhr

对于通过遗留 XMLHttpRequest API 完成的 HTTP 请求创建的面包屑。这保存了原始的 xhr 对象。

整理 Sentry

您可以构建一个允许的域列表，这些域可能会引发可接受的异常。例如，如果您的脚本是从 cdn.example.com 加载的并且您的站点是 example.com，您可以将 allowUrls 设置为：

Sentry.init({
  allowUrls: [
    /https?:\/\/((cdn|www)\.)?example\.com/
  ]
});

如果您想永远阻止特定的 URL，您也可以使用 denyUrls。

Note 在 5.17.0 版本之前，allowUrls 和 denyUrls 分别称为 whitelistUrls 和 blacklistUrls。出于向后兼容性的原因，这些选项仍受支持，但它们将在 6.0 版中删除。有关更多信息，请参阅

Inclusive Language Policy：https://develop.sentry.dev/inclusion/

此外，我们的社区还为日常事务编制了一份常见的忽略规则列表，例如 Facebook、Chrome extensions 等。这很有用，建议您检查一下这些内容，看看它们是否适用于您。这不是我们 SDK 的默认值；这只是一个广泛示例的一个亮点。

• Here is the original gist：https://gist.github.com/impressiver/5092952

Sentry.init({
  ignoreErrors: [
    // Random plugins/extensions
    "top.GLOBALS",
    // See: http://blog.errorception.com/2012/03/tale-of-unfindable-js-error.html
    "originalCreateNotification",
    "canvas.contentDocument",
    "MyApp_RemoveAllHighlights",
    "http://tt.epicplay.com",
    "Can't find variable: ZiteReader",
    "jigsaw is not defined",
    "ComboSearch is not defined",
    "http://loading.retry.widdit.com/",
    "atomicFindClose",
    // Facebook borked
    "fb_xd_fragment",
    // ISP "optimizing" proxy - `Cache-Control: no-transform` seems to
    // reduce this. (thanks @acdha)
    // See http://stackoverflow.com/questions/4113268
    "bmi_SafeAddOnload",
    "EBCallBackMessageReceived",
    // See http://toolbar.conduit.com/Developer/HtmlAndGadget/Methods/JSInjection.aspx
    "conduitPage",
  ],
  denyUrls: [
    // Facebook flakiness
    /graph\.facebook\.com/i,
    // Facebook blocked
    /connect\.facebook\.net\/en_US\/all\.js/i,
    // Woopra flakiness
    /eatdifferent\.com\.woopra-ns\.com/i,
    /static\.woopra\.com\/js\/woopra\.js/i,
    // Chrome extensions
    /extensions\//i,
    /^chrome:\/\//i,
    // Other plugins
    /127\.0\.0\.1:4001\/isrunning/i, // Cacaoweb
    /webappstoolbarba\.texthelp\.com\//i,
    /metrics\.itunes\.apple\.com\.edgesuite\.net\//i,
  ],
});

使用采样过滤 Transaction 事件

为了防止某些 transactions 被报告给 Sentry，请使用 tracesSampler 配置选项，它允许您提供一个函数来评估当前 transaction 并在它不是您想要的时候删除它。（它还允许您以不同的采样率对不同的 transaction 进行抽样。）

注意：tracesSampler 和 tracesSampleRate 配置选项是互斥的。如果您定义了一个 tracesSampler 来过滤掉某些 transaction，您还必须通过返回您希望对它们进行采样的速率来处理未过滤 transaction 的情况。

最简单的形式，仅用于过滤 transaction，它看起来像这样：

Sentry.init({
  // ...
  tracesSampler: samplingContext => {
    if ("...") {
      // Drop this transaction, by setting its sample rate to 0%
      return 0;
    } else {
      // Default sample rate for all others (replaces tracesSampleRate)
      return 0.1;
    }
  };
});

关闭与清空

大多数 SDK 的默认行为是在后台通过网络异步发送事件。这意味着如果应用程序意外关闭，某些事件可能会丢失。SDK 提供了处理这种情况的机制。

close 方法可选地接受以毫秒为单位的 timeout，并返回一个 promise，该 promise 在刷新所有挂起事件或 timeout 生效时 resolve。

Sentry.close(2000).then(function() {
  // perform something after close
});

调用 close 后，不能再使用当前客户端。仅在关闭应用程序之前立即调用 close 很重要。

或者，flush 方法清空事件队列，同时保持客户端启用以供继续使用。

采样

将 Sentry 添加到您的应用程序可为您提供大量关于错误和性能的非常有价值的信息，否则您将无法获得这些信息。大量的信息是好的——只要它是正确的信息，并且数量合理。

采样 Error 事件

要将具有代表性的错误样本发送到 Sentry，请将 SDK 配置中的 sampleRate 选项设置为 0（发送的错误的 0%）和 1（发送的错误的 100%）之间的数字。这是一个静态比率，它同样适用于所有错误。例如，要对 25% 的错误进行抽样：

Sentry.init({ sampleRate: 0.25 });

更改错误采样率需要重新部署。此外，设置 SDK 采样率会限制对事件源的可见性。为您的项目设置速率限制（仅在 volume 高时丢弃事件）可能更适合您的需求。

采样 Transaction 事件

我们建议对您的 transaction 进行抽样，原因有两个：

1. 捕获单个跟踪涉及的开销最小，但捕获每个页面加载或每个 API 请求的跟踪可能会给您的系统增加不必要的负载。
   
2. 启用采样可以让您更好地管理发送到 Sentry 的事件数量，因此您可以根据组织的需求定制您的数量。
   

选择采样率的目标是在性能和数量问题与数据准确性之间找到平衡。您不想收集太多数据，但希望收集足够的数据以得出有意义的结论。如果您不确定要选择什么速率，请从一个较低的值开始，随着您对流量模式和流量的了解越来越多，逐渐增加它。

配置 Transaction 采样率

Sentry SDK 有两个配置选项来控制发送到 Sentry 的 transaction 量，让您可以获取具有代表性的样本：

1. 统一采样率（tracesSampleRate）：
   

• 提供均匀的事务横截面，无论它们在您的应用程序中的哪个位置或在什么情况下发生。
  
• 使用默认继承(inheritance)和优先(precedence)行为
  

2. 采样函数（tracesSampler）其中：
   

• 以不同的速率采样不同的 transaction
  
• 完全过滤掉一些 transaction
  
• 修改默认优先级和继承行为
  

inheritance: https://docs.sentry.io/platforms/javascript/guides/react/configuration/sampling/#inheritance

precedence: https://docs.sentry.io/platforms/javascript/guides/react/configuration/sampling/#precedence

Filters: https://docs.sentry.io/platforms/javascript/guides/react/configuration/filtering/

设置统一采样率

为此，请将 Sentry.init() 中的 tracesSampleRate 选项设置为 0 到 1 之间的数字。设置此选项后，创建的每个 transaction 都有该百分比的机会被发送到 Sentry。（因此，例如，如果您将 tracesSampleRate 设置为 0.2，大约 20% 的 transaction 将被记录和发送。）看起来像这样：

Sentry.init({
  // ...
  tracesSampleRate: 0.2,
});

设置采样函数

要使用采样函数，请将 Sentry.init() 中的 tracesSampler 选项设置为一个函数，该函数将接受 samplingContext 对象并返回介于 0 和 1 之间的采样率。例如：

Sentry.init({
  // ...
  tracesSampler: samplingContext => {
    // Examine provided context data (including parent decision, if any) along
    // with anything in the global namespace to compute the sample rate or
    // sampling decision for this transaction
    if ("...") {
      // These are important - take a big sample
      return 0.5;
    } else if ("...") {
      // These are less important or happen much more frequently - only take 1%
      return 0.01;
    } else if ("...") {
      // These aren't something worth tracking - drop all transactions like this
      return 0;
    } else {
      // Default sample rate
      return 0.1;
    }
  };
});

为方便起见，该函数还可以返回一个布尔值。返回 true 等同于返回 1，并且将保证 transaction 将发送到 Sentry。返回 false 相当于返回 0，并保证 transaction 不会被发送到 Sentry。

采样 Context 数据

默认采样 Context 数据

在 transaction 事务时传递给 tracesSampler 的 SamplingContext 对象中包含的信息因平台和集成(integration)而异。

对于基于浏览器的 SDK，它至少包括以下内容：

// contents of `samplingContext`
{
  transactionContext: {
    name: string; // human-readable identifier, like "GET /users"
    op: string; // short description of transaction type, like "pageload"
  }
  parentSampled: boolean; // if this transaction has a parent, its sampling decision
  location: Location | WorkerLocation; // the window.location or self.location object
  ... // custom context as passed to `startTransaction`
}

自定义采样 Context 数据

使用自定义检测创建 transaction 时，您可以通过将数据作为可选的第二个参数传递给 startTransaction 来将数据添加到 samplesContext。如果您希望采样器可以访问某些数据，但又不想将其作为标签(tag)或数据(data)附加到 transaction 中，例如敏感信息或太大而无法与 transaction 一起发送的信息，这将非常有用。例如：

Sentry.startTransaction(
  {
    // `transactionContext` - will be recorded on transaction
    name: 'Search from navbar',
    op: 'search',
    tags: {
      testGroup: 'A3',
      treatmentName: 'eager load',
    },
  },
  // `customSamplingContext` - won't be recorded
  {
    // PII
    userId: '12312012',
    // too big to send
    resultsFromLastSearch: { ... }
  },
);

继承

无论 transaction 的抽样决策如何，该决策都将传递到其子跨度，并从那里传递到它们随后在其他服务中引起的任何 transaction。（有关如何完成传播的更多信息，请参阅连接服务。）

• Connecting Services: https://docs.sentry.io/platforms/javascript/performance/
  

如果当前正在创建的 transaction 是那些后续事务之一（换句话说，如果它有父 transaction），则上游（父）采样决策将始终包含在采样上下文数据中，以便您的 tracesSampler 可以选择是否和何时继承该决策。（在大多数情况下，继承是正确的选择，以避免部分跟踪痕迹。）

在某些 SDK 中，为了方便起见，tracesSampler 函数可以返回一个布尔值，这样如果这是所需的行为，则可以直接返回父级的决策。

tracesSampler: samplingContext => {
  // always inherit
  if (samplingContext.parentSampled !== undefined) {
    return samplingContext.parentSampled
  }
  ...
  // rest of sampling logic here
}

如果您使用的是 tracesSampleRate 而不是 tracesSampler，则决策将始终被继承。

强制抽样决策

如果您在 transaction 创建时知道是否要将 transaction 发送到 Sentry，您还可以选择将采样决策直接传递给 transaction 构造函数（注意，不是在 customSamplingContext 对象中）。如果您这样做，transaction 将不受 tracesSampleRate 的约束，也不会运行 tracesSampler，因此您可以指望通过的决策不会被覆盖。

Sentry.startTransaction({
  name: "Search from navbar",
  sampled: true,
});

优先级

transaction 以多种方式结束抽样决策。

• 根据 tracesSampleRate 中设置的静态采样率随机采样
  
• 根据 tracesSampler 采样函数返回的采样率随机采样
  
• tracesSampler 返回的绝对决策（100% 机会或 0% 机会）
  
• 如果 transaction 有父级，继承其父级的抽样决策
  
• 绝对决策传递给 startTransaction
  

当有可能不止一个发挥作用时，以下优先规则适用：

1. 如果将抽样决策传递给 startTransaction（请参阅上面的强制抽样决策），则将使用该决策，而不管其他任何事情
   
2. 如果定义了 tracesSampler，则将使用其决策。它可以选择保留或忽略任何父采样决策，或使用采样上下文数据来做出自己的决策或为 transaction 选择采样率。
   
3. 如果未定义 tracesSampler，但存在父采样决策，则将使用父采样决策。
   
4. 如果未定义 tracesSampler 并且没有父采样决策，则将使用 tracesSampleRate。

Sentry Testkit

在为您的应用程序构建测试时，您希望断言正确的流跟踪(flow-tracking)或错误正在发送到 Sentry，但没有真正将其发送到 Sentry 服务器。这样您就不会在测试运行或其他 CI 操作期间用错误报告淹没 Sentry。

注意：Sentry 合作伙伴 Wix 维护 Sentry Testkit。

• Wix：https://wix.github.io/sentry-testkit/
  

Sentry Testkit 是一个 Sentry 插件，它允许拦截 Sentry 的 report 并进一步检查正在发送的数据。它使 Sentry 能够在您的应用程序中原生工作，并且通过覆盖默认 Sentry 的传输机制(transport mechanism)，报告不会真正发送，而是本地记录到内存中。这样，您可以稍后获取记录的报告以供您自己使用、验证或您在本地开发/测试环境中可能拥有的任何其他用途。

Sentry Testkit: https://wix.github.io/sentry-testkit/

安装

npm install sentry-testkit --save-dev

在测试中使用

const sentryTestkit = require("sentry-testkit");
const { testkit, sentryTransport } = sentryTestkit();
// initialize your Sentry instance with sentryTransport
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  transport: sentryTransport,
  //... other configurations
});
// then run any scenario that should call Sentry.catchException(...)
expect(testkit.reports()).toHaveLength(1);
const report = testkit.reports()[0];
expect(report).toHaveProperty(/*...*/);

您也可以在 sentry-testkit 存储库的测试部分看到更多使用示例。

testing section: https://github.com/wix/sentry-testkit/tree/master/test

Testkit API

Sentry Testkit 由一个非常简单直接的 API 组成。请参阅 Sentry Testkit Docs 中的完整 API 描述和文档。

Sentry Testkit Docs: https://wix.github.io/sentry-testkit/

用法

Sentry 的 SDK 与您的运行时环境挂钩，并根据平台自动报告错误、未捕获的异常和未处理的拒绝以及其他类型的错误。

关键术语：

• event 是向 Sentry 发送数据的一个实例。通常，此数据是错误(error)或异常(exception)。
  
• issue 是一组相似的事件。
  
• 事件的报告称为捕获(capturing)。当一个事件被捕获时，它被发送到 Sentry。
  

最常见的捕获形式是捕获错误。可以捕获为错误的内容因平台而异。一般来说，如果你

有一些看起来像异常的东西，它可以被捕获。对于某些 SDK，您还可以省略 captureException 的参数，Sentry 将尝试捕获当前异常。它对于手动向 Sentry 报告错误或消息也很有用。

在捕获事件时，您还可以记录导致该事件的面包屑(breadcrumbs)。面包屑与事件不同：它们不会在 Sentry 中创建事件，而是会被缓冲，直到发送下一个事件。在我们的面包屑文档中了解有关面包屑的更多信息。

breadcrumbs: https://docs.sentry.io/platforms/javascript/guides/react/enriching-events/breadcrumbs/

捕获 Errors

通过包含和配置 Sentry，我们的 React SDK 会自动附加全局处理程序(global handlers)来捕获未捕获的异常和未处理的 promise 拒绝，如官方 ECMAScript 6 标准中所述。您可以通过在 GlobalHandlers 集成中将 onunhandledrejection 选项更改为 false 并手动挂接到每个事件处理程序，然后直接调用 Sentry.captureException 或 Sentry.captureMessage 来禁用此默认行为。

您可以将 Error 对象传递给 captureException() 以将其捕获为事件。也可以传递非 Error(non-Error) 对象和字符串(string)，但请注意 Sentry 中的结果事件(resulting events)可能会丢失堆栈跟踪。

import * as Sentry from "@sentry/react";
try {
  aFunctionThatMightFail();
} catch (err) {
  Sentry.captureException(err);
}

捕获 Messages

另一种常见的操作是捕获裸消息。消息是应该发送给 Sentry 的文本信息。通常不会发出消息，但它们对某些团队很有用。

Sentry.captureMessage("Something went wrong");

设置 Level

级别 - 类似于日志级别 - 通常基于集成默认添加。您还可以在事件中覆盖它。

要设置超出范围的级别，您可以为每个事件调用 captureMessage()：

Sentry.captureMessage("this is a debug message", "debug");

要在作用域内设置级别，您可以调用 setLevel()：

Sentry.configureScope(function(scope) {
  scope.setLevel(Sentry.Severity.Warning);
});

或每个事件：

Sentry.withScope(function(scope) {
  scope.setLevel("info");
  Sentry.captureException("info");
});

SDK 指纹

所有事件都有一个指纹。具有相同指纹的事件被组合成一个 issue。

默认情况下，Sentry 将运行一种内置分组算法，以根据事件中可用的信息（如堆栈跟踪stacktrace、异常exception和消息message）生成指纹。要扩展默认分组行为或完全更改它，您可以使用以下选项的组合：

1. 在您的 SDK 中，使用 SDK 指纹识别，如下所述
   
2. 在您的项目中，使用指纹规则或堆栈跟踪规则
   

• Fingerprint Rules: https://docs.sentry.io/product/data-management-settings/event-grouping/fingerprint-rules/
  
• Stack Trace Rules：https://docs.sentry.io/product/data-management-settings/event-grouping/stack-trace-rules/
  

在受支持的sdk中，您可以覆盖 Sentry 的默认分组，该分组将指纹属性作为字符串数组传递。指纹数组的长度不受限制。这类似于指纹规则功能，它总是可用的，可以实现类似的结果。

• fingerprint-rules：https://docs.sentry.io/product/data-management-settings/event-grouping/fingerprint-rules/

基本示例

在最基本的情况下，直接传递值：

function makeRequest(method, path, options) {
  return fetch(method, path, options).catch(function(err) {
    Sentry.withScope(function(scope) {
      // group errors together based on their request and response
      scope.setFingerprint([method, path, String(err.statusCode)]);
      Sentry.captureException(err);
    });
  });
}

您可以使用变量替换将动态值填充到通常在服务器上计算的指纹中。例如，可以添加值 {{ default }} 以将整个正常生成的分组哈希添加到指纹中。这些值与服务器端指纹识别相同。有关更多信息，请参阅：

Variables: https://docs.sentry.io/product/data-management-settings/event-grouping/fingerprint-rules/#variables

以更大的粒度对错误进行分组

您的应用程序查询远程过程调用模型 (RPC) 接口或外部应用程序编程接口 (API) 服务，因此堆栈跟踪通常是相同的（即使传出请求非常不同）。

以下示例将进一步拆分 Sentry 将创建的默认组（由 {{ default }} 表示），并考虑到错误对象的一些属性：

class MyRPCError extends Error {
  constructor(message, functionName, errorCode) {
    super(message);
    // The name of the RPC function that was called (e.g. "getAllBlogArticles")
    this.functionName = functionName;
    // For example a HTTP status code returned by the server.
    this.errorCode = errorCode;
  }
}
Sentry.init({
  ...,
  beforeSend: function(event, hint) {
    const exception = hint.originalException;
    if (exception instanceof MyRPCError) {
      event.fingerprint = [
        '{{ default }}',
        String(exception.functionName),
        String(exception.errorCode)
      ];
    }
    return event;
  }
});

更进一步地分组错误

通用错误（例如数据库连接错误）具有许多不同的堆栈跟踪，并且永远不会组合在一起。

以下示例将通过从数组中省略 {{ default }} 来完全覆盖 Sentry 的分组：

class DatabaseConnectionError extends Error {}
Sentry.init({
  ...,
  beforeSend: function(event, hint) {
    const exception = hint.originalException;
    if (exception instanceof DatabaseConnectionError) {
      event.fingerprint = ['database-connection-error'];
    }
    return event;
  }
});

Source Maps

生成 Source Maps

大多数现代 JavaScript 编译器都支持 source maps。以下是一些常用工具的说明。

我们建议使用 Sentry 的 Webpack 插件来配置 source maps 并在构建过程中自动上传它们。

sentry-webpack-plugin: https://github.com/getsentry/sentry-webpack-plugin

source-map-support

要依赖 Sentry 的 source map 解析，您的代码不能使用 source-map-support 包。该包以一种阻止我们的处理器正确解析它的方式覆盖捕获的堆栈跟踪。

source-map-support：https://www.npmjs.com/package/source-map-support

Webpack

Sentry 提供了一个方便的 Webpack 插件，可以配置 source maps 并自动将它们上传到 Sentry。

要使用该插件，您首先需要安装它：

npm install --save-dev @sentry/webpack-plugin
// or
yarn add --dev @sentry/webpack-plugin

然后，配置它webpack.config.js：

const SentryWebpackPlugin = require("@sentry/webpack-plugin");
module.exports = {
  // other webpack configuration
  devtool: 'source-map',
  plugins: [
    new SentryWebpackPlugin({
      // sentry-cli configuration - can also be done directly through sentry-cli
      // see https://docs.sentry.io/product/cli/configuration/ for details
      authToken: process.env.SENTRY_AUTH_TOKEN,
      org: "example-org",
      project: "example-project",
      release: process.env.SENTRY_RELEASE,
      // other SentryWebpackPlugin configuration
      include: ".",
      ignore: ["node_modules", "webpack.config.js"],
    }),
  ],
};

此外，Webpack 插件会自动设置 window.SENTRY_RELEASE，因此您的 Sentry.init 调用不需要包含 release 值。

将 Webpack 插件设置为最后运行的插件；否则，插件收到的 source maps 可能不是最终的。

高级用法

如果您更喜欢手动上传 source maps，请配置 Webpack 去输出 source maps：

module.exports = {
  devtool: 'source-map',
  output: {
    // Make maps auto-detectable by sentry-cli
    filename: "[name].js",
    sourceMapFilename: "[name].js.map",
    // Other `output` configuration
  },
  // Other webpack configuration
};

如果您使用 SourceMapDevToolPlugin 对 source map 生成进行更细粒度的控制，请关闭 noSources，以便 Sentry 可以在事件堆栈跟踪中显示正确的源代码上下文。

SourceMapDevToolPlugin：https://webpack.js.org/plugins/source-map-dev-tool-plugin

Rollup

您可以配置 Rollup 以生成 source maps，然后您可以使用 sentry-cli 上传 source maps：

• Rollup：https://rollupjs.org/
  
• upload using sentry-cli：https://docs.sentry.io/product/cli/releases/#sentry-cli-sourcemaps

export default {
  entry: "./src/app.js",
  output: {
    file: "bundle.js",
    format: "cjs",
    sourceMap: true,
  },
};

SystemJS

SystemJS 可以配置为输出 source maps，然后您可以使用 sentry-cli 上传 source maps：

builder.bundle("src/app.js", "dist/app.min.js", {
  minify: true,
  sourceMaps: true,
  sourceMapContents: true,
});

此示例配置将您的原始、未转换的源代码内联到生成的 source map 文件中。Sentry 需要 source map 和您的原始源文件来执行反向转换。如果您选择不内联源文件，则除了 source map 外，您还必须使这些源文件可供 Sentry 使用（见下文）。

• SystemJS：https://github.com/systemjs/builder
  
• upload using sentry-cli：https://docs.sentry.io/product/cli/releases/#sentry-cli-sourcemaps

TypeScript

TypeScript 编译器可以输出 source maps，然后您可以使用 sentry-cli 上传源映射。

将 sourceRoot 属性配置为 / 以从生成的源代码引用中去除构建路径前缀。这允许 Sentry 相对于您的源根文件夹匹配源文件：

{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSources": true,
    "sourceRoot": "/"
  }
}

UglifyJS

我们强烈建议您使用更高级的打包器（或转译器），因为 UglifyJS 配置会变得非常复杂，并且很难达到预期的结果。

UglifyJS 可以配置为输出 source maps，然后您可以使用 sentry-cli 上传：

uglifyjs app.js \
  -o app.min.js.map \
  --source-map url=app.min.js.map,includeSources

UglifyJS：https://github.com/mishoo/UglifyJS