Sentry 開發者貢獻指南 – SDK 開發(事件負載)

• 2021 年 12 月 28 日
• 筆記

內容整理自官方開發文檔

系列

• 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 紀元以來經過的秒數的數字（整數或浮點數）值。
  • //tools.ietf.org/html/rfc3339
  • //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，也可以是具有語義版本的產品標識符（建議格式為 [email protected]）。

{
  "release": "[email protected]"
}

{
  "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 }}", "//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 的狀態。

{
  "status": "ok"
}

tags

• Optional. 事件 tags 的 map 或 list，每個 tag 必須少於 200 個字元。

{
"tags": {
  "ios_version": "4.0",
  "context": "production"
}
}

data

• Optional. 與此 Span 關聯的任意數據。

{
  "data": {
    "url": "//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": "//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 的狀態。

{
  "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": "//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 文檔頁面上閱讀手動麵包屑記錄和自定義的概述。

• //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": "//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. 螢幕解析度（例如：800×600、3040×1444）。

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) 。

• //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": "//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://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": "[email protected]",
    "ip_address": "127.0.0.1",
    "subscription": "basic"
  }
}

公眾號：黑客下午茶