## SDK 開發 1. [頂級開源專案 Sentry 20.x JS-SDK 設計藝術（理念與設計原則篇）](https://mp.weixin.qq.com/s/5h5_q6lmbqUy1x__R9C2WA) 2. [頂級開源專案 Sentry 20.x JS-SDK 設計藝術（開發基礎篇）](https://mp.weixin.qq.com/s/YpysOHQslu9kjOw0SQQ_Ng) 3. [頂級開源專案 Sentry 20.x JS-SDK 設計藝術（概述篇）](https://mp.weixin.qq.com/s/zqLkXn290DPU_c47rdLeSw) ## 系列 1. [Snuba：Sentry 新的搜尋基礎設施(基於 ClickHouse 之上)](https://mp.weixin.qq.com/s/RKaBfEh8Dlgt_iuHt10OPg) 2. [Sentry 10 K8S 雲原生架構探索，Vue App 1 分鐘快速接入](https://mp.weixin.qq.com/s/Rwwz4MJytA7va8zE8A5Y0w) 3. [Sentry(v20.x)玩轉前/後端監控與事件日誌大資料分析，使用 Helm 部署到 K8S 叢集](https://mp.weixin.qq.com/s/5xYtkzNx31dLsCAhoMPGrQ) 4. [Sentry(v20.x) JavaScript SDK 三種安裝載入方式](https://mp.weixin.qq.com/s/EV9M3Ru5rK5atAjTl1D9PA) 5. [Sentry(v20.x) JavaScript SDK 配置詳解](https://mp.weixin.qq.com/s/dlaejrn1kWBPiUJSmrzwow) 6. [Sentry(v20.x) JavaScript SDK 手動捕獲事件基本用法](https://mp.weixin.qq.com/s/4b4ojLkKGM6QX0z4Jq8nNQ) 7. [Sentry(v20.x) JavaScript SDK Source Maps詳解](https://mp.weixin.qq.com/s/-FySq0YUf2lJY2DjOORcIg) 8. [Sentry(v20.x) JavaScript SDK 故障排除](https://mp.weixin.qq.com/s/BHyLOCI53EUoswUjm1-dXw) 9. [Sentry(v20.x) JavaScript SDK 1分鐘上手效能監控](https://mp.weixin.qq.com/s/Z3Dp1fyzAEc5c89vy3Bzmw) 10. [Sentry(v20.x) JavaScript SDK 效能監控之管理 Transactions](https://mp.weixin.qq.com/s/Si2GLgGKsCwErJjJKFvtQg) 11. [Sentry(v20.x) JavaScript SDK 效能監控之取樣 Transactions](https://mp.weixin.qq.com/s/GdOFEE2aKVM7d5mWM1zVZw) 12. [Sentry(v20.x) JavaScript SDK Enriching Events(豐富事件資訊)](https://mp.weixin.qq.com/s/scjuodVzpApe59MBRwZtpQ) 13. [Sentry(v20.x) JavaScript SDK Data Management（問題分組篇）](https://mp.weixin.qq.com/s/DW061Q5ISf5FTXCYsMy5Tg) ## 統一的API 新的 `Sentry SDK` 應遵循 `Unified API`，使用一致的術語來指代概念。 本文件說明了 `Unified API` 是什麼以及為什麼它存在。 ### 動機 `Sentry` 有各種各樣的 `SDK`，這些 `SDK` 是由不同的開發人員根據不同的想法在過去幾年裡開發出來的。這導致了不同 `SDK` 的特性設定不同，使用不同的概念和術語，這導致了通常不清楚如何在不同的平臺上實現相同的東西。 此外，這些 `SDK` 完全以通過 `explicit clients` 進行錯誤報告為中心，這意味著通常無法進行某些整合（例如麵包屑 `breadcrumbs`）。 ### 一般準則 * 我們希望所有 `SDK API` 的語言/措辭統一，以輔助支援和文件編制，並使使用者更輕鬆地在不同環境中使用 `Sentry`。 * 在設計 `SDK` 時，我們可以新增一些新的功能，而不是單純的事件報告（`transactions`，`APM`等）。 * 設計具有相同 `client` 例項的 `SDK`，我們既可以通過依賴項注入等在執行時環境中自然工作，也可以使用隱式上下文分派給已經存在的 `clients` 和 `scopes`，以掛接到大多數環境中。 這很重要，因為它允許事件將流程中其他整合的資料包括在內。 * 常見任務必須簡單明瞭。 * 為了幫助第三方庫，“non configured Sentry” 的情況需要快速處理（和延遲執行）。 * 通用 `API` 需求在大多數語言中都是有意義的，並且一定不能依賴於超級特殊的構造。 為了使它更自然，我們應該考慮語言細節，並明確地支援它們作為替代方法（`disposables`, `stack guards` 等）。 ### 簡化過的圖解  ### 術語 * **minimal**：一個單獨的 `“facade”` 包，它通過介面（`interfaces`）或代理（`proxies`）重新匯出 `SDK` 功能的子集。該包不直接依賴於 `SDK`，相反，如果沒有安裝 `SDK`，它應該使每個操作都成為 `noop`。這樣一個包的目的是允許 `random` 庫記錄麵包屑和設定上下文資料，同時不依賴 `SDK`。 * **hub**：管理狀態的物件。預設情況下可以使用隱含的 `global thread local` 或類似的 `hub`。`Hubs` 可以手動建立。 * **scope**：`scope` 包含了應該與 `Sentry` 事件一起隱式傳送的資料。它可以儲存上下文資料、額外引數、級別覆蓋、指紋等。 * **client**：`client` 是隻配置一次的物件，可以繫結到 `hub`。然後，使用者可以自動發現 `client` 並分派對它的呼叫。使用者通常不需要直接與 `client` 打交道。它們要麼通過 `hub` 實現，要麼通過 `static convenience functions` 實現。`client` 主要負責構建 `Sentry` 事件並將其傳送到 `transport`。 * **client options**：是特定於語言和執行時的引數，用於配置 `client`。 這可以是 `release` 和 `environment`，也可以是要配置的 `integrations`，`in-app works` 等。 * **context**：`Contexts` 為 `Sentry` 提供額外的資料。有特殊的上下文（ `user` 和類似的）和通用的上下文（runtime，os，device），等等。檢查有效鍵的 `Contexts`。注意:在舊的 `SDK` 中，您可能會遇到一個與上下文無關的概念，這個概念現在已被作用域棄用。 * **tags**：`Tags` 可以是任意 `string` → 可以搜尋事件的 `string pairs`。 `Contexts` 被轉換為 `tags`。 * **extra**：`client users` 附加的真正任意資料。這是一個已棄用的特性，但在可預見的未來將繼續得到支援。鼓勵使用者使用上下文代替。 * **transport**：`transport` 是對事件傳送進行抽象的客戶端的內部構造。通常，`transport` 在單獨的執行緒中執行，並獲取通過佇列傳送的事件。`transport` 負責傳送（`sending`）、重試（`retrying`）和處理速率限制（`handling rate limits`）。如果需要，`transport` 還可能在重啟過程中持久化未傳送的事件。 * **integration**：向特定框架（`frameworks`）或環境（`environments`）提供中介軟體（`middlewares`）、繫結（`bindings`）或鉤子（`hooks`）的程式碼，以及插入這些繫結並激活它們的程式碼。整合的使用不遵循公共介面。 * **event processors**：針對每個事件執行的回撥（`Callbacks`）。他們可以修改並返回事件，或者可以為 `null`。返回 `null` 將丟棄該事件，並且不會進一步處理。有關更多資訊，請參見事件管道（`Event Pipeline`）。 * **disabled SDK**：大多數 `SDK` 功能依賴於已配置的 `active client`。當有 `transport` 時，Sentry 認為 `client` 是 `active` 的。否則，客戶端是 `inactive` 的，`SDK` 被認為是 `“disabled”`。在這種情況下，某些回撥函式，例如 `configure_scope` 或事件處理器（`event processors`），可能不會被呼叫。因此，麵包屑（`breadcrumbs`）不會被記錄下來。 ### "Static（靜態）API" 靜態 `API` 函式是最常見的面向使用者的 `API`。使用者只需匯入這些功能，即可開始向 `Sentry` 發出事件或配置作用域。這些快捷方式功能應在包的頂級名稱空間中匯出。 他們在後臺使用 `hubs` 和 `scopes`（有關更多資訊，請參見併發性 `Concurrency`）（如果在該平臺上可用）。請注意，下面列出的所有函式大部分都是 `Hub::get_current().function` 的別名。 * `init(options)`：這是每個 `SDK` 的入口點。 通常，這會建立(`creates`)/重新初始化(`reinitializes`)傳播到所有新執行緒(`new threads`)/執行上下文(`execution contexts`)的`global hub`，或者為每個執行緒(`per thread`)/執行上下文(`execution context`)建立一個 `hub`。 接受 `options`（`dsn` 等），配置 `client` 並將其繫結到當前 `hub` 或對其進行初始化。應返回一個 `stand-in`，可用於 `drain events`（一次性）。 這可能會返回一個 `handle` 或 `guard` 來處理。如何實現這一點完全取決於 `SDK`。這甚至可能是一個 `client`，如果這對 `SDK` 有意義的話。在 `Rust` 中，它是一個 `ClientInitGuard`，在 `JavaScript` 中，它可以是一個帶有可等待的 `close` 方法的 `helper` 物件。 您應該能夠多次呼叫此方法，而第二次呼叫它既可以拆除先前的 `client`，也可以減少先前 `client` 的引用計數，等等。 多次呼叫只能用於測試。如果您在應用程式啟動以外的任何時間呼叫 `init`，將會是 `undefined`。 使用者必須呼叫一次 `init`，但允許使用禁用的 `DSN` 進行呼叫。 例如可能沒有引數傳遞等。 此外，它還設定了所有預設的整合。 * `capture_event(event)`：接受一個已經組合好的事件，並將其排程到當前活動的中心。 事件物件可以是普通字典或型別化的物件，無論在SDK中更有意義。 它應儘可能遵循本機協議，而忽略平臺特定的重新命名（案例樣式等）。 * `capture_exception(error)`：報告 `error` 或 `exception` 物件。根據平臺的不同，可能有不同的引數。最明顯的版本只接受一個 `error` 物件，但在不傳遞 `error` 且使用當前 `exception` 的情況下也可能發生變化。 * `capture_message(message, level)`：報告 `message`。級別可以是可選的語言預設引數，在這種情況下，它應該預設為 `info`。 * `add_breadcrumb(crumb)`：向 `scope` 新增新的麵包屑。 如果麵包屑的總數超過 `max_breadcrumbs` 設定，則 `SDK` 應刪除最舊的麵包屑。這與 `Hub API` 的工作原理類似。如果禁用了 `SDK`，它應該忽略 `breadcrumb`。 * `configure_scope(callback)`：可以重新配置 `scope` 物件呼叫的回撥。這用於為相同範圍內的未來事件附加上下文資料。 * `last_event_id()`：應該返回當前作用域發出的最後一個事件 `ID`。例如，這用於實現使用者反饋對話方塊（`feedback`）。 ### 併發 所有 `SDK` 都應具有併發安全上下文儲存（`concurrency safe context storage`）的概念。 這意味著什麼取決於語言。 基本思想是，`SDK` 的使用者可以呼叫一種方法來為即將記錄的所有事件安全地提供其他上下文資訊。 在大多數語言中，這是作為 `thread local stack` 實現的，但在某些語言中（比如 `JavaScript`），它可能是全域性的，因為假設這在環境中是有意義的。 以下是一些常見的併發模式： * **Thread bound hub**：在這種模式下，每個 `thread` 都有自己的 `“hub”`，該 `hub` 在內部管理一系列作用域`scopes`。 如果遵循該模式，則一個 `thread`（呼叫 `init()` 的執行緒）將成為 `“main” hub`，該 `hub` 將用作新生成的執行緒的基礎，該執行緒將獲得基於主 `hub` 的 `hub`（但又是獨立的）。 * **Internally scoped hub**：在一些平臺上，如 `.NET ambient data` 是可用的，在這種情況下 `Hub` 可以內部管理作用域`scopes`。 * **Dummy hub**：在一些平臺上，併發性`concurrency`本身並不存在。在這種情況下，`hub` 可能完全不存在，或者只是一個沒有併發管理`concurrency management`的單例。 ### Hub 在正常情況下，hub 由一堆 `clients` 和 `scopes` 組成。 `SDK` 維護兩個變數：`main hub`（一個全域性變數）和 `current hub`（當前執行緒`thead`或執行上下文`execution context`的本地變數，有時也稱為非同步本地`async local`或上下文字地`context local`變數） * `Hub::new(client, scope)`：使用給定的 `client` 和 `scope` 建立一個新的 `hub`。`client` 可以在 `hubs` 之間重用。`scope` 應歸 `hub` 所有（如有必要，請進行 `clone`） * `Hub::new_from_top(hub)` / 或者原生建構函式過載`native constructor overloads`：通過克隆另一個 `hub` 的頂部堆疊`top stack`來建立新的 `hub`。 * `get_current_hub()` / `Hub::current()` / `Hub::get_current()`：全域性函式或靜態函式以返回當前（執行緒的）`hub`。 * `get_main_hub()` / `Hub::main()` / `Hub::get_main()`：在主執行緒`main thread`是特殊的語言中（`“Thread bound hub”`模型），這會返回 `main thread` 的中心而不是當前執行緒 `current thread` 的中心。這可能並不存在於所有的語言中。 * `Hub::capture_event` / `Hub::capture_message` / `Hub::capture_exception`：捕獲 `message / exception` 到 `capture event`。`capture_event` 將傳遞的 `event` 與 `scope` 資料合併，並分派給 `client`。作為附加引數，它還需要一個提示。有關 `hint` 引數，請參見 `hints`。 * `Hub::push_scope()`：推送一個繼承前一個數據的新作用域層`new scope layer`。 這應返回有意義的語言的 `disposable` 或 `stack guard`。當使用 “內部作用域中心”`internally scoped hub` 併發模型時，通常需要對此進行呼叫，否則可能會意外地錯誤共享作用域。 * `Hub::with_scope(callback)` (optional)：在 `Python` 中，這可能是上下文管理器；在 `Ruby` 中，這可能是塊函式。推動並彈出整合工作的 `scope`。 * `Hub::pop_scope(callback)` (optional)：只存在於沒有更好的資源管理`resource management`的語言中。最好在 `push_scope` 的返回值上使用這個函式，或者使用 `with_scope`。這有時也被稱為 `pop_scope_unsafe`，以表明不應該直接使用該方法。 * `Hub::configure_scope(callback)`：使用對修改範圍的可變引用來呼叫回撥。 這也可以是具有它的語言（`Python`）中的 `with` 語句。如果沒有 `active client` 繫結到該 `hub`，則 `SDK` 不應呼叫回撥。 * `Hub::add_breadcrumb(crumb, hint)`：將麵包屑新增到當前作用域。 * 支援的引數應為： * 建立麵包屑的函式 * 已經建立的麵包屑物件 * 麵包屑列表(可選) * 在沒有基本過載形式的語言中，只有原始的麵包屑物件`raw breadcrumb object`應該被接受。 * 如果沒有 `active client` 繫結到該 `hub`，則 `SDK` 應忽略麵包屑。 * 有關 `hint` 引數，請參見 `hints`。 * `Hub::client() / Hub::get_client()` (optional)：返回當前 `client` 或 `None` 的 `Accessor` 或 `getter`。 * `Hub::bind_client(new_client)`：將不同的 `client` 繫結到 `hub`。如果 `hub` 也是 `init` 建立的 `client` 的所有者，那麼如果 `hub` 是負責處理它的物件，則需要保留對它的引用。 * `Hub::unbind_client()` (optional)：對於 `bind_client` 不接受空值的語言，可選的解繫結方法。 * `Hub::last_event_id()`：應該返回當前 `scope` 發出的最後一個 `event ID`。例如，這是用來實現使用者反饋對話方塊`feedback dialogs`。 * `Hub::run(hub, callback) hub.run(callback), run_in_hub(hub, callback)`(optional)：執行將 `hub` 繫結為當前 `hub` 的回撥。 ### Scope `scope` 包含了應該與 `Sentry` 事件一起隱式傳送的資料。它可以儲存上下文資料`context data`、額外引數`extra parameters`、級別覆蓋`level overrides`、指紋`fingerprints`等。 使用者可以通過全域性函式 `configure_scope` 修改當前作用域(設定額外的、標記、當前使用者)。`configure_scope` 接受一個回撥函式，並將當前的作用域傳遞給它。 使用這種基於回撥的 `API` 的原因是效率。如果禁用了 `SDK`，它就不應該呼叫回撥函式，從而避免不必要的工作。 ```js Sentry.configureScope(scope => scope.setExtra("character_name", "Mighty Fighter")); ``` * `scope.set_user(user)`：淺合併使用者 `Shallow merges` 配置（電子郵件`email`，使用者名稱`username`等）。刪除使用者資料是 SDK 定義的，可以使用 `remove_user` 函式，也可以不傳遞任何資料。 * `scope.set_extra(key, value)`：將附加鍵設定為任意值，覆蓋潛在的先前值。 刪除 `key` 是 `SDK` 定義的，可以使用 `remove_extra` 函式或不傳遞任何資料作為資料。這是不推薦使用的功能，應鼓勵使用者改用上下文。 * `scope.set_extras(extras)`：設定一個具有 `key/value` 對，便捷功能的物件，而不是多個 `set_extra` 呼叫。與 `set_extra` 一樣，這被視為已棄用的功能。 * `scope.set_tag(key, value)`：將 `tag` 設定為字串值，覆蓋潛在的先前值。 刪除 `key` 是 `SDK` 定義的，可以使用 `remove_tag` 函式或不傳遞任何資料作為資料。 * `scope.set_tags(tags)`：設定一個具有 `key/value` 對，便捷功能的物件，而不是多個 `set_tag` 呼叫。 * `scope.set_context(key, value)`：將上下文鍵設定為一個值，覆蓋一個潛在的先前值。刪除 `key` 是 `SDK` 定義的，可以使用 `remove_context` 函式或不傳遞任何資料作為資料。 這些型別是 `sdk` 指定的。 * `scope.set_level(level)`：設定在此 `scope` 內傳送的所有事件的級別。 * `scope.set_transaction(transaction_name)`：設定當前 `transaction` 的名稱。 * `scope.set_fingerprint(fingerprint[])`：將指紋設定為將特定事件分組在一起。 * `scope.add_event_processor(processor)`：註冊事件處理器函式 `event processor`。它接受一個事件並返回一個新事件，或者返回 `None` 來將其刪除。這是許多整合的基礎。 * `scope.add_error_processor(processor)`(optional)：註冊錯誤處理器函式。 它接受一個事件和異常物件，並返回一個新事件或`“None”`將其刪除。 這可用於從 `SDK` 無法提取自身的異常物件中提取其他資訊。 * `scope.clear()`：將 `scope` 重置為預設值，同時保留所有已註冊的事件處理器`event processors`。這不會影響子作用域或父作用域。 * `scope.add_breadcrumb(breadcrumb)`：將麵包屑新增到當前 `scope`。 * `scope.clear_breadcrumbs()`：從 `scope` 中刪除當前的麵包屑 `breadcrumbs`。 * `scope.apply_to_event(event[, max_breadcrumbs])`：將 `scope` 資料應用於給定的事件物件。這也適用於內部儲存在 `scope` 中的事件處理器 `event processors`。 一些實現可能想要在此處設定最大面包屑計數。 ### Client `Client` 是 `SDK` 中負責事件建立的部分。 例如，`Client` 應將異常轉換為 `Sentry event`。`Client` 應該是無狀態的，它會注入作用域並委託將事件傳送到 `Transport` 的工作。 * `Client::from_config(config)`：（或者是普通的建構函式）這通常採用帶有 `options + dsn` 的物件。 * `Client::capture_event(event, scope)`：通過將事件與其他資料（`client` 預設設定）合併來捕獲事件。另外，如果將 `scope` 傳遞到此係統，則來自該範圍的資料會將其傳遞到內部 `transport`。 * `Client::close(timeout)`：重新整理佇列直到超時秒。如果客戶端能夠保證事件的交付僅持續到當前時間點，則首選此方法。這可能會因為超時秒而阻塞。在呼叫 `close` 後，客戶端應該被禁用或銷燬。 * `Client::flush(timeout)`：和 `close` 的區別一樣，客戶端在呼叫 `flush` 後不會被釋放。 ### Hints （可選）支援事件捕獲和麵包屑新增的附加引數：`hint`。 `hint` 是特定於 `SDK` 的，但提供了關於事件起源的高階資訊。例如，如果捕獲了一個異常，提示可能攜帶原始異常物件。並不是所有的 `SDK` 都需要提供這個功能。然而，這個引數是為此目的保留的。 ### Event Pipeline `capture_event` 捕獲的事件將按以下順序處理。 **注意**：事件可以在任何階段丟棄，此時不會發生進一步的處理。 1. 如果禁用 `SDK`, `Sentry` 會立即丟棄該事件。 2. 客戶端根據配置的取樣速率對事件進行取樣。事件可以根據抽樣率隨機丟棄。 3. 使用 `apply_to_event` 應用該作用域。按順序呼叫作用域的事件處理器。 4. `Sentry` 呼叫 `before-send` 鉤子。 5. `Sentry` 將事件傳遞到配置的 `transport`。如果傳輸沒有有效的 `DSN`，則可以丟棄該事件；它的內部佇列已滿；或由於伺服器要求的速率限制。 ### Options 許多選項都是跨 `SDK` 標準化的。有關這些選項的列表，請參閱 `the main options documentation`。 ```sh 我是為少 微信：uuhells123 公眾號：黑客下午茶 加我微信（互相學習交流），關注公眾號（獲取更多學習資料~