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

请注意:
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:使用 压缩算法。

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 补丁,以自动拾取错误并集成作用域处理。

我是为少 微信:uuhells123 公众号:黑客下午茶 加我微信(互相学习交流),关注公众号(获取更多学习资料~)

内容版权声明:除非注明,否则皆为本站原创文章。

转载注明出处:https://www.heiqu.com/zwpygw.html