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

内容整理自官方开发文档

系列

• Docker Compose 部署与故障排除详解
• 1 分钟快速使用 Docker 上手最新版 Sentry-CLI - 创建版本
• 快速使用 Docker 上手 Sentry-CLI - 30 秒上手 Source Maps
• Sentry For React 完整接入详解
• Sentry For Vue 完整接入详解
• Sentry-CLI 使用详解
• Sentry Web 性能监控 - Web Vitals
• Sentry Web 性能监控 - Metrics
• Sentry Web 性能监控 - Trends
• Sentry Web 前端监控 - 最佳实践(官方教程)
• Sentry 后端监控 - 最佳实践(官方教程)
• Sentry 监控 - Discover 大数据查询分析引擎
• Sentry 监控 - Dashboards 数据可视化大屏
• Sentry 监控 - Environments 区分不同部署环境的事件数据
• Sentry 监控 - Security Policy 安全策略报告
• Sentry 监控 - Search 搜索查询实战
• Sentry 监控 - Alerts 告警
• Sentry 监控 - Distributed Tracing 分布式跟踪
• Sentry 监控 - 面向全栈开发人员的分布式跟踪 101 系列教程(一)
• Sentry 监控 - Snuba 数据中台架构简介(Kafka+Clickhouse)
• Sentry 监控 - Snuba 数据中台架构(Data Model 简介)
• Sentry 监控 - Snuba 数据中台架构(Query Processing 简介)
• Sentry 官方 JavaScript SDK 简介与调试指南
• Sentry 监控 - Snuba 数据中台架构(编写和测试 Snuba 查询)
• Sentry 监控 - Snuba 数据中台架构(SnQL 查询语言简介)
• Sentry 监控 - Snuba 数据中台本地开发环境配置实战
• Sentry 监控 - 私有 Docker Compose 部署与故障排除详解
• Sentry 开发者贡献指南 - 前端(ReactJS生态)
• Sentry 开发者贡献指南 - 后端服务(Python/Go/Rust/NodeJS)
• Sentry 开发者贡献指南 - 前端 React Hooks 与虫洞状态管理模式
• Sentry 开发者贡献指南 - SDK 开发(性能监控)

公众号：黑客下午茶

事件负载(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

• 指示在 Sentry SDK 中创建事件的时间。格式要么是 RFC 3339 中定义的字符串，要么是表示自 Unix 纪元以来经过的秒数的数字(整数或浮点数)值。
  • https://tools.ietf.org/html/rfc3339
  • https://en.wikipedia.org/wiki/Unix_time

{
  "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 文档页面上阅读手动面包屑记录和自定义的概述。

• https://docs.sentry.io/platform-redirect/?next=/enriching-events/breadcrumbs/

一个事件可能包含一个带有一个条目 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) 。

• http://man7.org/linux/man-pages/man3/errno.3.html

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

公众号：黑客下午茶