事件是客户端通常通过使用 SDK
发送到 Sentry
服务器的基本数据。事件负载(Event payload
)大小限制为 200kb
。
接受事件有效负载的 Sentry server
上的 API
端点是 /api/{PROJECT_ID}/store/
。
属性是 Sentry
理解的简单数据,用于提供有关事件的最基本信息。这些是诸如事件的 unique ID
或事件发生的时间之类的东西。
所有事件都需要以下属性。
event_id
uuid4
值的十六进制字符串。长度正好是 32
个字符。不允许使用破折号(-
)。必须是小写。{
"event_id": "fc6d8c0c43fc4630ad850ee518f1b9d0"
}
timestamp
Sentry SDK
中创建事件的时间。格式要么是 RFC 3339 中定义的字符串,要么是表示自 Unix 纪元以来经过的秒数的数字(整数或浮点数)值。{
"timestamp": "2011-05-02T17:41:36Z"
}
或者:
{
"timestamp": 1304358096.0
}
platform
SDK
提交的平台的字符串。这将被 Sentry
接口用来定制接口中的各种组件。{
"platform": "python"
}
可接受的值为:
as3
c
cfml
cocoa
csharp
elixir
haskell
go
groovy
java
javascript
native
node
objc
other
perl
php
python
ruby
此外,Sentry
认可并高度鼓励以下几个可选值:
level
默认为 error
。
该值需要是一个支持的 level
字符串值。
{
"level": "warning"
}
可接受的值是:
fatal
error
warning
info
debug
logger
logger
的名称。{
"logger": "my.logger.name"
}
transaction
exception
的 transaction
的名称。例如,在 Web
应用程序中,这可能是路由名称。
{
"transaction": "/users/<username>/"
}
server_name
host
。{
"server_name": "foo.example.com"
}
release
发布版本在您组织中的所有项目中必须是唯一的. 该值可以是给定项目的 git SHA
,也可以是具有语义版本的产品标识符(建议格式为 my-project-name@1.0.0
)。
{
"release": "my-project-name@1.0.0"
}
{
"release": "721e41770371db95eee98ca2707686226b993eda"
}
dist
distribution
)。分发版(Distribution)
用于消除应用程序同一版本的构建或部署变体的歧义。例如,dist
可以是 XCode
构建的构建号(build number
)或 Android
构建的版本代码(version code
)。
{
"release": "721e41770371db95eee98ca2707686226b993eda",
"dist": "14G60"
}
tags
tags
的 map
或 list
,每个 tag
必须少于 200
个字符。{
"tags": {
"ios_version": "4.0",
"context": "production"
}
}
environment
production
或 staging
。{
"environment": "production"
}
modules
{
"modules": {
"my.module.name": "1.0"
}
}
extra
{
"extra": {
"my_key": 1,
"some_other_value": "foo bar"
}
}
fingerprint
{
"fingerprint": ["myrpc", "POST", "/foo.bar"]
}
{
"fingerprint": ["{{ default }}", "http://example.com/my.url"]
}
errors
: 捕获或处理此事件的错误列表。这提供了关于事件捕获和处理本身的元数据,而不是关于事件所代表的 error
或 transaction
的元数据。
该列表主要由 Sentry
在接收和处理事件时填充。如果存在 Sentry
通过检查剩余负载无法检测到的严重情况,则仅鼓励 SDK
在此处添加条目。
Errors
必须包含必需的 type
字段,该字段可以是 Sentry EventError 模型中声明的类型之一。如果没有适用的类型变体,请考虑opening an issue来建议添加。
除了 type
之外,任何属性都是有效的。如果包含常见错误属性的语义,则存在约定:
name
: 声明导致或显示 error
的 payload
字段的路径的字符串。例如 modules[0].name
。value
: 导致或显示 error
的字段的原始值。{
"errors": [
{
"type": "unknown_error",
"path": "/var/logs/errors.log.1",
"details": "Failed to read attachment"
}
]
}
Event payload
中所有不是基本属性的值都是数据接口
。key
是规范化接口的短名称,值是接口期望的数据(通常是字典)。
在大多数情况下,接口是 Sentry
不断发展的一部分。与属性一样,SDK
预计将在未来的任何时候添加更多接口。
核心数据接口是:
Exception Interface(异常接口)
Message Interface(消息接口)
Stack Trace Interface(堆栈跟踪接口)
Template Interface(模板接口)
Breadcrumbs Interface(面包屑接口)
User Interface(用户接口)
Request Interface(请求接口)
Contexts Interface(上下文接口)
Threads Interface(线程接口)
Debug Meta Interface(调试元接口)
SDK Interface(SDK 接口)
Event Type Definitions(事件类型定义)
Span
接口指定了一系列具有开始
和结束
时间的_timed(定时)
_应用程序事件。
一个 Transaction
可以在名为 spans
的数组属性中包含零个或多个 Span
。 list
中的 Span
不必排序,它们将按服务器上的开始/结束
时间排序。
虽然 Span
属性将在服务器上规范化,但当 Span
至少包含一个 op
和 description
时,它是最有用的。
span_id
:
{
"span_id": "99659d76b7cdae94"
}
parent_span_id
:
{
"parent_span_id": "b0e6f15b45c36b12"
}
trace_id
:
Span
属于哪个 trace
。该值应该是编码为十六进制字符串(32
个字符长)的 16
个随机字节。{
"trace_id": "1e57b752bc6e4544bbaa246cd1d05dee"
}
op
{
"op": "db.query"
}
description
span
操作的更长描述,它唯一地标识 span
但跨 span
实例是一致的。{
"description": "SELECT * FROM users WHERE last_active < DATE_SUB(CURRENT_DATE, INTERVAL 1 YEAR)`"
}
start_timestamp
start_timestamp
值必须大于或等于时间戳值,否则 Span
将被视为无效而丢弃。{
"start_timestamp": "2011-05-02T17:41:36.242Z"
}
或者:
{
"start_timestamp": 1304358096.242
}
timestamp
{
"timestamp": "2011-05-02T17:41:36.955Z"
}
或者:
{
"timestamp": 1304358096.955
}
status
Span/Transaction
的状态
。State | Description | HTTP status code equivalent |
---|---|---|
ok | 不是 error,成功返回 | 200 and 2XX HTTP statuses |
cancelled | 操作被取消,通常是由调用方取消的 | 499 |
unknown or unknown_error | 由未返回足够错误信息的 API 引发的未知错误 | 500 |
invalid_argument | 客户端指定了无效的参数 | 400 |
deadline_exceeded | 在操作成功之前,截止日期已过 | 504 |
not_found | 未找到内容或请求被拒绝的整个类别的用户 | 404 |
already_exists | 尝试创建的实体已经存在 | 409 |
permission_denied | 调用者无权执行指定的操作 | 403 |
resource_exhausted | 资源已耗尽,例如 每个用户的配额已用完,文件系统空间不足 | 429 |
failed_precondition | 客户端不应该重试直到系统状态被显式处理 | 400 |
aborted | 操作被中止 | 409 |
out_of_range | 尝试操作超过有效范围,例如 越过文件末尾查找 | 400 |
unimplemented | 此操作未实施或不支持/启用此操作 | 501 |
internal_error | 底层系统预期的一些不变量已被破坏。此代码保留用于严重错误 | 500 |
unavailable | 该服务当前可用,例如,作为过渡条件 | 503 |
data_loss | 不可恢复的数据丢失或损坏 | 500 |
unauthenticated | 请求者没有操作的有效身份验证凭据 | 401 |
{
"status": "ok"
}
tags
tags
的 map
或 list
,每个 tag
必须少于 200
个字符。{
"tags": {
"ios_version": "4.0",
"context": "production"
}
}
data
{
"data": {
"url": "http://localhost:8080/sockjs-node/info?t=1588601703755",
"status_code": 200,
"type": "xhr",
"method": "GET"
}
}
以下示例将 Span
作为 Transaction
的一部分进行说明,并为简单起见省略了其他属性。
{
"spans": [
{
"trace_id": "1e57b752bc6e4544bbaa246cd1d05dee",
"span_id": "b01b9f6349558cd1",
"parent_span_id": "b0e6f15b45c36b12",
"op": "http",
"description": "GET /sockjs-node/info",
"status": "ok",
"start_timestamp": 1588601261.481961,
"timestamp": 1588601261.488901,
"tags": {
"http.status_code": "200"
},
"data": {
"url": "http://localhost:8080/sockjs-node/info?t=1588601703755",
"status_code": 200,
"type": "xhr",
"method": "GET"
}
},
{
"trace_id": "1e57b752bc6e4544bbaa246cd1d05dee",
"span_id": "b980d4dec78d7344",
"parent_span_id": "9312d0d18bf51736",
"op": "update",
"description": "Vue <App>",
"start_timestamp": 1588601261.535386,
"timestamp": 1588601261.544196
}
]
}
事务
用于向 Sentry
发送跟踪事件。
事务必须包装在 Envelope
中,因此也必须发送到 Envelope
端点。
Transaction
基本上是与 Event
相结合的 Span
。在我们的 SDK
中使用跟踪时,您通常会创建一个 Span tree
,根节点以及整个树都被视为 Transaction
。所以从技术上讲,Transaction
只是一个 Span
。 Transaction
还必须有一个 contexts.trace
(其中包含 Span
的一些数据)和一些其他属性,这些属性将在下一节中介绍。
Transaction
是用 Span
数据丰富的 Events
。我们只会在这里列出对 Transaction
来说重要的东西。
type
transaction
。{
"type": "transaction"
}
start_timestamp
start_timestamp
值必须大于或等于时间戳值,否则 Span
将被视为无效而丢弃。{
"start_timestamp": "2011-05-02T17:41:36.242Z"
}
或者:
{
"start_timestamp": 1304358096.242
}
timestamp
{
"timestamp": "2011-05-02T17:41:36.955Z"
}
或者:
{
"timestamp": 1304358096.955
}
Transaction
必须有一个特定的 contexts.trace
条目,其中包含来自 Span
的数据。
span_id
:
{
"span_id": "99659d76b7cdae94"
}
parent_span_id
:
{
"parent_span_id": "b0e6f15b45c36b12"
}
trace_id
:
Span
属于哪个 trace
。该值应该是编码为十六进制字符串(32
个字符长)的 16
个随机字节。{
"trace_id": "1e57b752bc6e4544bbaa246cd1d05dee"
}
op
{
"op": "db.query"
}
description
span
操作的更长描述,它唯一地标识 span
但跨 span
实例是一致的。{
"description": "SELECT * FROM users WHERE last_active < DATE_SUB(CURRENT_DATE, INTERVAL 1 YEAR)`"
}
status
Span/Transaction
的状态
。State | Description | HTTP status code equivalent |
---|---|---|
ok | 不是 error,成功返回 | 200 and 2XX HTTP statuses |
cancelled | 操作被取消,通常是由调用方取消的 | 499 |
unknown or unknown_error | 由未返回足够错误信息的 API 引发的未知错误 | 500 |
invalid_argument | 客户端指定了无效的参数 | 400 |
deadline_exceeded | 在操作成功之前,截止日期已过 | 504 |
not_found | 未找到内容或请求被拒绝的整个类别的用户 | 404 |
already_exists | 尝试创建的实体已经存在 | 409 |
permission_denied | 调用者无权执行指定的操作 | 403 |
resource_exhausted | 资源已耗尽,例如 每个用户的配额已用完,文件系统空间不足 | 429 |
failed_precondition | 客户端不应该重试直到系统状态被显式处理 | 400 |
aborted | 操作被中止 | 409 |
out_of_range | 尝试操作超过有效范围,例如 越过文件末尾查找 | 400 |
unimplemented | 此操作未实施或不支持/启用此操作 | 501 |
internal_error | 底层系统预期的一些不变量已被破坏。此代码保留用于严重错误 | 500 |
unavailable | 该服务当前可用,例如,作为过渡条件 | 503 |
data_loss | 不可恢复的数据丢失或损坏 | 500 |
unauthenticated | 请求者没有操作的有效身份验证凭据 | 401 |
{
"status": "ok"
}
{
"contexts": {
"trace": {
"op": "navigation",
"description": "User clicked on <Link />",
"trace_id": "743ad8bbfdd84e99bc38b4729e2864de",
"span_id": "a0cfbde2bdff3adc",
"status": "ok",
"parent_span_id": "99659d76b7cdae94"
}
}
}
spans
Span
列表。{
"spans": [
{
"start_timestamp": 1588601261.481961,
"description": "GET /sockjs-node/info",
"tags": {
"http.status_code": "200"
},
"timestamp": 1588601261.488901,
"parent_span_id": "b0e6f15b45c36b12",
"trace_id": "1e57b752bc6e4544bbaa246cd1d05dee",
"op": "http",
"data": {
"url": "http://localhost:8080/sockjs-node/info?t=1588601703755",
"status_code": 200,
"type": "xhr",
"method": "GET"
},
"span_id": "b01b9f6349558cd1"
},
{
"start_timestamp": 1588601261.535386,
"description": "Vue <App>",
"timestamp": 1588601261.544196,
"parent_span_id": "9312d0d18bf51736",
"trace_id": "1e57b752bc6e4544bbaa246cd1d05dee",
"op": "update",
"span_id": "b980d4dec78d7344"
}
]
}
Sentry
使用 面包屑 来创建问题之前发生的事件的跟踪。这些事件与传统日志非常相似,但可以记录更丰富的结构化数据。
此页面提供有关面包屑结构的技术信息。您可以在我们的 Breadcrumbs Sentry 文档页面上阅读手动面包屑记录
和自定义
的概述。
一个事件可能包含一个带有一个条目 values
的 breadcrumbs
属性,它是一个面包屑对象数组。条目按从最旧到最新的顺序排列。因此,列表中的最后一个条目应该是事件发生之前的最近一个条目。
以下示例说明了 event payload
的面包屑部分,并为简单起见省略了其他属性。
{
"breadcrumbs": {
"values": [
{
"timestamp": "2016-04-20T20:55:53.845Z",
"message": "Something happened",
"category": "log",
"data": {
"foo": "bar",
"blub": "blah"
}
},
{
"timestamp": "2016-04-20T20:55:53.847Z",
"type": "navigation",
"data": {
"from": "/login",
"to": "/dashboard"
}
}
]
}
}
面包屑对象包含属性 values
,这是一个具有以下属性的对象数组:
type
(optional)
default
,这使得它们显示为 Debug
条目,但 Sentry
提供了影响面包屑呈现方式的其他类型。category
(optional)
ui.click
可用于指示在 UI
中发生了单击,或 flask
可用于指示事件源自 Flask
框架。message
(optional)
如果提供了 message
,则将其呈现为保留所有空格的文本。
data
(optional)
包含一个字典,其内容取决于 breadcrumb type
。类型不支持的其他参数呈现为 key/value
表。
level
(optional)
fatal
、error
、warning
、info
和 debug
。在 UI
中使用级别
来强调和淡化面包屑。默认值为 info
。timestamp
(recommended)
面包屑在包含时间戳时最有用,因为它创建了一个导致事件 expection/error
的时间线。
面包屑不会按时间戳排序,它们会按照添加的方式保持顺序。
下面是对各个面包屑类型
的描述,以及它们的 data
属性是什么样的。
default
data
部分完全未定义,因此完全呈现为 key/value
表。{
"type": "default",
"category": "started",
"data": undefined,
"level": "info",
"message": "this is a message",
"timestamp": 1596814007.035
}
debug
data
部分完全未定义,因此完全呈现为 key/value
表。在内部,我们显示 default
类型的面包屑,其中包含类别 console
作为 debug
类型的面包屑。
{
"type": "debug",
"category": "started",
"data": null,
"level": "info",
"message": "this is a message",
"timestamp": 1596814007.035
}
error
{
"type": "error",
"category": "error",
"level": "error",
"message": "this is a message",
"timestamp": 1596814007.035
}
navigation
Web
应用程序中的 URL
更改,或者 mobile
或 desktop
应用程序中的 UI
转换等。在内部,我们显示 default
类型的面包屑,其中包含类别 navigation
作为 navigation
类型的面包屑。
它的 data
属性具有以下子属性:
from
(Required)
表示原始
应用程序 state / location
的字符串。
to
(Required)
表示新
应用程序 state / location
的字符串。
{
"type": "navigation",
"category": "navigation",
"timestamp": "2016-04-20T20:55:53.845Z",
"data": {
"from": "/login",
"to": "/dashboard"
}
}
http
HTTP
请求。这可能是来自 Web
应用程序的 AJAX
请求,或者是对 API service provider
的 server-to-server
的 HTTP
请求等。它的 data
属性具有以下子属性:
url
(optional)
请求的 URL。
method
(optional)
HTTP 请求方法。
status_code
(optional)
响应的 HTTP 状态代码。
reason
(optional)
描述状态代码的文本。
{
"type": "http",
"category": "xhr",
"data": {
"url": "http://example.com/api/1.0/users",
"method": "GET",
"status_code": 200,
"reason": "OK"
},
"timestamp": "2016-04-20T20:55:53.845Z"
}
info
{
"type": "info",
"category": "started",
"level": "info",
"message": "this is a message",
"timestamp": 1596813998.386
}
query
{
"type": "query",
"category": "started",
"level": "info",
"message": "this is a message",
"timestamp": 1596813998.386
}
transaction
在内部,我们显示类型为 default
的面包屑,其中包含类别 sentry.transaction
和 sentry.event
作为 transaction
类型的面包屑。
{
"type": "default",
"category": "sentry.transaction",
"level": "info",
"message": "this is a message",
"timestamp": 1596813997.646
}
ui
在内部,我们将包含类别 ui.*
的 default
类型的面包屑显示为 ui
类型的面包屑。
{
"type": "default",
"category": "ui.click",
"message": "div.css-bsbdc4-TextOverflow.e1kpcezi0",
"level": "info",
"timestamp": 1598613151.875368
}
user
{
"type": "user",
"category": "click",
"message": "div.css-bsbdc4-TextOverflow.e1kpcezi0",
"level": "info",
"timestamp": 1598613151.875368
}
上下文接口
提供额外的上下文数据
。通常,这是与当前 user
和 environment
相关的数据。例如,device
或 application version
。它的规范名称是 contexts
。
contexts
类型可用于定义事件的任意上下文数据。它接受 key/value
对的对象。key
是上下文的“别名”
,可以自由选择。但是,根据策略,它应该匹配上下文的类型,除非一个类型有两个值。如果 key
名是类型,您可以省略 type
。
将附加数据添加到事件数据模型(event data model)
时, 如果您在单个时间点拥有所有可用数据,则上下文非常适合。上下文不太适合随时间收集的数据,因为上下文的 SDK
接口无法合并数据。
上下文的 Unknown
数据呈现为 key/value
列表。
设备上下文
描述引起事件的设备。这最适合移动应用程序。
type
和默认 key
是 "device"
。
name
family
iPhone
将是一个合理的系列,Samsung Galaxy
也将是一个合理的系列。model
Samsung Galaxy S3
。model_id
arch
battery_level
orientation
portrait(纵向)
或 landscape(横向)
。manufacturer
brand
screen_resolution
screen_height_pixels
screen_width_pixels
screen_density
screen_dpi
DPI
(每英寸点数)密度的十进制值。online
charging
low_memory
simulator
flag
。memory_size
free_memory
usable_memory
storage_size
free_storage
external_storage_size
android SDK card
)。external_free_storage
android SDK card
)。boot_time
UTC
时间戳。例如,"2018-02-08T12:52:12Z"
。timezone
Europe/Vienna
。language
en-US
。processor_count
“逻辑处理器”
的数量。例如,8
。cpu_description
Intel(R) Core(TM)2 Quad CPU Q6600 @ 2.40GHz
。processor_frequency
MHz
为单位的处理器频率。请注意,实际 CPU 频率可能会因当前负载和电源条件而异,尤其是在手机和笔记本电脑等低功耗设备上。device_type
Unknown, Handheld, Console, Desktop
。battery_status
Unknown, Charging, Discharging, NotCharging, Full
。device_unique_identifier
sendDefaultPii
时才可以使用此值。supports_vibration
supports_accelerometer
supports_gyroscope
supports_audio
supports_location_service
OS context
描述了在其上创建事件的操作系统。在 Web
上下文中,这是浏览器的操作系统(通常从 User-Agent
字符串中提取)。
type
和默认 key
是 "os"
。
name
raw_description
。如果未提供 raw_description
,则 required。version
build
kernel_version
uname
系统调用的整个输出。rooted
rooted
的标志。theme
light
或 dark
。描述操作系统是否在黑暗模式下运行。raw_description
Sentry
将尝试从这个字符串解析 name
和 version
。3
个主要操作系统的 OS context
应如下所示:
{
"windows": {
"type": "os",
"name": "Windows",
"version": "10.0.19041",
"build": "662",
},
"mac": {
"type": "os",
"name": "macOS",
"version": "11.1.0",
"build": "20C69",
"kernel_version": "20.2.0"
},
"linux": {
"type": "os",
"name": "Linux",
"version": "5.10.6",
"build": "arch1-1"
}
}
Runtime context
更详细地描述了运行时。通常,如果涉及多个运行时(例如,如果您有一个 JavaScript
应用程序运行在 JVM
之上),则此上下文会被多次使用。
type
和默认 key
是 "runtime"
。
name
raw_description
。如果未提供 raw_description
,则required。version
raw_description
Sentry
将尝试从这个字符串解析 name
和 version
。App context
描述了应用程序。与运行时相反,这是正在运行并携带有关当前 session
的 metadata
的实际应用程序。
type
和默认 key
是 "app"
。
app_start_time
device_app_hash
build_type
testflight
。app_identifier
bundle ID
。app_name
platform
上。app_version
platform
上。app_build
platform
上的内部构建标识符。Browser context
携带有关 browser
或 user agent
的 Web
相关错误信息。这可以是发生此事件的浏览器,也可以是触发该事件的 Web
请求的 user agent
。
type
和默认 key
是 "browser"
。
name
version
GPU context
描述了设备的 GPU
。
name
version
id
vendor_id
vendor_name
memory_size
api_type
"Apple Metal"
或 "Direct3D11"
multi_threaded_rendering
GPU
是否具有多线程渲染。npot_support
max_texture_size
16384
。graphics_shader_level
着色器能力(shader capability)
级别。例如,Shader Model 2.0, OpenGL ES 3.0, Metal / OpenGL ES 3.1, 27 (unknown)
。supports_draw_call_instancing
supports_ray_tracing
supports_compute_shaders
supports_geometry_shaders
例子:
"gpu": {
"name": "AMD Radeon Pro 560",
"vendor_name": "Apple",
"memory_size": 4096,
"api_type": "Metal",
"multi_threaded_rendering": true,
"version": "Metal",
"npot_support": "Full"
}
State context
描述了应用程序的状态(例如:Redux store
对象)。
type
和默认 key
是 "state"
。
state
key
的对象:用于命名状态库(例如:Redux、MobX、Vuex)的 可选 type
和保存 state
对象的 必需 value
。示例:
"state": {
"state": {
"type": "MobX",
"value": {
"flights": [],
"airports": [],
"showModal": false
}
},
}
Culture Context
描述了使用软件的文化的某些属性。
type
和默认 key
是 "culture"
。
calendar
GregorianCalendar
。自由形式的字符串。display_name
English (United States)
locale
RFC 4646
。例如 en-US
或 pt-BR
。is_24_hour_format
true
或 false
。timezone
Europe/Vienna
。以下示例说明了 event payload
的上下文部分,并为简单起见省略了其他属性。
{
"contexts": {
"os": {
"name": "Windows"
},
"electron": {
"type": "runtime",
"name": "Electron",
"version": "4.0"
}
}
}
调试元接口
携带用于处理错误
和崩溃报告
的调试信息。Sentry
修改此接口中的信息。
sdk_info
sdk_name
、version_major
、version_minor
和 version_patchlevel
。这有助于 Sentry
定位 iOS
系统 symbols
,其他 SDK
不需要。{
"sdk_name": "iOS",
"version_major": 10,
"version_minor": 3,
"version_patchlevel": 0
}
images
调试镜像
列表包含加载到进程中的所有动态库及其内存地址。 Stack Trace
中的指令地址被映射到调试镜像
列表中,以便检索调试文件进行符号化(symbolication)
。
有两种调试镜像:
macho
、elf
和 pe
类型的原生调试镜像proguard
的 Android
调试镜像MachO
镜像用于 Apple
平台。它们的结构与其他原生镜像相同。
属性:
type
"macho"
。image_addr
"0x"
为前缀的十六进制表示形式的字符串。image_size
Sentry
将假定镜像跨越到下一个镜像,这可能会导致无效的堆栈跟踪。debug_id
Mach
头中 LC_UUID
加载命令的值,格式为 UUID
。debug_file
dSYM
文件的可选名称或绝对路径。从某些 symbol
服务器检索调试文件可能需要此值。code_id
Mach
头中 LC_UUID
加载命令的值,格式为 UUID
。 Mach
镜像可以为空,因为它相当于调试标识符。code_file
Sentry
上丢失,这有助于定位文件。image_vmaddr
如果此值非零,则原生镜像中声明的所有 symbols
和 addresses
都从此地址开始,而不是 0
。相比之下,Sentry
处理相对于镜像开始的地址。例如,对于 image_vmaddr: 0x40000
,位于 0x401000
的 symbol
的相对地址为 0x1000
。
Apple Crash Reports
和 addr2line
中使用的相对地址通常位于首选地址空间中,而不是相对地址空间。
arch
示例:
{
"type": "macho",
"debug_id": "84a04d24-0e60-3810-a8c0-90a65e2df61a",
"debug_file": "libDiagnosticMessagesClient.dylib",
"code_file": "/usr/lib/libDiagnosticMessagesClient.dylib",
"image_addr": "0x7fffe668e000",
"image_size": 8192,
"image_vmaddr": "0x40000",
"arch": "x86_64"
}
ELF
镜像用于 Linux
平台。它们的结构与其他原生镜像相同。
属性:
type
"elf"
。image_addr
"0x"
为前缀的十六进制表示形式的字符串。image_size
Sentry
将假定镜像跨越到下一个镜像,这可能会导致无效的堆栈跟踪。debug_id
16
字节的 little-endian(小端) UUID 表示。插入空格以提高可读性,请注意第一个字段的字节顺序:code id: f1c3bcc0 2798 65fe 3058 404b2831d9e6 4135386c
debug id: c0bcc3f1-9827-fe65-3058-404b2831d9e6
如果没有可用的 code id
,debug id
应该通过对 16 字节块中的 .text
部分的前 4096
个字节进行异或(XORing)
来计算,并将其表示为 little-endian UUID
(再次交换字节顺序)。
debug_file
名称
或绝对路径
。从某些 symbol
服务器检索调试文件可能需要此值。code_id
这应该是 NT_GNU_BUILD_ID
程序头的十六进制表示(类型 PT_NOTE
), 或 .note.gnu.build-id
注释部分的值(类型 SHT_NOTE
)。否则,将此值留空。
某些 symbol
服务器使用代码标识符来定位 ELF
镜像的调试信息,在这种情况下,如果可能,应包含此字段。
code_file
Sentry
上丢失,这有助于定位文件。image_vmaddr
如果此值非零,则原生镜像
中声明的所有符号和地址都从此地址开始,而不是 0
。相比之下,Sentry
处理相对于镜像开始的地址。例如,对于 image_vmaddr: 0x40000
,位于 0x401000
的符号的相对地址为 0x1000
。
addr2line
中使用的相对地址通常在首选地址空间中,而不是相对地址空间。
arch
示例:
{
"type": "elf",
"code_id": "68220ae2c65d65c1b6aaa12fa6765a6ec2f5f434",
"code_file": "/lib/x86_64-linux-gnu/libgcc_s.so.1",
"debug_id": "e20a2268-5dc6-c165-b6aa-a12fa6765a6e",
"image_addr": "0x7f5140527000",
"image_size": 90112,
"image_vmaddr": "0x40000",
"arch": "x86_64"
}
PE
镜像用于 Windows
平台,并附有 PDB
文件用于调试。它们的结构与其他原生镜像相同。
type
"pe"
。image_addr
"0x"
为前缀的十六进制表示形式的字符串。image_size
Sentry
将假定镜像跨越到下一个镜像,这可能会导致无效的堆栈跟踪。debug_id
PDB
文件的 signature
和 age
。这两个值都可以从 PE
中的 CodeView PDB70
调试信息头中读取。该值应表示为 little-endian UUID,并在末尾附加 age
。请注意,必须交换 UUID
字段的字节顺序(插入空格以提高可读性):
signature: f1c3bcc0 2798 65fe 3058 404b2831d9e6
age: 1
debug_id: c0bcc3f1-9827-fe65-3058-404b2831d9e6-1
debug_file
PDB
文件的名称。从特定 symbol
服务器检索调试文件通常需要此值。code_id
DLL
的标识符。它包含来自 COFF
头的 time_date_stamp
和来自可选头的 size_of_image
的值,这些值使用 %08x%X
一起格式化为十六进制字符串(注意第二个值没有被填充):time_date_stamp: 0x5ab38077
size_of_image: 0x9000
code_id: 5ab380779000
应提供代码标识符以允许二进制崩溃报告
的服务器端堆栈遍历,例如 Minidumps
。
code_file
DLL
或可执行文件的绝对路径。如果文件在 Sentry
上丢失,这有助于定位文件。应提供代码文件以允许二进制崩溃报告的服务器端堆栈遍历,例如 Minidumps
。image_vmaddr
原生镜像中的符号和地址始终相对于镜像的开头,不考虑首选加载地址。这只是对加载程序的一个提示。
arch
示例:
{
"type": "pe",
"code_id": "57898e12145000",
"code_file": "C:\\Windows\\System32\\dbghelp.dll",
"debug_id": "9c2a902b-6fdf-40ad-8308-588a41d572a0-1",
"debug_file": "dbghelp.pdb",
"image_addr": "0x70850000",
"image_size": "1331200",
"image_vmaddr": "0x40000",
"arch": "x86"
}
WASM
镜像用于 WebAssembly
。它们的结构与其他原生镜像相同。
属性:
type
"wasm"
。debug_id
build_id
自定义部分的值,必须格式化为截断到前导 16
个字节的 UUID
。debug_file
WASM
文件的名称
或绝对 URL
。从某些 symbol
服务器检索调试文件可能需要此值。这应该对应于从 external_debug_info
自定义部分提取的外部化 URL
。
code_id
WASM
文件的标识符。它是格式为 HEX
字符串的 build_id
自定义部分的值。如果该部分包含 UUID
(16
字节),则可以省略它。code_file
wasm
文件的绝对 URL
。如果文件在 Sentry
上丢失,这有助于定位文件。示例:
{
"type": "wasm",
"debug_id": "84a04d24-0e60-3810-a8c0-90a65e2df61a",
"debug_file": "sample.wasm"
}
Proguard
镜像是指 Proguard
混淆函数名时生成的 mapping.txt
文件。 Java SDK
集成为此文件分配了一个唯一标识符,该标识符必须包含在镜像列表中。
uuid
示例:
{
"uuid": "395835f4-03e0-4436-80d3-136f0749a893"
}
请参阅上述调试镜像类型的示例。
{
"debug_meta": {
"images": [],
"sdk_info": {
"sdk_name": "iOS",
"version_major": 10,
"version_minor": 3,
"version_patchlevel": 0
}
}
}
异常接口指定程序中发生的异常或错误。
一个 event
可能在名为 exception
的属性中包含一个或多个异常。
exception
属性应该是一个对象,其属性 values
包含一个或多个值的 list
,这些值是以下描述格式的对象。
多个值代表链式异常,应该从最旧到最新排序。例如,考虑这个 Python
代码片段:
try:
raise Exception
except Exception as e:
raise ValueError from e
Exception
将首先在 values
list 中描述,然后是 ValueError
的描述。
type
ValueError
。value
module
thread_id
mechanism
stacktrace
异常机制
是驻留在 异常接口 中的可选字段。它携带有关在目标系统上创建异常的方式的附加信息。这包括从操作系统或运行时 API
获得的一般异常值,以及特定于机制的值。
type
mechanism
的唯一标识符决定了 mechanism
数据的呈现和处理。description
错误机制(error mechanism)
的人类可读描述以及有关如何解决此错误的可能提示。help_link
URL
,可能插入 error
参数。handled
try ... catch
)。synthetic
error
是合成错误的标志。合成错误是本身没有什么意义的错误。这可能是因为它们是在中心位置创建的(如crash handler
),并且都被称为相同的:Error
、Segfault
等。当设置 flag
时,Sentry
将尝试使用其他信息(top in-app frame function)而不是主事件显示的 UI
中的异常类型和值。例如,应该为所有 "segfaults"
设置此标志,否则每个 error group
看起来都非常相似。
meta
exception mechanism
的信息。data
发送任何异常机制属性都需要
type
属性,即使 SDK 无法确定具体机制。
在这种情况下,将 type
设置为 generic
。请参阅下面的示例。
机制元数据(mechanism metadata)
通常携带由运行时或操作系统报告的错误代码,以及这些代码的平台相关解释。 SDK
可以安全地省略众所周知的 error code
的代码名称和描述,因为它们将由 Sentry
填写。对于专有或供应商特定的 error code
,添加这些值将为用户提供附加信息。
meta
key 可能包含以下一个或多个属性:
signal
有关 POSIX signal
的信息。在 Apple
系统上,信号除了更详细地描述 signal
的 signal number
外,还带有代码。在 Linux
上,此代码不存在。
number
code
name
signal
编号的 signal
名称。code_name
signal code
的名称。mach_exception
Apple
系统上的 Mach Exception
,包括code triple(代码三元组)
和可选描述。
exception
code
subcode
name
iOS / macOS
中异常常量的名称。ns_error
Apple 系统上的 NSError
,由 domain
和 code
组成。
code
domain
NSError
的 domain
作为字符串。errno
由 Linux
系统调用设置的错误代码和 ISO C99
、POSIX.1-2001
和 POSIX.1-2008
中指定的一些库函数。有关更多信息,请参阅 errno(3) 。
number
name
以下示例说明了发送异常的多种方式。每个示例都包含 event payload
的异常部分, 并为简单起见省略了其他属性。
单个异常:
{
"exception": {
"values": [
{
"type": "ValueError",
"value": "my exception value",
"module": "__builtins__",
"stacktrace": {}
}
]
}
}
链式异常:
{
"exception": {
"values": [
{
"type": "Exception",
"value": "initial exception",
"module": "__builtins__"
},
{
"type": "ValueError",
"value": "chained exception",
"module": "__builtins__"
}
]
}
}
iOS 原生 mach 异常与机制:
{
"exception": {
"values": [
{
"type": "EXC_BAD_ACCESS",
"value": "Attempted to dereference a null pointer",
"mechanism": {
"type": "mach",
"handled": false,
"data": {
"relevant_address": "0x1"
},
"meta": {
"signal": {
"number": 10,
"code": 0,
"name": "SIGBUS",
"code_name": "BUS_NOOP"
},
"mach_exception": {
"code": 0,
"subcode": 8,
"exception": 1,
"name": "EXC_BAD_ACCESS"
}
}
}
}
]
}
}
JavaScript
未处理的 promise rejection
:
{
"exception": {
"values": [
{
"type": "TypeError",
"value": "Object [object Object] has no method 'foo'",
"mechanism": {
"type": "promise",
"description": "This error originated either by throwing inside of an ...",
"handled": false,
"data": {
"polyfill": "bluebird"
}
}
}
]
}
}
一般未处理的崩溃:
{
"exception": {
"values": [
{
"type": "Error",
"value": "An error occurred",
"mechanism": {
"type": "generic",
"handled": false
}
}
]
}
}
消息接口
携带描述 event
或 error
的日志消息。可选地,它可以携带格式字符串和结构化参数。这有助于将类似的消息归为同一问题。
formatted
Sentry
将尝试插入消息。
它不得超过 8192
个字符。较长的消息将被截断。Sentry
还接受未设置为支持旧版 SDK
的消息。message
params
{
"message": {
"message": "My raw message with interpreted strings like %s",
"params": ["this"]
}
}
请求接口
包含有关与事件相关的 HTTP
请求的信息。在客户端 SDK
中,这可以是传出请求,也可以是渲染当前网页的请求。在 server SDK
上,这可能是正在处理的传入 Web
请求。
数据变量应该只包含请求 body
(而不是 query string
)。它可以是字典(用于标准 HTTP
请求)或原始请求 body
。
在请求接口
中,几个属性可以声明为字符串(string)
、对象(object)
或元组列表(list of tuples)
。在这种情况下,Sentry
尝试从字符串表示中解析结构化信息。
有时,key
可以被多次声明,或者元素的顺序很重要。在这种情况下,请在普通对象上使用元组(tuple)
表示。
请求头作为对象的示例:
{
"content-type": "application/json",
"accept": "application/json, application/xml"
}
与元组列表相同的 header
示例:
[
["content-type", "application/json"],
["accept", "application/json"],
["accept", "application/xml"]
]
method
url
URL
(如果可用)。查询字符串可以作为 url
的一部分声明,也可以在 query_string
中单独声明。query_string
URL
的查询字符串组件。可以作为未解析的字符串、字典或元组列表给出。
如果查询字符串未声明并且是 url
参数的一部分,Sentry
会将其移动到查询字符串中。data
SDK
应丢弃大型 body
。可以作为任何格式的字符串或结构数据给出。
在将请求数据附加到事件之前,始终修剪和截断请求数据。如果这不可能,请在 API
文档中添加用户应截断请求数据的说明。虽然 Sentry
会在摄取时尝试修剪此字段,但大型 body
可能会导致整个事件有效负载超过其最大大小限制, 在这种情况下,事件将被丢弃。cookies
headers
header
的字典。如果一个 header
多次出现,则需要按照 HTTP header
合并标准进行合并。 Sentry
不区分大小写地处理 Header
名称。env
environment
信息的字典。这是 CGI/WSGI/Rack
key 等非 HTTP header
的信息所在的位置。
Sentry
将明确查找 REMOTE_ADDR
以提取 IP
地址。一个完全填充的请求接口:
{
"request": {
"method": "POST",
"url": "http://absolute.uri/foo",
"query_string": "query=foobar&page=2",
"data": {
"foo": "bar"
},
"cookies": "PHPSESSID=298zf09hf012fh2; csrftoken=u32t4o3tb3gg43; _gat=1;",
"headers": {
"content-type": "text/html"
},
"env": {
"REMOTE_ADDR": "192.168.0.1"
}
}
}
SDK 接口
描述了 Sentry SDK
及其用于捕获
和传输
事件的配置。
name
entity.ecosystem[.flavor]
其中 entity 标识了 SDK
的开发者, ecosystem 是指使用 SDK
的编程语言或平台,可选的 flavor 用于标识属于主要生态系统的独立 SDK
。
官方 Sentry SDK
使用 entity(实体) sentry
。示例:sentry.python
sentry.javascript.react-native
version
MAJOR.MINOR.PATCH
, 没有任何前缀(在主要版本号之前没有 v
或任何其他内容)。示例:0.1.0
1.0.0
4.3.12
integrations
包含默认集成是因为不同的 SDK 版本
可能包含不同的默认集成
。
packages
source:identifier
和 version
的 name
。如果源是 Git
存储库,则源应该是 git
,identifier
应该是 checkout
链接,version
应该是 Git reference
(branch
、tag
或 SHA
)。以下示例说明了 event payload 的 SDK
部分,并为简单起见省略了其他属性。
{
"sdk": {
"name": "sentry.javascript.react-native",
"version": "1.0.0",
"integrations": [
"redux"
],
"packages": [
{
"name": "npm:@sentry/react-native",
"version": "0.39.0"
},
{
"name": "git:https://github.com/getsentry/sentry-cocoa.git",
"version": "4.1.0"
}
]
}
}
堆栈跟踪
包含一个帧列表
,每个帧
都有描述该帧
上下文的各种位(大多数可选)。帧
应该从最旧到最新排序。
堆栈跟踪始终是异常或线程的一部分。它们不能被声明为顶级事件属性。向事件添加堆栈跟踪时,请遵循以下经验法则:
错误(error)
、异常(exception)
或崩溃(crash)
的一部分,请将其添加到异常接口。frames
: Required. 堆栈帧的非空列表(见下文)。该列表是从调用者(caller)
到被调用者(callee)
,或从最老到最年轻的。最后一帧是创建异常的帧。
registers
: Optional. 寄存器名称及其值的映射。这些值应包含线程的实际寄存器值,从而映射到列表中的最后一帧。
每个对象都应该至少一个 filename
、function
或 instruction_addr
属性。所有值都是可选的,但建议使用。
filename
: 源文件相对于项目根目录的路径。
该值不应使文件名无法区分,并且应仅在实际重命名的文件的版本之间更改。
在某些 SDK
中,这被实现为相对于与语言/平台
相关的某个入口点的路径。例如,在 Python
中,filename
与 PYTHONPATH
或 site-packages
相关。
function
: 被调用函数的名称。
此函数名称可能会被缩短或取消。如果没有,Sentry
将对其进行分解和缩短。原始函数名称将存储在 raw_function
中。
raw_function
: 原始函数名,如果函数名被缩短或被破坏。单击 UI
中缩短的函数时,Sentry
会显示原始函数。
module
: 特定于平台的模块路径(例如 sentry.interfaces.Stacktrace
)。
lineno
: 调用的行号,从 1 开始
colno
: 调用的列号,从 1 开始。
abs_path
: 源文件的绝对路径。
context_line
: lineno
文件名中的源代码。
pre_context
: context_line
之前的源代码行列表(按顺序)— 通常是 [lineno - 5:lineno]
。
post_context
: context_line
之后的源代码行列表(按顺序)——通常是 [lineno + 1:lineno + 5]
。
in_app
: 指示此帧是否与此堆栈跟踪中相关代码的执行相关。例如,此帧或许为你 app
提供动力的框架的 web server
并不相关。但是,一旦您开始处理代码,对框架库的调用可能是相关的。
stack_start
: 将此帧标记为链式堆栈跟踪的底部。来自异步代码的堆栈跟踪由几个子跟踪组成,这些子跟踪链接在一起成为一个大列表。此标志指示链式堆栈跟踪的根函数。根据运行时和线程,这可以是 main
函数或线程 base stub
。该字段只应在 true
时指定。
vars
: 此帧内可用的变量映射(通常是上下文本地变量)。
以下属性主要用于基于 C 的语言:
instruction_addr
: 用于符号化的可选指令地址。这应该是一个带有 0x
前缀的十六进制数字的字符串。如果设置了此项并且在调试元接口中定义了已知镜像,则可以进行符号化。注意 addr_mode
属性可以控制这个地址的行为。
addr_mode
: 可选择更改寻址模式。默认值与 "abs"
相同,表示绝对引用。这也可以设置为 "rel:DEBUG_ID"
或 "rel:IMAGE_INDEX"
以使地址与 debug id
或 index
引用的对象相关。例如,这对于 WASM
处理是必要的,因为 WASM
不使用统一的地址空间。
symbol_addr
: 指向 symbol
的可选地址。我们使用指令地址进行符号化,但这可用于自动计算指令偏移量。注意 addr_mode
属性可以控制这个地址的行为。
image_addr
: (可选)要引用的调试镜像的地址。
package
: 包含框架的 "package"
。根据平台的不同,这可能是不同的东西。对于 C#
,它可以是程序集的名称。对于原生代码,可以是动态库的路径等。
platform
: 这可以覆盖单个帧的平台。否则,将假定事件的平台。这可用于多平台堆栈跟踪,例如在 React Native
中。
对于用 Python 编写的给定示例程序:
def foo():
my_var = 'foo'
raise ValueError()
def main():
foo()
以正确的顺序对上述程序进行最小的堆栈跟踪:
{
"frames": [{ "function": "main" }, { "function": "foo" }]
}
顶部帧完全填充了五行源上下文:
{
"frames": [
{
"in_app": true,
"function": "myfunction",
"abs_path": "/real/file/name.py",
"filename": "file/name.py",
"lineno": 3,
"vars": {
"my_var": "'value'"
},
"pre_context": ["def foo():", " my_var = 'foo'"],
"context_line": " raise ValueError()",
"post_context": ["", "def main():"]
}
]
}
具有寄存器值的最小原生堆栈跟踪。请注意,package
事件属性必须是 "native"
才能对这些帧进行符号化。
{
"frames": [
{ "instruction_addr": "0x7fff5bf3456c" },
{ "instruction_addr": "0x7fff5bf346c0" }
],
"registers": {
"rip": "0x00007ff6eef54be2",
"rsp": "0x0000003b710cd9e0"
}
}
当常规堆栈跟踪不包含模板数据时,模板接口对于特定于模板引擎的报告很有用。例如,这在 Django
框架中是必需的,其中模板未集成到 Python
堆栈跟踪中。
渲染的模板。这通常用作堆栈跟踪中的单个帧,并且仅在模板系统不提供适当的堆栈跟踪时才应使用。
属性 filename
、context_line
和 lineno
是必需的。
lineno
abs_path
filename
context_line
pre_context
context_line
之前的源代码行列表(按顺序)— 通常 [lineno - 5:lineno]
。post_context
context_line
之后的源代码行列表(按顺序)— 通常 [lineno + 1:lineno + 5]
。{
"template": {
"abs_path": "/real/file/name.html",
"filename": "file/name.html",
"lineno": 3,
"pre_context": [
"line1",
"line2"
],
"context_line": "line3",
"post_context": [
"line4",
"line5"
],
}
}
线程接口指定在事件发生时正在运行的线程。这些线程还可以包含堆栈跟踪。
一个 event
可能在一个名为 threads
的属性中包含一个或多个线程。
threads
属性应该是一个带有 values
属性的对象包含一个或多个值,这些值是采用下述格式的对象。
根据 Sentry
策略,因 exception
而崩溃的线程不应有堆栈跟踪, 而是应在 exception
上设置 thread_id
属性,Sentry
将连接两者。
id
exception
可以设置 thread_id
属性来交叉引用此线程。crashed
false
。current
false
。name
stacktrace
如果这是一个错误事件,则应在异常接口中声明主要异常的堆栈跟踪。如果有单个异常,Sentry
将自动移动唯一崩溃线程的堆栈跟踪。
以下示例说明了 event payload
的线程部分,并为简单起见省略了其他属性。
{
"threads": {
"values": [
{
"id": "0",
"name": "main",
"crashed": true,
"stacktrace": {}
}
]
}
}
描述请求的经过身份验证的用户的接口。
例如,您应该至少为 Sentry
提供 id
、email
、ip_address
、username
之一,以便能够告诉你有多少用户受到一个问题的影响。发送没有这些属性而只有自定义属性的用户是有效的,但没有那么有用。
id
username
id
更好的标签。email
Sentry
知道电子邮件地址,可以显示诸如 Gravatars
之类的内容并解锁消息传递功能。ip_address
IP
地址。如果用户未经身份验证,Sentry
使用 IP
地址作为用户的唯一标识符。设置为 "{{auto}}"
以让 Sentry
从连接推断 IP
地址。所有其他 key
都存储为 extra
信息,但不会由 Sentry
专门处理。
在客户端平台上运行的 SDK
,例如浏览器和移动应用程序,应该默认设置 ip_address = "{{auto}}"
。相反,服务器端 SDK
应填充请求接口
。 Sentry
使用几种回退来回填 IP
地址:
user.ip_address
。http.env.REMOTE_ADDR
。Sentry
看到的连接 IP
地址,如果使用了 {{auto}}
。{
"user": {
"id": "unique_id",
"username": "my_user",
"email": "foo@example.com",
"ip_address": "127.0.0.1",
"subscription": "basic"
}
}