Sentry 开发者贡献指南 - (事件负载第一篇)

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

• 指示在 Sen

{
  "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. 表示测量开始时间的时间戳。格式要么是 RFC3339 中定义的字符串，
  要么是表示自 Unix 纪元以来经过的秒数的数字（整数或浮点数）值。
  start_timestamp 值必须大于或等于时间戳值，否则 Span 将被视为无效而丢弃。

{
"start_timestamp": "2011-05-02T17:41:36.242Z"
}

或者：

{
"start_timestamp": 1304358096.242
}

timestamp

• Required. 表示测量完成时的时间戳。格式要么是 RFC3339 中定义的字符串，
  要么是表示自 Unix 纪元以来经过的秒数的数字（整数或浮点数）值。

{
"timestamp": "2011-05-02T17:41:36.955Z"
}

或者：

{
"timestamp": 1304358096.955
}

status

• Optional. 描述 Span/Transaction 的状态。

事件负载(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 指示在 Sen { "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" } }