内容整理自官方开发文档

系列

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