顶级开源项目 Sentry 20.x JS-SDK 设计艺术（概述篇）

概述

下面是一个实现新的 Sentry SDK 的指南。它涵盖了事件提交的协议，以及客户端的典型外观和行为准则。

编写一个SDK

SDK 的核心是一组实用程序，用于捕获有关应用程序中异常状态的数据。给定此数据后，它将构建并发送 JSON 有效负载并将其发送到 Sentry 服务器。

预计可用于生产环境的 SDK 包括以下各项：

• DSN配置
  
• 优雅故障（例如 Sentry 服务器不可达）
  
• 设置属性（例如 tags 和 extra data）
  
• 支持 Linux，Windows 和 OS X（如果适用）
  

以下情况需要基于 Feature 的支持：

• 如果有 Cookie 数据可用，则默认情况下不会发送
  
• 如果有 POST 数据，则默认情况下不会发送
  

此外，强烈建议您使用以下功能：

• 自动错误捕获（例如，未捕获的异常处理程序 uncaught exception）
  
• 日志框架集成
  
• 非阻塞事件提交
  
• 上下文数据助手（例如，设置当前用户，记录面包屑）
  
• 事件取样
  
• Honor Sentry 的 HTTP 429 Retry-After header
  
• 事件前和事件后发送钩子
  
• 堆栈跟踪中的局部变量值（在可能的平台上）
  
• 为每个事件发送一个 environment。如果用户没有检测到或设置任何值，则应该使用 production。
  

请参阅 features 页面，以获取有关常见的 Sentry SDK 功能的描述。

最终用户的用法

通常，对于最终用户来说，使用 SDK 包括三个步骤，无论使用哪种语言，这三个步骤看起来几乎是相同的：

1. SDK 的初始化（有时对用户隐藏）：
   

JavaScript

Sentry.init({dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0'});

Python

Sentry.init({dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0'});

2. 捕获事件：
   

JavaScript

var resultId = Sentry.captureException(myException);

Python

result_id = sentry_sdk.capture_exception(my_exception);

3. 使用事件捕获的结果：
   

JavaScript

alert(`Your exception was recorded as ${resultId}`);

Python

print('Your exception was recorded as %s', result_id);

理想情况下，init 允许多种配置方法。第一个参数应该总是 DSN 值（如果可能的话）：

JavaScript

Sentry.init({
    'dsn': 'https://examplePublicKey@o0.ingest.sentry.io/0',
    'foo': 'bar'
})

请注意：SDK 应接受一个空的 DSN 作为有效配置。如果未初始化 SDK，或者使用空 DSN 初始化了 SDK，则 SDK 不应通过网络发送任何数据，例如捕获的异常。根据平台的不同，SDK 可能会避免执行不必要的初始化工作，并将其运行时占用空间降至最低。

此外，你应该提供全局函数来捕捉基本消息或异常：

• Sentry.captureMessage(message)
  
• Sentry.captureException(exception)

解析DSN

鼓励SDK通过构造函数允许任意选项，但必须允许第一个参数作为DSN字符串。该字符串包含以下位：

'{PROTOCOL}://{PUBLIC_KEY}:{SECRET_KEY}@{HOST}{PATH}/{PROJECT_ID}'

您将向其发送请求的最终端点按照以下方式构造：

{BASE_URI} = '{PROTOCOL}://{HOST}{PATH}'
'{BASE_URI}/api/{PROJECT_ID}/{ENDPOINT}/'

Sentry 提供以下端点：

• /envelope/ 用于使用 Envelopes 的任何提交。
  
• /store/ 用于提交简单的 JSON 事件。
  
• /minidump/ 用于包含 minidump 的 multipart 请求。
  
• /unreal/ 用于虚幻引擎4崩溃报告。
  
• /security/ 用于浏览器 CSP 报告，通常在浏览器而不是 SDK 中进行配置。
  

有关如何组成适当的请求有效负载的信息，请查看相应的端点。

例如，给定以下构造函数：

Sentry.init({dsn: 'https://public@sentry.example.com/1'})

您应该解析以下设置：

• URI = https://sentry.example.com
  
• Public Key = public
  
• Project ID = 1
  

对于纯 JSON 有效负载的最终 POST 请求随后将传输到：

'https://sentry.example.com/api/1/store/'

请注意：DSN 的 secret 部分是可选的，目前已被弃用。如果提供的 Sentry 的未来版本将完全忽略它，clients 仍然应该尊重它。DSN 解析代码不得要求设置 secret key。

认证

预期将与消息正文（message body）一起发送身份验证标头（authentication header），该消息标头用作所有权标识符（ownership identifier）：

X-Sentry-Auth: Sentry sentry_version=7,
  sentry_client=<client version, arbitrary>,
  sentry_timestamp=<current timestamp>,
  sentry_key=<public api key>,
  sentry_secret=<secret api key>

仅当 DSN 中包含 secret key 部分时，才必须包含 sentry_secret。协议的未来版本将完全弃用 secret key。

请注意： 您应该在标头的 User-Agent 部分中包含 SDK 版本字符串，如果 auth 标头中未发送 sentry_client ，则将使用该字符串。

在无法发送自定义 X-Sentry-Auth 标头的情况下，可以通过查询字符串发送以下值：

?sentry_version=7&sentry_key=<public api key>&sentry_secret=<secret api key>...

sentry_key

• 必需的。public key 应作为 SDK 配置的一部分提供。
  

sentry_version

• 必需的。协议版本。该协议的当前版本为 7。
  

sentry_client

• 标识 SDK（包括其版本）的任意字符串。典型的模式是 client_name/client_version。
  

例如，Python SDK 可能会将其作为 raven-python/1.0 发送。

sentry_timestamp

• Unix 时间戳，表示生成此事件的时间。
  

sentry_secret

• 应该作为 SDK 配置的一部分提供的密钥。
  

该 key 已被有效弃用，但由于某些较早的 Sentry 版本在大多数情况下都需要它，因此 SDK 仍应暂时释放该 key。该 secret key 将在Sentry的未来版本中完全淘汰。

HTTP Headers

我们建议始终发送以下标头：

• content-type
  
• content-length
  

根据 CORS 的策略，允许以下附加头：

• x-sentry-auth
  
• x-requested-with
  
• x-forwarded-for
  
• origin
  
• referer
  
• accept
  
• authentication
  
• authorization
  
• content-encoding
  
• transfer-encoding

请求压缩

强烈建议 SDK 在将请求正文发送到服务器之前先对其进行压缩，以保持数据量较小。首选方法是发送 content-encoding 标头。 Relay 和 Sentry 接受以下内容编码：

• gzip：使用 LZ77 压缩算法。
  
• deflate：使用 zlib 结构与 deflate 压缩算法。
  
• br：使用 Brotli 算法。

传输编码

建议仅对非常大的请求使用传输编码（Transfer Encoding）。将标头设置为 transfer-encoding: chunked，这可以省略 content-length 标头，并要求将请求主体包装到 chunk 标头中。

有关更多详细信息，请参见 MDN。

读取响应

成功后，您将从服务器收到一个 HTTP 响应，其中包含 JSON 有效负载以及有关已提交有效负载的信息：

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "fc6d8c0c43fc4630ad850ee518f1b9d0"
}

请注意 Sentry 将使用的响应代码。始终检查 200 响应，这将确认消息已交付。一个小级别的验证会立即发生，这可能会导致不同的响应代码（和消息）。

处理错误

我们强烈建议您的 SDK 妥善处理来自 Sentry 服务器的故障。具体来说，SDK 必须遵守 429 状态代码，并且在 Retry-After 之前不要尝试发送。如果 Sentry 不可用，则 SDK 应该丢弃事件，而不是重试。

要在开发过程中调试错误，请检查响应标头和响应正文。例如，您可能会收到类似于以下内容的响应：

HTTP/1.1 400 Bad Request
Content-Type: application/json
X-Sentry-Error: failed to read request body
{
  "detail":"failed to read request body",
  "causes":[
    "failed to decode zlib payload",
    "corrupt deflate stream"
  ]
}

X-Sentry-Error 标头和响应正文并不总是包含一条消息，但是它们仍然可以帮助调试客户端。发出时，它们将包含精确的错误消息，这对于识别根本原因很有用。

请注意： 我们不建议即使错误响应标头中声明了 Retry-After，SDK 也不会在发生错误时自动重试事件提交。如果请求一次失败，则很有可能在下一次尝试时再次失败。重试次数过多可能会导致进一步的速率限制或 Sentry 服务器的阻塞。

并发（作用域 Scope 和集线器 Hub）

SDK 应该通过 hubs 和 scopes 的概念来提供标准化的并发处理。统一 API 文档的“并发性”一章中对此进行了更详细的说明。

集成层

SDK 在可能的情况下应该在较低的层次上集成，这样可以捕获尽可能多的运行时。这意味着，如果 SDK 可以直接挂钩运行时或框架，这比要求用户子类化特定基类（或混合使用 helper）更可取。例如，Python SDK 将在框架中对核心功能进行 monkey 补丁，以自动拾取错误并集成作用域处理。