顶级开源项目 Sentry 20.x JS-SDK 设计艺术(概述篇)
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
接受以下内容编码:
传输编码
建议仅对非常大的请求使用传输编码(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
公众号:黑客下午茶
加我微信(互相学习交流),关注公众号(获取更多学习资料~)
顶级开源项目 Sentry 20.x JS-SDK 设计艺术(概述篇)的更多相关文章
- 顶级开源项目 Sentry 20.x JS-SDK 设计艺术(Unified API篇)
SDK 开发 顶级开源项目 Sentry 20.x JS-SDK 设计艺术(理念与设计原则篇) 顶级开源项目 Sentry 20.x JS-SDK 设计艺术(开发基础篇) 顶级开源项目 Sentry ...
- 如何从零开始参与 Apache 顶级开源项目?| 墙裂推荐
写在开头 从 2021 开始,有一个很有意思的说法经常在各大技术媒体或开源论坛中出现,「开源正在吞噬一切」.不论是否言过其实,从一个行业从业者的切身感知来看,开源确实从少数极客的小众文化成为主流的 ...
- Java 开发者必须了解的 16 个Java 顶级开源项目!
本文已经收录自笔者开源的 JavaGuide: https://github.com/Snailclimb/JavaGuide ([Java学习+面试指南] 一份涵盖大部分Java程序员所需要掌握的核 ...
- 开源项目SMSS开源项目(三)——protobuf协议设计
本文的第一部分将介绍protobuf使用基础以及如何利用protobuf设计通信协议.第二部分会给出smss项目的协议设计规范和源码讲解. 一.Protobuf使用基础 什么是protobuf pro ...
- 准备开一个地图SDK的开源项目
最近有点空闲时间了, 准备开一个地图SDK的开源项目, 现在的地图SDK已经有很多了, 再做一个跟重新发明个轮子差不多, 但还想做的原因是想在别的轮子的基础上造个轮子... 初步设想是基于开源的地图渲 ...
- apache基金会开源项目简介
apache基金会开源项目简介 项目名称 描述 HTTP Server 互联网上首屈一指的HTTP服务器 Abdera Apache Abdera项目的目标是建立一个功能完备,高效能的IETF ...
- apache开源项目--CouchDB
Apache CouchDB 是一个面向文档的数据库管理系统.它提供以 JSON 作为数据格式的 REST 接口来对其进行操作,并可以通过视图来操纵文档的组织和呈现. CouchDB 是 Apache ...
- 2015十大顶级开源ERP系统点评
如今,企业资源规划(ERP)和客户关系管理(CRM)系统的必要性已经被各种组织和企业所认可:ERP和CRM能够直接为企业的业务效率和利润做出贡献. 但是随着今天企业商业形态的日趋多样化,互联网新经济的 ...
- 分享:10 大顶级开源 ERP 系统
10 大顶级开源 ERP 系统 企业资源规划(ERP)和客户关系管理(CRM)系统现在已经成为各种组织和企业的必需品,通过它们,可以轻松实现企业的信息数据标准化.系统运行集成化.业务流程合理化.绩效监 ...
随机推荐
- WPF 之路由事件和附加事件(六)
一.消息驱动与直接事件模型 事件的前身是消息(Message).Windows 是消息驱动的系统,运行其上的程序也遵循这个原则.消息的本质就是一条数据,这条消息里面包含着消息的类别,必要的时候还记 ...
- 找工作面试题记录与参考资料(Golang/C++/计算机网络/操作系统/算法等)
记录下去年(2020年)找工作的面试题及参考资料. C++ 智能指针的实现原理 多态的实现原理[2] C++11/14/17新特性[3] 手写memcpy和memmove[4] 介绍下boost库 计 ...
- 在Python中使用BeautifulSoup进行网页爬取
目录 什么是网页抓取? 为什么我们要从互联网上抓取数据? 网站采集合法吗? HTTP请求/响应模型 创建网络爬虫 步骤1:浏览并检查网站/网页 步骤2:创建用户代理 步骤3:导入请求库 检查状态码 步 ...
- 如何加入VNT Hubble主网
环境:Ubuntu20.04 (但以下方法应该只要不是过于老旧的Ubuntu,都行得通) 从源码安装go-vnt 安装Go编译器(版本大于1.9)和C编译器 安装C编译器GCC[1] sudo apt ...
- codeforces 870C
C. Maximum splitting time limit per test 2 seconds memory limit per test 256 megabytes input standar ...
- Leetcode(14)-最长公共前缀
编写一个函数来查找字符串数组中的最长公共前缀. 如果不存在公共前缀,返回空字符串 "". 示例 1: 输入: ["flower","flow" ...
- Error: Cannot find module 'koa-router'
Error: Cannot find module 'koa-router' koa-router !== koa-route # install OK $ yarn add koa-router h ...
- CSS Modules in depth
CSS Modules in depth https://github.com/css-modules/css-modules https://webpack.js.org/loaders/css-l ...
- c++ 获取和设置 窗口标题
有些窗口标题中含有中文,可能识别不出来,可以改一下 SetWindowTextW GetWindowTextW 设置: SetWindowTextW( (HWND)0x00370868/*窗口句柄*/ ...
- Python算法_两数之和(01)
给定一个整数数组 nums 和一个目标值 target,请你在该数组中找出和为目标值的那 两个 整数,并返回他们的数组下标. 你可以假设每种输入只会对应一个答案.但是,数组中同一个元素不能使用两遍. ...