您的位置:首页 > 其它

Sentry 开发者贡献指南 - SDK 开发(事件负载)

2021-12-28 19:32 211 查看

内容整理自官方开发文档

系列

公众号:黑客下午茶

事件负载(Payload)

事件是客户端通常通过使用

SDK
发送到
Sentry
服务器的基本数据。事件负载(
Event payload
)大小限制为
200kb

接受事件有效负载的

Sentry server
上的
API
端点是
/api/{PROJECT_ID}/store/

必需属性

属性是

Sentry
理解的简单数据,用于提供有关事件的最基本信息。 这些是诸如事件的
unique ID
或事件发生的时间之类的东西。

所有事件都需要以下属性。

event_id

  • Required. 表示
    uuid4
    值的十六进制字符串。长度正好是
    32
    个字符。不允许使用破折号(
    -
    )。必须是小写。
{
"event_id": "fc6d8c0c43fc4630ad850ee518f1b9d0"
}

timestamp

{
"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

  • Optional. 事件
    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 Interface(跨度接口)

Span
接口指定了一系列具有
开始
结束
时间的_
timed(定时)
_应用程序事件。

一个

Transaction
可以在名为
spans
的数组属性中包含零个或多个
Span
list
中的
Span
不必排序,它们将按服务器上的
开始/结束
时间排序。

虽然

Span
属性将在服务器上规范化,但当
Span
至少包含一个
op
description
时,它是最有用的。

属性

span_id
:

  • Required. 长度为 16 个字符的随机十六进制字符串。
{
"span_id": "99659d76b7cdae94"
}

parent_span_id
:

  • Optional. 如果此 Span 应呈现为另一个 Span 的子项,请将此属性设置为父项的 id。
{
"parent_span_id": "b0e6f15b45c36b12"
}

trace_id
:

  • Required. 确定
    Span
    属于哪个
    trace
    。该值应该是编码为十六进制字符串(
    32
    个字符长)的
    16
    个随机字节。
{
"trace_id": "1e57b752bc6e4544bbaa246cd1d05dee"
}

op

  • Recommended. 标识 span 正在测量的操作类型的短代码。
{
"op": "db.query"
}

description

  • Optional. 对
    span
    操作的更长描述,它唯一地标识
    span
    但跨
    span
    实例是一致的。
{
"description": "SELECT * FROM users WHERE last_active < DATE_SUB(CURRENT_DATE, INTERVAL 1 YEAR)`"
}

start_timestamp

  • Required. 表示测量开始时间的时间戳。格式要么是 RFC 3339 中定义的字符串, 要么是表示自 Unix 纪元以来经过的秒数的数字(整数或浮点数)值。
    start_timestamp
    值必须大于或等于时间戳值,否则
    Span
    将被视为无效而丢弃。
{
"start_timestamp": "2011-05-02T17:41:36.242Z"
}

或者:

{
"start_timestamp": 1304358096.242
}

timestamp

  • Required. 表示测量完成时的时间戳。格式要么是 RFC 3339 中定义的字符串, 要么是表示自 Unix 纪元以来经过的秒数的数字(整数或浮点数)值。
{
"timestamp": "2011-05-02T17:41:36.955Z"
}

或者:

{
"timestamp": 1304358096.955
}

status

  • Optional. 描述
    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

  • Optional. 事件
    tags
    map
    list
    ,每个
    tag
    必须少于
    200
    个字符。
{
"tags": {
"ios_version": "4.0",
"context": "production"
}
}

data

  • Optional. 与此 Span 关联的任意数据。
{
"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
}
]
}

Transaction Payloads(事务有效负载)

事务
用于向
Sentry
发送跟踪事件。

事务必须包装在

Envelope
中,因此也必须发送到
Envelope
端点。

剖析

Transaction
基本上是与
Event
相结合的
Span
。 在我们的
SDK
中使用跟踪时,您通常会创建一个
Span tree
,根节点以及整个树都被视为
Transaction
。 所以从技术上讲,
Transaction
只是一个
Span
Transaction
还必须有一个
contexts.trace
(其中包含
Span
的一些数据)和一些其他属性,这些属性将在下一节中介绍。

Transaction
是用
Span
数据丰富的
Events
。 我们只会在这里列出对
Transaction
来说重要的东西。

type

  • Required. 事务必须将此值设置为
    transaction
{
"type": "transaction"
}

start_timestamp

  • Required. 表示测量开始时间的时间戳。格式要么是 RFC 3339 中定义的字符串, 要么是表示自 Unix 纪元以来经过的秒数的数字(整数或浮点数)值。
    start_timestamp
    值必须大于或等于时间戳值,否则
    Span
    将被视为无效而丢弃。
{
"start_timestamp": "2011-05-02T17:41:36.242Z"
}

或者:

{
"start_timestamp": 1304358096.242
}

timestamp

  • Required. 表示测量完成时的时间戳。格式要么是 RFC 3339 中定义的字符串, 要么是表示自 Unix 纪元以来经过的秒数的数字(整数或浮点数)值。
{
"timestamp": "2011-05-02T17:41:36.955Z"
}

或者:

{
"timestamp": 1304358096.955
}

contexts.trace

Transaction
必须有一个特定的
contexts.trace
条目,其中包含来自
Span
的数据。

span_id
:

  • Required. 长度为 16 个字符的随机十六进制字符串。
{
"span_id": "99659d76b7cdae94"
}

parent_span_id
:

  • Optional. 如果此 Span 应呈现为另一个 Span 的子项,请将此属性设置为父项的 id。
{
"parent_span_id": "b0e6f15b45c36b12"
}

trace_id
:

  • Required. 确定
    Span
    属于哪个
    trace
    。该值应该是编码为十六进制字符串(
    32
    个字符长)的
    16
    个随机字节。
{
"trace_id": "1e57b752bc6e4544bbaa246cd1d05dee"
}

op

  • Recommended. 标识 span 正在测量的操作类型的短代码。
{
"op": "db.query"
}

description

  • Optional. 对
    span
    操作的更长描述,它唯一地标识
    span
    但跨
    span
    实例是一致的。
{
"description": "SELECT * FROM users WHERE last_active < DATE_SUB(CURRENT_DATE, INTERVAL 1 YEAR)`"
}

status

  • Optional. 描述
    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

  • Recommended.
    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"
}
]
}

Breadcrumbs Interface(面包屑接口)

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)

  • 表示面包屑出现时间的时间戳。格式要么是 RFC 3339 中定义的字符串,要么是表示自 Unixepoch 以来经过的秒数的数字(整数或浮点数)值。 面包屑在包含时间戳时最有用,因为它创建了一个导致事件
    expection/error
    的时间线。

面包屑不会按时间戳排序,它们会按照添加的方式保持顺序。

Breadcrumb Types(面包屑类型)

下面是对各个

面包屑类型
的描述,以及它们的
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 的交互。

在内部,我们将包含类别

ui.*
default
类型的面包屑显示为
ui
类型的面包屑。

{
"type": "default",
"category": "ui.click",
"message": "div.css-bsbdc4-TextOverflow.e1kpcezi0",
"level": "info",
"timestamp": 1598613151.875368
}

user

  • 用户与应用 UI 的交互。
{
"type": "user",
"category": "click",
"message": "div.css-bsbdc4-TextOverflow.e1kpcezi0",
"level": "info",
"timestamp": 1598613151.875368
}

Contexts Interface(上下文接口)

上下文接口
提供额外的
上下文数据
。 通常,这是与当前
user
environment
相关的数据。 例如,
device
application version
。它的规范名称是
contexts

contexts
类型可用于定义事件的任意上下文数据。 它接受
key/value
对的对象。
key
是上下文的
“别名”
,可以自由选择。 但是,根据策略,它应该匹配上下文的类型,除非一个类型有两个值。 如果
key
名是类型,您可以省略
type

将附加数据添加到

事件数据模型(event data model)
时, 如果您在单个时间点拥有所有可用数据,则上下文非常适合。 上下文不太适合随时间收集的数据,因为上下文的
SDK
接口无法合并数据。

上下文的

Unknown
数据呈现为
key/value
列表。

Device Context(设备上下文)

设备上下文
描述引起事件的设备。这最适合移动应用程序。

type
和默认
key
"device"

name

  • Required. 设备名称。这通常是 hostname。

family

  • Optional. 设备的系列。这通常是跨代型号名称的共同部分。例如,
    iPhone
    将是一个合理的系列,
    Samsung Galaxy
    也将是一个合理的系列。

model

  • Optional. 型号名称。例如,这可以是
    Samsung Galaxy S3

model_id

  • Optional. 用于准确识别设备的内部硬件修订版。

arch

  • Optional. CPU 架构。

battery_level

  • Optional. 如果设备有电池,这可以是定义电池电量的浮点值(在 0-100 范围内)。

orientation

  • Optional. 这可以是用于定义设备方向的字符串
    portrait(纵向)
    landscape(横向)

manufacturer

  • Optional. 设备的制造商。

brand

  • Optional. 设备的品牌。

screen_resolution

  • Optional. 屏幕分辨率(例如:800x600、3040x1444)。

screen_height_pixels

  • Optional. 屏幕的高度。

screen_width_pixels

  • Optional. 屏幕的宽度。

screen_density

  • Optional. 表示屏幕密度的浮点数。

screen_dpi

  • Optional. 反映
    DPI
    (每英寸点数)密度的十进制值。

online

  • Optional. 设备是否在线。

charging

  • Optional. 设备是否正在充电。

low_memory

  • Optional. 设备是否内存不足。

simulator

  • Optional. 指示此设备是模拟器还是实际设备的
    flag

memory_size

  • Optional. 可用的总系统内存(以字节为单位)。

free_memory

  • Optional. 空闲系统内存(以字节为单位)。

usable_memory

  • Optional. 可用于应用程序的内存(以字节为单位)。

storage_size

  • Optional. 设备总存储量(以字节为单位)。

free_storage

  • Optional. 设备空闲存储量(以字节为单位)。

external_storage_size

  • Optional. 附加外部存储的总大小(以字节为单位)(例如,
    android SDK card
    )。

external_free_storage

  • Optional. 附加外部存储的空闲大小(以字节为单位)(例如,
    android SDK card
    )。

boot_time

  • Optional. 系统启动时格式化的
    UTC
    时间戳。例如,
    "2018-02-08T12:52:12Z"

timezone

  • Optional. 设备的时区。例如,
    Europe/Vienna

language

  • Optional. 设备的语言。 例如,
    en-US

processor_count

  • Optional.
    “逻辑处理器”
    的数量。 例如,
    8

cpu_description

  • Optional. CPU 描述。例如,
    Intel(R) Core(TM)2 Quad CPU Q6600 @ 2.40GHz

processor_frequency

  • Optional. 以
    MHz
    为单位的处理器频率。请注意,实际 CPU 频率可能会因当前负载和电源条件而异,尤其是在手机和笔记本电脑等低功耗设备上。

device_type

  • Optional. 运行应用程序的设备类型。例如,
    Unknown, Handheld, Console, Desktop

battery_status

  • Optional. 设备电池的状态。例如,
    Unknown, Charging, Discharging, NotCharging, Full

device_unique_identifier

  • Optional. 唯一的设备标识符。只有在启用
    sendDefaultPii
    时才可以使用此值。

supports_vibration

  • Optional. 设备上是否有振动?

supports_accelerometer

  • Optional. 设备上是否有加速计?

supports_gyroscope

  • Optional. 设备上有陀螺仪吗?

supports_audio

  • Optional. 设备上是否有音频?

supports_location_service

  • Optional. 设备是否能够报告其位置?

OS Context(操作系统上下文)

OS context
描述了在其上创建事件的操作系统。在
Web
上下文中,这是浏览器的操作系统(通常从
User-Agent
字符串中提取)。

type
和默认
key
"os"

name

  • Recommended. 操作系统的名称。它可能源自
    raw_description
    。如果未提供
    raw_description
    ,则 required

version

  • Optional. 操作系统的版本。

build

  • Optional. 操作系统的内部构建版本。

kernel_version

  • Optional. 一个独立的内核版本字符串。这通常是
    uname
    系统调用的整个输出。

rooted

  • Optional. 指示操作系统是否已越狱或
    rooted
    的标志。

theme

  • Optional.
    light
    dark
    。描述操作系统是否在黑暗模式下运行。

raw_description

  • Optional. 操作系统获取的未处理的描述字符串。对于一些众所周知的运行时,如果没有明确给出,
    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(运行时上下文)

Runtime context
更详细地描述了运行时。 通常,如果涉及多个运行时(例如,如果您有一个
JavaScript
应用程序运行在
JVM
之上),则此上下文会被多次使用。

type
和默认
key
"runtime"

name

  • Recommended. 运行时的名称。它可能源自
    raw_description
    。如果未提供
    raw_description
    ,则required

version

  • Optional. 运行时的版本标识符。

raw_description

  • Optional. 运行时获取的未处理的描述字符串。对于一些众所周知的运行时,如果没有明确给出,
    Sentry
    将尝试从这个字符串解析
    name
    version

App Context(应用上下文)

App context
描述了应用程序。与运行时相反,这是正在运行并携带有关当前
session
metadata
的实际应用程序。

type
和默认
key
"app"

app_start_time

  • Optional. 用户启动应用程序时的格式化 UTC 时间戳。

device_app_hash

  • Optional. 特定于应用程序的设备标识符。

build_type

  • Optional. 标识构建类型的字符串。例如,
    testflight

app_identifier

  • Optional. 与版本无关的应用程序标识符,通常是一个带点的
    bundle ID

app_name

  • Optional. 人类可读的应用程序名称,因为它出现在
    platform
    上。

app_version

  • Optional. 人类可读的应用程序版本,因为它出现在
    platform
    上。

app_build

  • Optional. 显示在
    platform
    上的内部构建标识符。

Browser Context(浏览器上下文)

Browser context
携带有关
browser
user agent
Web
相关错误信息。 这可以是发生此事件的浏览器,也可以是触发该事件的
Web
请求的
user agent

type
和默认
key
"browser"

name

  • Required. 浏览器应用程序的显示名称。

version

  • Optional. 浏览器的版本字符串。

GPU Context(GPU上下文)

GPU context
描述了设备的
GPU

name

  • Required. 图形设备的名称。

version

  • Optional. 图形设备的版本。

id

  • Optional. 图形设备的 PCI 标识符。

vendor_id

  • Optional. 图形设备的 PCI 供应商标识符。

vendor_name

  • Optional. 图形设备报告的供应商名称。

memory_size

  • Optional. 可用的总 GPU 内存(以兆字节为单位)。

api_type

  • Optional. 设备底层 API 类型。

    示例:

    "Apple Metal"
    "Direct3D11"

multi_threaded_rendering

  • Optional.
    GPU
    是否具有多线程渲染。

npot_support

  • Optional. Non-Power-Of-Two-Support(非二次幂支持)。

max_texture_size

  • Optional. 图形硬件支持的最大纹理尺寸。例如,
    16384

graphics_shader_level

  • Optional. 图形设备的近似
    着色器能力(shader capability)
    级别。例如,
    Shader Model 2.0, OpenGL ES 3.0, Metal / OpenGL ES 3.1, 27 (unknown)

supports_draw_call_instancing

  • Optional. 是否支持 GPU 绘制调用实例?

supports_ray_tracing

  • Optional. 设备上是否可以使用光线追踪?

supports_compute_shaders

  • Optional. 设备上是否可以使用计算着色器?

supports_geometry_shaders

  • Optional. 设备上是否可以使用几何体着色器?

例子:

"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(状态上下文)

State context
描述了应用程序的状态(例如:
Redux store
对象)。

type
和默认
key
"state"

state

  • Required. 具有两个
    key
    的对象:用于命名状态库(例如:Redux、MobX、Vuex)的 可选
    type
    和保存
    state
    对象的 必需
    value

示例:

"state": {
"state": {
"type": "MobX",
"value": {
"flights": [],
"airports": [],
"showModal": false
}
},
}

Culture Context(文化上下文)

Culture Context
描述了使用软件的文化的某些属性。

type
和默认
key
"culture"

calendar

  • Optional. 例如
    GregorianCalendar
    。自由形式的字符串。

display_name

  • Optional. 人类可读的文化名称。例如
    English (United States)

locale

  • Optional. 名称标识符,通常遵循
    RFC 4646
    。例如
    en-US
    pt-BR

is_24_hour_format

  • Optional. 布尔值,
    true
    false

timezone

  • Optional. 区域设置的时区。 例如,
    Europe/Vienna

示例

以下示例说明了

event payload
的上下文部分,并为简单起见省略了其他属性。

{
"contexts": {
"os": {
"name": "Windows"
},
"electron": {
"type": "runtime",
"name": "Electron",
"version": "4.0"
}
}
}

Debug Meta Interface(调试元接口)

调试元接口
携带用于处理
错误
崩溃报告
的调试信息。
Sentry
修改此接口中的信息。

Attributes(属性)

sdk_info

  • 描述系统 SDK 的对象:
    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

  • 加载到进程中的动态库列表(见下文)。

Debug Images(调试镜像)

调试镜像
列表包含加载到进程中的所有动态库及其内存地址。
Stack Trace
中的指令地址被映射到
调试镜像
列表中,以便检索调试文件进行
符号化(symbolication)

有两种调试镜像:

  • 具有
    macho
    elf
    pe
    类型的原生调试镜像
  • 类型为
    proguard
    Android
    调试镜像

MachO 镜像

MachO
镜像用于
Apple
平台。它们的结构与其他原生镜像相同。

属性:

type

  • Required. 调试镜像的类型。必须是
    "macho"

image_addr

  • Required. 内存地址,镜像安装在进程的虚拟地址空间中的位置。应该是以
    "0x"
    为前缀的十六进制表示形式的字符串。

image_size

  • 虚拟内存中镜像的大小。如果丢失,
    Sentry
    将假定镜像跨越到下一个镜像,这可能会导致无效的堆栈跟踪。

debug_id

  • Required. 动态库或可执行文件的标识符。它是
    Mach
    头中
    LC_UUID
    加载命令的值,格式为
    UUID

debug_file

  • Optional: 包含此镜像调试信息的
    dSYM
    文件的可选名称或绝对路径。从某些
    symbol
    服务器检索调试文件可能需要此值。

code_id

  • Optional. 动态库或可执行文件的标识符。它是
    Mach
    头中
    LC_UUID
    加载命令的值,格式为
    UUID
    Mach
    镜像可以为空,因为它相当于调试标识符。

code_file

  • Optional. 动态库或可执行文件的绝对路径。如果文件在
    Sentry
    上丢失,这有助于定位文件。

image_vmaddr

  • Optional. 镜像在虚拟内存中的首选加载地址,如镜像头中声明的那样。加载镜像时,操作系统可能仍会选择将其放置在不同的地址。

如果此值非零,则原生镜像中声明的所有

symbols
addresses
都从此地址开始,而不是
0
。 相比之下,
Sentry
处理相对于镜像开始的地址。 例如,对于
image_vmaddr: 0x40000
,位于
0x401000
symbol
的相对地址为
0x1000

Apple Crash Reports
addr2line
中使用的相对地址通常位于首选地址空间中,而不是相对地址空间。

arch

  • Optional. 模块的架构。如果丢失,这将由 Sentry 回填。

示例:

{
"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 镜像

ELF
镜像用于
Linux
平台。它们的结构与其他原生镜像相同。

属性:

type

  • Required. 调试镜像的类型。必须是
    "elf"

image_addr

  • Required. 内存地址,镜像安装在进程的虚拟地址空间中的位置。应该是以
    "0x"
    为前缀的十六进制表示形式的字符串。

image_size

  • Required. 虚拟内存中镜像的大小。如果丢失,
    Sentry
    将假定镜像跨越到下一个镜像,这可能会导致无效的堆栈跟踪。

debug_id

  • Required. 动态库或可执行文件的调试标识符。如果代码标识符可用,则调试标识符是该标识符前
    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

  • Optional. 包含此镜像的剥离调试信息的文件的
    名称
    绝对路径
    。从某些
    symbol
    服务器检索调试文件可能需要此值。

code_id

  • Optional. 动态库或可执行文件的标识符。如果程序是用相对较新的编译器编译的, 这应该是
    NT_GNU_BUILD_ID
    程序头的十六进制表示(类型
    PT_NOTE
    ), 或
    .note.gnu.build-id
    注释部分的值(类型
    SHT_NOTE
    )。否则,将此值留空。

某些

symbol
服务器使用代码标识符来定位
ELF
镜像的调试信息,在这种情况下,如果可能,应包含此字段。

code_file

  • Optional. 动态库或可执行文件的绝对路径。如果文件在
    Sentry
    上丢失,这有助于定位文件。

image_vmaddr

  • Optional. 镜像在虚拟内存中的首选加载地址,如镜像头中声明的那样。加载镜像时,操作系统可能仍会选择将其放置在不同的地址。

如果此值非零,则

原生镜像
中声明的所有符号和地址都从此地址开始,而不是
0
。 相比之下,
Sentry
处理相对于镜像开始的地址。 例如,对于
image_vmaddr: 0x40000
,位于
0x401000
的符号的相对地址为
0x1000

addr2line
中使用的相对地址通常在首选地址空间中,而不是相对地址空间。

arch

  • Optional. 模块的架构。如果丢失,这将由 Sentry 回填。

示例:

{
"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 镜像 (PDBs)

PE
镜像用于
Windows
平台,并附有
PDB
文件用于调试。它们的结构与其他原生镜像相同。

type

  • Required. 调试镜像的类型。必须是
    "pe"

image_addr

  • Required. 内存地址,镜像安装在进程的虚拟地址空间中的位置。应该是以
    "0x"
    为前缀的十六进制表示形式的字符串。

image_size

  • Required. 虚拟内存中镜像的实际大小。如果丢失,
    Sentry
    将假定镜像跨越到下一个镜像,这可能会导致无效的堆栈跟踪。

debug_id

  • Required.
    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

  • Required. 包含此镜像调试信息的
    PDB
    文件的名称。从特定
    symbol
    服务器检索调试文件通常需要此值。

code_id

  • Optional. 可执行文件或
    DLL
    的标识符。它包含来自
    COFF
    头的
    time_date_stamp
    和来自可选头的
    size_of_image
    的值,这些值使用
    %08x%X
    一起格式化为十六进制字符串(注意第二个值没有被填充):
time_date_stamp: 0x5ab38077
size_of_image:           0x9000
code_id:           5ab380779000

应提供代码标识符以允许

二进制崩溃报告
的服务器端堆栈遍历,例如
Minidumps

code_file

  • Optional.
    DLL
    或可执行文件的绝对路径。如果文件在
    Sentry
    上丢失,这有助于定位文件。应提供代码文件以允许二进制崩溃报告的服务器端堆栈遍历,例如
    Minidumps

image_vmaddr

  • Optional. 镜像在虚拟内存中的首选加载地址,如镜像头中声明的那样。加载镜像时,操作系统可能仍会选择将其放置在不同的地址。

原生镜像中的符号和地址始终相对于镜像的开头,不考虑首选加载地址。这只是对加载程序的一个提示。

arch

  • Optional. 模块的架构。 如果丢失,这将由 Sentry 回填。

示例:

{
"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 镜像

WASM
镜像用于
WebAssembly
。它们的结构与其他原生镜像相同。

属性:

type

  • Required. 调试镜像的类型。必须是
    "wasm"

debug_id

  • Required. 动态库或可执行文件的标识符。它是
    build_id
    自定义部分的值,必须格式化为截断到前导
    16
    个字节的
    UUID

debug_file

  • Optional. 包含此镜像调试信息的
    WASM
    文件的
    名称
    绝对 URL
    。 从某些
    symbol
    服务器检索调试文件可能需要此值。这应该对应于从
    external_debug_info
    自定义部分提取的外部化
    URL

code_id

  • Optional.
    WASM
    文件的标识符。它是格式为
    HEX
    字符串的
    build_id
    自定义部分的值。如果该部分包含
    UUID
    16
    字节),则可以省略它。

code_file

  • Required.
    wasm
    文件的绝对
    URL
    。如果文件在
    Sentry
    上丢失,这有助于定位文件。

示例:

{
"type": "wasm",
"debug_id": "84a04d24-0e60-3810-a8c0-90a65e2df61a",
"debug_file": "sample.wasm"
}

Proguard 镜像

Proguard
镜像是指
Proguard
混淆函数名时生成的
mapping.txt
文件。
Java SDK
集成为此文件分配了一个唯一标识符,该标识符必须包含在镜像列表中。

uuid

  • Required. Java SDK 分配的唯一标识符。

示例:

{
"uuid": "395835f4-03e0-4436-80d3-136f0749a893"
}

示例

请参阅上述调试镜像类型的示例。

{
"debug_meta": {
"images": [],
"sdk_info": {
"sdk_name": "iOS",
"version_major": 10,
"version_minor": 3,
"version_patchlevel": 0
}}
}

Exception Interface(异常接口)

异常接口指定程序中发生的异常或错误。

一个

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

  • 与堆栈跟踪接口对应的可选堆栈跟踪对象。

Exception Mechanism(异常机制)

异常机制
是驻留在 异常接口 中的可选字段。 它携带有关在目标系统上创建异常的方式的附加信息。 这包括从操作系统或运行时
API
获得的一般异常值,以及特定于机制的值。

属性

type

  • Required 该
    mechanism
    的唯一标识符决定了
    mechanism
    数据的呈现和处理。

description

  • Optional
    错误机制(error mechanism)
    的人类可读描述以及有关如何解决此错误的可能提示。

help_link

  • Optional 在线帮助资源的完全限定
    URL
    ,可能插入
    error
    参数。

handled

  • Optional 指示用户是否已处理异常的标志(例如,通过
    try ... catch
    )。

synthetic

  • Optional 指示此
    error
    是合成错误的标志。合成错误是本身没有什么意义的错误。 这可能是因为它们是在中心位置创建的(如
    crash handler
    ),并且都被称为相同的:
    Error
    Segfault
    等。 当设置
    flag
    时,
    Sentry
    将尝试使用其他信息(top in-app frame function)而不是主事件显示的
    UI
    中的异常类型和值。 例如,应该为所有
    "segfaults"
    设置此标志,否则每个
    error group
    看起来都非常相似。

meta

  • Optional 来自操作系统或运行时关于
    exception mechanism
    的信息。

data

  • 可能有助于用户理解此机制引发的错误的任意额外数据。

发送任何异常机制属性都需要

type
属性,即使 SDK 无法确定具体机制。 在这种情况下,将
type
设置为
generic
。请参阅下面的示例。

Meta information(元信息)

机制元数据(mechanism metadata)
通常携带由运行时或操作系统报告的错误代码,以及这些代码的平台相关解释。
SDK
可以安全地省略众所周知的
error code
的代码名称和描述,因为它们将由
Sentry
填写。 对于专有或供应商特定的
error code
,添加这些值将为用户提供附加信息。

meta
key 可能包含以下一个或多个属性:

signal

有关

POSIX signal
的信息。在
Apple
系统上,信号除了更详细地描述
signal
signal number
外,还带有代码。在
Linux
上,此代码不存在。

number

  • POSIX signal 编号。

code

  • Optional Apple signal 代码。

name

  • Optional 基于
    signal
    编号的
    signal
    名称。

code_name

  • Optional
    signal code
    的名称。
mach_exception

Apple
系统上的
Mach Exception
,包括
code triple(代码三元组)
和可选描述。

exception

  • Required 数字异常编号。

code

  • Required 数字异常代码。

subcode

  • Required 数字异常子代码。

name

  • Optional
    iOS / macOS
    中异常常量的名称。
ns_error

Apple 系统上的

NSError
,由
domain
code
组成。

code

  • Required 数字错误代码。

domain

  • Required
    NSError
    domain
    作为字符串。
errno

Linux
系统调用设置的错误代码和
ISO C99
POSIX.1-2001
POSIX.1-2008
中指定的一些库函数。 有关更多信息,请参阅 errno(3)

number

  • 错误编号

name

  • Optional 错误名称

示例

以下示例说明了发送异常的多种方式。 每个示例都包含

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
}
}
]
}
}

Message Interface(消息接口)

消息接口
携带描述
event
error
的日志消息。 可选地,它可以携带格式字符串和结构化参数。 这有助于将类似的消息归为同一问题。

属性

formatted

  • Required. 完全格式化的消息。如果丢失,

    Sentry
    将尝试插入消息。

    它不得超过

    8192
    个字符。较长的消息将被截断。
    Sentry
    还接受未设置为支持旧版
    SDK
    的消息。

message

  • Optional. 原始消息字符串(未插入的)。

    它不得超过 8192 个字符。较长的消息将被截断。

params

  • Optional. 格式化参数列表,最好是字符串。非字符串将被强制为字符串。

示例

{
"message": {
"message": "My raw message with interpreted strings like %s",
"params": ["this"]
}
}

Request Interface(请求接口)

请求接口
包含有关与事件相关的
HTTP
请求的信息。 在客户端
SDK
中,这可以是传出请求,也可以是渲染当前网页的请求。 在
server SDK
上,这可能是正在处理的传入
Web
请求。

数据变量应该只包含请求

body
(而不是
query string
)。它可以是字典(用于标准
HTTP
请求)或原始请求
body

有序 Map

请求接口
中,几个属性可以声明为
字符串(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

  • Optional. 请求的 HTTP 方法。

url

  • Optional. 请求的
    URL
    (如果可用)。查询字符串可以作为
    url
    的一部分声明,也可以在
    query_string
    中单独声明。

query_string

  • Optional.

    URL
    的查询字符串组件。可以作为未解析的字符串、字典或元组列表给出。

    如果查询字符串未声明并且是

    url
    参数的一部分,
    Sentry
    会将其移动到查询字符串中。

data

  • Optional. 以最有意义的格式提交数据。默认情况下,

    SDK
    应丢弃大型
    body
    。可以作为任何格式的字符串或结构数据给出。

    在将请求数据附加到事件之前,始终修剪和截断请求数据。 如果这不可能,请在

    API
    文档中添加用户应截断请求数据的说明。 虽然
    Sentry
    会在摄取时尝试修剪此字段,但大型
    body
    可能会导致整个事件有效负载超过其最大大小限制, 在这种情况下,事件将被丢弃。

cookies

  • Optional. cookie 的值。可以以字符串、字典或元组列表的形式给出未解析的字符串。

headers

  • Optional. 已提交
    header
    的字典。如果一个
    header
    多次出现,则需要按照
    HTTP header
    合并标准进行合并。
    Sentry
    不区分大小写地处理
    Header
    名称。

env

  • Optional. 包含从服务器传递的

    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 Interface(SDK 接口)

SDK 接口
描述了
Sentry SDK
及其用于
捕获
传输
事件的配置。

属性

name

  • Required. SDK 的名称。格式为

    entity.ecosystem[.flavor]
    其中 entity 标识了
    SDK
    的开发者, ecosystem 是指使用
    SDK
    的编程语言或平台,可选的 flavor 用于标识属于主要生态系统的独立
    SDK

    官方

    Sentry SDK
    使用 entity(实体)
    sentry
    。示例:

    sentry.python
  • sentry.javascript.react-native

version

  • Required. SDK 的版本。它应该具有 Semantic Versioning 格式
    MAJOR.MINOR.PATCH
    , 没有任何前缀(在主要版本号之前没有
    v
    或任何其他内容)。 示例:
    0.1.0
  • 1.0.0
  • 4.3.12

integrations

  • Optional. 标识启用的集成的名称列表。该列表应包含所有启用的集成,包括默认集成。 包含默认集成是因为
    不同的 SDK 版本
    可能包含
    不同的默认集成

packages

  • Optional. 作为此 SDK 或激活的集成的一部分安装的软件包列表。每个包都包含格式为
    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"
}
]
}
}

Stack Trace Interface(堆栈跟踪接口)

堆栈跟踪
包含一个
帧列表
,每个
都有描述该
上下文的各种位(大多数可选)。
应该从最旧到最新排序。

堆栈跟踪始终是异常或线程的一部分。它们不能被声明为顶级事件属性。向事件添加堆栈跟踪时,请遵循以下经验法则:

  • 如果堆栈跟踪是
    错误(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"
}
}

Template Interface(模板接口)

当常规堆栈跟踪不包含模板数据时,模板接口对于特定于模板引擎的报告很有用。例如,这在

Django
框架中是必需的,其中模板未集成到
Python
堆栈跟踪中。

渲染的模板。这通常用作堆栈跟踪中的单个帧,并且仅在模板系统不提供适当的堆栈跟踪时才应使用。

属性

属性

filename
context_line
lineno
是必需的。

lineno

  • 调用的行号。

abs_path

  • 文件系统上模板的绝对路径。

filename

  • 传递给模板加载器的文件名。

context_line

  • lineno 文件名中的源代码。

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"
],
}
}

Threads Interface(线程接口)

线程接口指定在事件发生时正在运行的线程。这些线程还可以包含堆栈跟踪。

一个

event
可能在一个名为
threads
的属性中包含一个或多个线程。

threads
属性应该是一个带有
values
属性的对象包含一个或多个值,这些值是采用下述格式的对象。

根据

Sentry
策略,因
exception
而崩溃的线程不应有堆栈跟踪, 而是应在
exception
上设置
thread_id
属性,
Sentry
将连接两者。

属性

id

  • Required. 线程的 ID。通常是数字或数字字符串。需要在线程中是唯一的。
    exception
    可以设置
    thread_id
    属性来交叉引用此线程。

crashed

  • Optional. 指示线程是否崩溃的标志。默认为
    false

current

  • Optional. 指示线程是否在前台的标志。默认为
    false

name

  • Optional. 线程名称。

stacktrace

  • Optional. 堆栈跟踪接口对应的堆栈跟踪对象。

如果这是一个错误事件,则应在异常接口中声明主要异常的堆栈跟踪。 如果有单个异常,

Sentry
将自动移动唯一崩溃线程的堆栈跟踪。

示例

以下示例说明了

event payload
的线程部分,并为简单起见省略了其他属性。

{
"threads": {
"values": [
{
"id": "0",
"name": "main",
"crashed": true,
"stacktrace": {}
}
]
}
}

User Interface(用户接口)

描述请求的经过身份验证的用户的接口。

例如,您应该至少为

Sentry
提供
id
email
ip_address
username
之一,以便能够告诉你有多少用户受到一个问题的影响。 发送没有这些属性而只有自定义属性的用户是有效的,但没有那么有用。

属性

id

  • 用户的特定于应用程序的内部标识符。

username

  • 用户名。通常用作比内部
    id
    更好的标签。

email

  • 用户名的替代或补充。
    Sentry
    知道电子邮件地址,可以显示诸如
    Gravatars
    之类的内容并解锁消息传递功能。

ip_address

  • 用户的
    IP
    地址。如果用户未经身份验证,
    Sentry
    使用
    IP
    地址作为用户的唯一标识符。设置为
    "{{auto}}"
    以让
    Sentry
    从连接推断
    IP
    地址。

所有其他

key
都存储为
extra
信息,但不会由
Sentry
专门处理。

自动 IP 地址

在客户端平台上运行的

SDK
,例如浏览器和移动应用程序,应该默认设置
ip_address = "{{auto}}"
。 相反,服务器端
SDK
应填充
请求接口
Sentry
使用几种回退来回填
IP
地址:

  1. 如果直接设置,请使用
    user.ip_address
  2. 如果可用,回退到
    http.env.REMOTE_ADDR
  3. Sentry
    看到的连接
    IP
    地址,如果使用了
    {{auto}}

示例

{
"user": {
"id": "unique_id",
"username": "my_user",
"email": "foo@example.com",
"ip_address": "127.0.0.1",
"subscription": "basic"
}
}
公众号:黑客下午茶
内容来自用户分享和网络整理,不保证内容的准确性,如有侵权内容,可联系管理员处理 点击这里给我发消息
标签: