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

本文轉載自查看原文 2021-12-28 19:32 745

內容整理自官方開發文檔

系列

公眾號：黑客下午茶

事件負載(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 的時間線。

面包屑不會按時間戳排序，它們會按照添加的方式保持順序。

下面是對各個面包屑類型的描述，以及它們的 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 地址：

如果直接設置，請使用 user.ip_address。
如果可用，回退到 http.env.REMOTE_ADDR。
Sentry 看到的連接 IP 地址，如果使用了 {{auto}}。

示例

{
  "user": {
    "id": "unique_id",
    "username": "my_user",
    "email": "foo@example.com",
    "ip_address": "127.0.0.1",
    "subscription": "basic"
  }
}

公眾號：黑客下午茶

免責聲明！

本站轉載的文章為個人學習借鑒使用，本站對版權不負任何法律責任。如果侵犯了您的隱私權益，請聯系本站郵箱yoyou2525@163.com刪除。

猜您在找 Sentry 開發者貢獻指南 - SDK 開發(性能監控) Sentry 開發者貢獻指南 - 什么是 Scope, 什么是 Hub？ Sentry 開發者貢獻指南 - 前端(ReactJS生態) Sentry 開發者貢獻指南 - 后端服務(Python/Go/Rust/NodeJS) Sentry 開發者貢獻指南 - 前端 React Hooks 與蟲洞狀態管理模式 ZooKeeper開發者指南(五) ProtoBuf開發者指南 RocketMQ開發者指南 ProtoBuf開發者指南（轉） Android SDK 開發指南