SDK 开发
- 顶级开源项目 Sentry 20.x JS-SDK 设计艺术(理念与设计原则篇)
- 顶级开源项目 Sentry 20.x JS-SDK 设计艺术(开发基础篇)
系列
- Snuba:Sentry 新的搜索基础设施(基于 ClickHouse 之上)
- Sentry 10 K8S 云原生架构探索,Vue App 1 分钟快速接入
- Sentry(v20.x)玩转前/后端监控与事件日志大数据分析,使用 Helm 部署到 K8S 集群
- Sentry(v20.x) JavaScript SDK 三种安装加载方式
- Sentry(v20.x) JavaScript SDK 配置详解
- Sentry(v20.x) JavaScript SDK 手动捕获事件基本用法
- Sentry(v20.x) JavaScript SDK Source Maps详解
- Sentry(v20.x) JavaScript SDK 故障排除
- Sentry(v20.x) JavaScript SDK 1分钟上手性能监控
- Sentry(v20.x) JavaScript SDK 性能监控之管理 Transactions
- Sentry(v20.x) JavaScript SDK 性能监控之采样 Transactions
- Sentry(v20.x) JavaScript SDK Enriching Events(丰富事件信息)
- Sentry(v20.x) JavaScript SDK Data Management(问题分组篇)
概述
下面是一个实现新的 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
包括三个步骤,无论使用哪种语言,这三个步骤看起来几乎是相同的:
- SDK 的初始化(有时对用户隐藏):
JavaScript
Sentry.init({dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0'});
Python
Sentry.init({dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0'});
- 捕获事件:
JavaScript
var resultId = Sentry.captureException(myException);
Python
result_id = sentry_sdk.capture_exception(my_exception);
- 使用事件捕获的结果:
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
补丁,以自动拾取错误并集成作用域处理。
我是为少
微信:uuhells123
公众号:黑客下午茶
加我微信(互相学习交流),关注公众号(获取更多学习资料~)