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

公眾號：黑客下午茶