Sentry 開發者貢獻指南 - SDK 開發(性能監控：Sentry SDK API 演進)
本文檔的目標是將 Sentry SDK 中性能監控功能的演變置于上下文中。我們首先總結了如何將性能監控添加到 Sentry 和 SDK， 然后我們討論 identified issues(已確定的問題) 吸取的經驗教訓以及解決這些問題的舉措。
介紹
早在 2019 年初，Sentry 就開始嘗試向 SDK 添加跟蹤功能。 Python 和 JavaScript SDK 是設計和開發第一個概念的測試平臺。概念驗證于 2019 年 4 月 29 日 發布， 并于 2019 年 5 月 7 日交付給 Sentry。 Python 和 JavaScript 是顯而易見的選擇，因為它們允許我們試驗檢測 Sentry 自己的后端和前端。
- https://github.com/getsentry/sentry-python/pull/342
- https://github.com/getsentry/sentry-javascript/pull/1918
- https://github.com/getsentry/sentry-python/releases/tag/0.7.13
- https://github.com/getsentry/sentry/pull/12952
請注意，上述工作與 OpenCensus 和 OpenTracing 合并形成 OpenTelemetry 是同時代的。 Sentry 的 API 和 SDK 實現借鑒了 OpenTelemetry 1.0 之前版本的靈感，并結合了我們自己的想法。例如，我們的 Span 狀態列表與 2019 年底左右在 OpenTelemetry 規范中可以找到的匹配。
- https://medium.com/opentracing/a-roadmap-to-convergence-b074e5815289
- https://github.com/getsentry/relay/blob/55127c75d4eeebf787848a05a12150ee5c59acd9/relay-common/src/constants.rs#L179-L181
使用 API 后，性能監控支持隨后擴展到其他 SDK。Sentry 的性能監控 解決方案于 2020 年 7 月普遍可用。 OpenTelemetry 的跟蹤規范 1.0 版于 2021 年 2 月發布。
- https://blog.sentry.io/2020/07/14/see-slow-faster-with-performance-monitoring
- https://medium.com/opentelemetry/opentelemetry-specification-v1-0-0-tracing-edition-72dd08936978
我們最初的實現重用了我們現有的錯誤報告機制：
- Event type 擴展了新字段。這意味著我們可以節省時間并快速開始向 Sentry 發送事件，而不是設計和實現全新的攝取管道，這一次，不是 error，而是一種新的 transaction 事件類型。
- https://develop.sentry.dev/sdk/event-payloads/
- 由于我們只是發送一種新型事件，因此也重用了 SDK 傳輸層。
- 由于我們共享攝取管道(ingestion pipeline)，這意味著我們共享存儲以及發生在所有事件上的處理的許多部分。
我們的實現演變成明確強調 Transaction 和 Span 之間的區別。部分原因是重用 Event 接口的副作用。
Transaction 與客戶產生了良好的共鳴。他們允許突出顯示代碼中的重要工作塊，例如瀏覽器頁面加載或 http 服務器請求。客戶可以查看和瀏覽 transaction 列表，而在 transaction 中，span 為更細粒度的工作單元提供詳細的時間安排。
在下一節中，我們將討論當前模型的一些缺點。
已確定的問題
雖然統一 SDK 架構(hub、client、scope) 和 transaction ingestion 模型的重用有其優點，但經驗揭示了一些我們將其分為兩類的問題。
- https://develop.sentry.dev/sdk/unified-api/
第一組與 scope 傳播有關，本質上是確定 當前 scope 是什么的能力。用戶代碼中的手動檢測以及 SDK 集成中的自動檢測都需要此操作。
第二組是與用于將 transaction 數據從 SDK 發送到 Sentry 的 wire 格式相關的問題。
Scope 傳播
該問題由 getsentry/sentry-javascript#3751 跟蹤。
- https://github.com/getsentry/sentry-javascript/issues/3751
Unified SDK 架構 基本上是基于每個并發單元存在一個 hub，每個 hub 有一堆 client 和 scope 對。
- https://develop.sentry.dev/sdk/unified-api/
Client 保存配置并負責通過 transport 向 Sentry 發送數據，而 scope 保存附加到傳出事件(例如 tag 和 breadcrumb)的上下文數據。
每個 hub 都知道當前的 scope 是什么。它始終是堆棧頂部的 scope。困難的部分是 “per unit of concurrency(每單位并發)” 有一個 hub。
例如，JavaScript 是具有事件循環和異步代碼執行的單線程。沒有標準的方法來承載跨異步調用工作的上下文數據。因此，對于 JavaScript 瀏覽器應用程序，只有一個全局 hub 共享用于同步和異步代碼。
類似的情況出現在 Mobile SDK 上。用戶期望上下文數據(例如 tags、current user 是什么、 breadcrumbs 以及存儲在 scope 上的其他信息)可以從任何線程獲得和設置。因此，在這些 SDK 中，只有一個全局 hub。
在這兩種情況下，當 SDK 必須處理 reporting errors 時，一切都相對較好。隨著跟蹤 transaction 和 span 的額外責任，scope 變得不適合存儲當前的 span，因為它限制了并發 span 的存在。
對于瀏覽器 JavaScript，一個可能的解決方案是使用 Zone.js，Angular 框架的一部分。主要挑戰是它增加了包的大小，并且可能會無意中影響最終用戶應用程序，因為它對 JavaScript 運行時引擎的關鍵部分進行了猴子修補(monkey-patches)。
- https://github.com/angular/angular/blob/master/packages/zone.js/README.md
當我們嘗試為手動檢測創建更簡單的 API 時，scope 傳播問題變得尤為明顯。這個想法是公開一個 Sentry.trace 函數，該函數將隱式傳播 tracing 和 scope 數據， 并支持同步和異步代碼的深度嵌套。
舉個例子，假設有人想測量搜索 DOM 樹需要多長時間。Tracing(跟蹤) 此操作將如下所示：
- await Sentry.trace(
- {
- op: 'dom',
- description: 'Walk DOM Tree',
- },
- async () => await walkDomTree()
- );
使用 Sentry.trace 功能，用戶在添加計時數據時不必擔心保留對正確 transaction 或 span 的引用。用戶可以在 walkDomTree 函數中自由創建子 Span，Span 將在正確的層次結構中排序。
實際 trace 函數的實現相對簡單 (參見具有示例實現的 PR)。然而，了解異步代碼和全局集成中的當前 span 是一個尚未克服的挑戰。
- https://github.com/getsentry/sentry-javascript/pull/3697/files#diff-f5bf6e0cdf7709e5675fcdc3b4ff254dd68f3c9d1a399c8751e0fa1846fa85dbR158
以下兩個示例綜合了 scope 傳播問題。
無法確定當前 Span
考慮一些需要獲取對當前 span 的引用的自動檢測代碼，在這種情況下，手動 scope 傳播不可用。
- // SDK code
- function fetchWrapper(/* ... */) {
- /*
- ... some code omitted for simplicity ...
- */
- const parent = getCurrentHub().getScope().getSpan(); // <1>
- const span = parent.startChild({
- data: { type: 'fetch' },
- description: `${method} ${url}`,
- op: 'http.client',
- });
- try {
- // ...
- // return fetch(...);
- } finally {
- span.finish();
- }
- }
- window.fetch = fetchWrapper;
- // User code
- async function f1() {
- const hub = getCurrentHub();
- let t = hub.startTransaction({ name: 't1' });
- hub.getScope().setSpan(t);
- try {
- await fetch('https://example.com/f1');
- } finally {
- t.finish();
- }
- }
- async function f2() {
- const hub = getCurrentHub();
- let t = hub.startTransaction({ name: 't2' });
- hub.getScope().setSpan(t);
- try {
- await fetch('https://example.com/f2');
- } finally {
- t.finish();
- }
- }
- Promise.all([f1(), f2()]); // run f1 and f2 concurrently
在上面的例子中，幾個并發的 fetch 請求觸發了 fetchWrapper helper 的執行。行 <1> 必須能夠根據當前的執行流程觀察到不同的 span，導致如下兩個 span 樹：
- t1
- \
- |- http.client GET https://example.com/f1
- t2
- \
- |- http.client GET https://example.com/f2
這意味著，當 f1 運行時，parent 必須引用 t1，而當 f2 運行時，parent 必須是 t2。不幸的是，上面的所有代碼都在爭先恐后地更新和讀取單個 hub 實例，因此觀察到的 span 樹不是確定性的。例如，結果可能錯誤地為：
- t1
- t2
- \
- |- http.client GET https://example.com/f1
- |- http.client GET https://example.com/f2
作為無法正確確定當前 span 的副作用， fetch 集成的顯示實現(和其他)在JavaScript 瀏覽器 SDK 中選擇創建 flat transactions， 其中所有子 span 都是 transaction 的直接子代(而不是具有適當的多級樹結構)。
- https://github.com/getsentry/sentry-javascript/blob/61eda62ed5df5654f93e34a4848fc9ae3fcac0f7/packages/tracing/src/browser/request.ts#L169-L178
請注意，其他跟蹤庫也面臨同樣的挑戰。在 OpenTelemetry for JavaScript 中有幾個(在開放時)問題與確定父跨度和正確的上下文傳播(包括異步代碼)相關：
- 如果使用多個 TracerProvider 實例，則上下文泄漏 #1932
https://github.com/open-telemetry/opentelemetry-js/issues/1932
- 如何在不傳遞 parent 的情況下創建嵌套 span #1963
https://github.com/open-telemetry/opentelemetry-js/issues/1963
- 嵌套的子 span 沒有得到正確的父級 #1940
https://github.com/open-telemetry/opentelemetry-js/issues/1940
- OpenTracing shim 不會改變上下文 #2016
https://github.com/open-telemetry/opentelemetry-js/issues/2016
- Http Span 未鏈接/未設置父 Span #2333
https://github.com/open-telemetry/opentelemetry-js/issues/2333
相互沖突的數據傳播預期
每當我們添加前面討論過的 trace 函數，或者只是嘗試使用 Zones 解決 scope 傳播時，就會出現預期沖突。
當前的 span 與 tags、breadcrumbs 等一起存儲在 scope 中的事實使數據傳播變得混亂， 因為 scope 的某些部分旨在僅傳播到內部函數調用中(例如，tags)， 而其他人預計會傳播回調用者(例如，breadcrumbs)，尤其是在出現 error 時。
這是一個例子：
- function a() {
- trace((span, scope) => {
- scope.setTag('func', 'a');
- scope.setTag('id', '123');
- scope.addBreadcrumb('was in a');
- try {
- b();
- } catch(e) {
- // How to report the SpanID from the span in b?
- } finally {
- captureMessage('hello from a');
- // tags: {func: 'a', id: '123'}
- // breadcrumbs: ['was in a', 'was in b']
- }
- })
- }
- function b() {
- trace((span, scope) => {
- const fail = Math.random() > 0.5;
- scope.setTag('func', 'b');
- scope.setTag('fail', fail.toString());
- scope.addBreadcrumb('was in b');
- captureMessage('hello from b');
- // tags: {func: 'b', id: '123', fail: ?}
- // breadcrumbs: ['was in a', 'was in b']
- if (fail) {
- throw Error('b failed');
- }
- });
- }
在上面的示例中，如果 error 在調用堆棧中冒泡，我們希望能夠報告 error 發生在哪個 span(通過引用 SpanID)。我們希望有面包屑來描述發生的一切，無論哪個 Zones 正在執行， 我們希望在內部 Zone 中設置一個 tag 來覆蓋來自父 Zone 的同名 tag， 同時繼承來自父 Zone 的所有其他 tag。每個 Zone 都有自己的 "current span"。
所有這些不同的期望使得很難以一種可以理解的方式重用當前的 scope 概念、面包屑的記錄方式以及這些不同的概念如何相互作用。
最后，值得注意的是，在不破壞現有 SDK API 的情況下，重組 scope 管理的更改很可能無法完成。現有的 SDK 概念 — 如 hubs、scopes、breadcrumbs、user、tags 和 contexts — 都必須重新建模。
Span 攝取模型
考慮由以下 span 樹描述的跟蹤：
- F*
- ├─ B*
- │ ├─ B
- │ ├─ B
- │ ├─ B
- │ │ ├─ S*
- │ │ ├─ S*
- │ ├─ B
- │ ├─ B
- │ │ ├─ S*
- │ ├─ B
- │ ├─ B
- │ ├─ B
- │ │ ├─ S*
- where
- F: span created on frontend service
- B: span created on backend service
- S: span created on storage service
此跟蹤說明了 3 個被檢測的服務，當用戶單擊網頁上的按鈕 (F) 時，后端 (B) 執行一些工作，然后需要對存儲服務 (S) 進行多次查詢。位于給定服務入口點的 Span 標有 * 以表示它們是 transaction。
我們可以通過這個例子來比較和理解 Sentry 的 span 攝取模型與 OpenTelemetry 和其他類似跟蹤系統使用的模型之間的區別。
在 Sentry 的 span 攝取模型中，屬于 transaction 的所有 span 必須在單個請求中一起發送。這意味著在整個 B* transaction 期間，所有 B span 都必須保存在內存中，包括在下游服務(示例中的存儲服務)上花費的時間。
在 OpenTelemetry 的模型中，span 在完成時被一起批處理，并且一旦 a) 批次中有一定數量的 span 或 b) 過了一定的時間就會發送批次。在我們的示例中，這可能意味著前 3 個 B 跨度將一起批處理并發送， 而第一個 S* 事務仍在存儲服務中進行。隨后，其他 B span 將一起批處理并在完成時發送，直到最終 B* transaction span 也被發送。
雖然 transaction 作為將 span 組合在一起并探索 Sentry 中感興趣的操作的一種方式特別有用， 但它們目前存在的形式會帶來額外的認知負擔。 SDK 維護人員和最終用戶在編寫檢測代碼時都必須了解并在 transaction 或 span 之間進行選擇。
在當前的攝取模型中已經確定了接下來幾節中的問題，并且都與這種二分法有關。
事務的復雜 JSON 序列化
在 OpenTelemetry 的模型中， 所有跨度都遵循相同的邏輯格式。用戶和檢測庫可以通過將 key-value 屬性附加到任何 span 來為其提供更多含義。 wire 協議使用 span 列表將數據從一個系統發送到另一個系統。
- https://github.com/open-telemetry/opentelemetry-proto/blob/ebef7c999f4dea62b5b033e92a221411c49c0966/opentelemetry/proto/trace/v1/trace.proto#L56-L235
與 OpenTelemetry 不同，Sentry 的模型對兩種類型的 span 進行了嚴格區分：transaction span(通常稱為 transactions)和 regular span。
在內存中，transaction span 和 regular span 有一個區別：transaction span 有一個額外的屬性，即 transaction name。
但是，當序列化為 JSON 時，差異更大。 Sentry SDK 以直接類似于內存中的 span 的格式將常規 span 序列化為 JSON。相比之下，transaction span 的序列化需要將其 span 屬性映射到 Sentry Event (最初用于 report errors，擴展為專門用于 transactions 的新字段)，并將所有子 span 作為列表嵌入 Event 中。
Transaction Span 獲取 Event 屬性
當 transaction 從其內存表示轉換為 Event 時， 它會獲得更多無法分配給 regular span 的屬性， 例如 breadcrumbs, extra, contexts, event_id, fingerprint, release, environment, user 等。
生命周期鉤子
Sentry SDK 為 error 事件公開了一個 BeforeSend hook，允許用戶在將事件發送到 Sentry 之前修改和/或丟棄事件。
當引入新的 transaction 類型事件時，很快就決定此類事件不會通過 BeforeSend hook，主要有兩個原因：
- 防止用戶代碼依賴 transaction 的雙重形式(有時看起來像一個 span，有時像一個 event，如前幾節所述);
- 為了防止現有的 BeforeSend 函數在編寫時只考慮到 error 而干擾 transaction，無論是意外地改變它們、完全丟棄它們，還是導致一些其他意想不到的副作用。
然而，也很明顯需要某種形式的 lifecycle hook，以允許用戶執行諸如更新 transaction 名稱之類的操作。
我們最終達成了中間立場，即通過使用 EventProcessor(一種更通用的 BeforeSend 形式)來允許更改/丟棄 transaction 事件。這通過在數據離開 SDK 之前讓用戶立即訪問他們的數據來解決問題，但它也有缺點，它比 BeforeSend 使用起來更復雜，并且還暴露了從未打算泄漏的 transaction 二元性。
相比之下，在 OpenTelemetry 中，span 通過 span processor，這是兩個生命周期鉤子：一個是在 span 開始時，一個是在它結束時。
嵌套事務
Sentry 的攝取模型不是為服務中的嵌套 transaction 而設計的。Transaction 旨在標記服務轉換。
在實踐中，SDK 無法防止 transaction 嵌套。最終結果可能會讓用戶感到驚訝，因為每筆 transaction 都會開始一棵新樹。關聯這些樹的唯一方法是通過 trace_id。
Sentry 的計費模型是針對每個事件的，無論是 error 事件還是 transaction 事件。這意味著 transaction 中的 transaction 會生成兩個可計費事件。
在 SDK 中，在 transaction 中進行 transaction 將導致內部 span 被圍繞它們的最內層 transaction “吞噬”。在這些情況下，創建 span 的代碼只會將它們添加到兩個 transaction 之一，從而導致另一個 transaction 中的檢測間隙。
Sentry 的 UI 并非旨在以有用的方式處理嵌套 transaction。當查看任何一個 transaction 時，就好像 transaction 中的所有其他 transaction 都不存在(樹視圖上沒有直接表示其他 transaction)。有一個 trace view 功能來可視化共享一個 trace_id 的所有 transaction， 但 trace view 僅通過顯示 transaction 而不是子 span 來提供跟蹤的概述。如果不先訪問某個 transaction，就無法導航到 trace view。
對于這種情況(偽代碼)，用戶對 UI 中的期望也存在混淆：
- # if do_a_database_query returns 10 results, is the user
- # - seeing 11 transactions in the UI?
- # - billed for 11 transactions?
- # - see spans within create_thumbnail in the innermost transaction only?
- with transaction("index-page"):
- results = do_a_database_query()
- for result in results:
- if result["needs_thumbnail"]:
- with transaction("create-thumbnail", {"resource": result["id"]}):
- create_thumbnail(result)
跨度不能存在于事務之外
Sentry 的追蹤體驗完全圍繞著存在于 transaction 中的 trace 部分。這意味著數據不能存在于 transaction 之外，即使它存在于 trace 中。
如果 SDK 沒有進行 transaction，則由 instrumentation 創建的 regular span 將完全丟失。也就是說，這對 Web server 來說不是什么問題，因為自動檢測的 transaction 隨著每個傳入請求開始和結束。
Transaction 的要求在前端(瀏覽器、移動和桌面應用程序)上尤其具有挑戰性， 因為在這些情況下，自動檢測的 transaction 不太可靠地捕獲所有 span，因為它們在自動完成之前只持續有限的時間。
在 trace 以僅作為 span 而不是 transaction 進行檢測的操作開始的情況下，會出現另一個問題。在我們的 示例跟蹤中，產生 trace 的第一個 span 是由于單擊按鈕。如果按鈕點擊 F* 被檢測為常規的 span 而不是 transaction，則很可能不會捕獲來自前端的數據。然而，仍會捕獲 B 和 S span，導致不完整的蹤跡。
在 Sentry 的模型中，如果一個 span 不是一個 transaction 并且沒有作為 transaction 的祖先 span，那么該 span 將不會被攝取。反過來，這意味著在很多情況下，跟蹤丟失了有助于調試問題的關鍵信息，特別是在前端，transaction 需要在某個時刻結束但執行可能會繼續。
自動和手動檢測面臨著決定是開始 span 還是 transaction 的挑戰，考慮到以下因素，決定尤其困難：
如果沒有 transaction，則 span 丟失。
如果已經存在 transaction，則存在嵌套事務問題。
缺少 Web Vitals 測量
Sentry 的瀏覽器工具收集 Web Vitals 測量值。但是，因為這些測量值是使用自動檢測的 transaction 作為載體發送到 Sentry 的，所以在自動 transaction 完成后由瀏覽器提供的測量值將丟失。
這會導致 transaction 丟失一些 Web Vitals 或對 LCP 等指標進行非最終測量。
前端事務持續時間不可靠
因為所有的數據都必須在一個 transaction 中。Sentry 的瀏覽器 SDK 為每個頁面加載和每個導航創建一個 transaction。這些 transaction 必須在某個時間結束。
如果在 transaction 完成之前關閉瀏覽器選項卡并將其發送到 Sentry，則所有收集的數據都會丟失。因此，SDK 需要平衡丟失所有數據的風險與收集不完整和可能不準確的數據的風險。
在觀察到最后一個活動(例如傳出的 HTTP 請求)后空閑了一段時間后，Transaction 就完成了。這意味著頁面加載或導航 transaction 的持續時間是一個相當隨意的值，不一定能改進或與其他事務相比，因為它不能準確代表任何具體和可理解的過程的持續時間。
我們通過將 LCP Web Vital 作為瀏覽器的默認性能指標來應對這一限制。但是，如上所述，LCP 值可能會在最終確定之前發送，因此這不是理想的解決方案。
內存緩沖影響服務器
如前所述，當前的攝取模型需要 Sentry SDK 來觀察內存中的完整 span 樹。以恒定的并發 transaction 流運行的應用程序將需要大量的系統資源來收集和處理跟蹤數據。Web 服務器是出現此問題的典型案例。
這意味著記錄 100% 的 span 和 100% 的 transaction 對于許多服務器端應用程序來說是不可行的，因為所產生的開銷太高了。
無法批處理事務
Sentry 的攝取模型不支持一次攝取多個事件。特別是，SDK 不能將多個 transaction 批處理為一個請求。
因此，當多筆 transaction 幾乎同時完成時，SDK 需要為每個 transaction 發出單獨的請求。這種行為在最好的情況下是非常低效的，在最壞的情況下是對資源(如網絡帶寬和CPU周期)的嚴重且有問題的消耗。
兼容性
Transaction Span 的特殊處理與 OpenTelemetry 不兼容。使用 OpenTelemetry SDK 檢測現有應用程序的用戶無法輕松使用 Sentry 來獲取和分析他們的數據。
Sentry 確實為 OpenTelemetry Collector 提供了一個 Sentry Exporter，但是，由于當前的攝取模型，Sentry Exporter 有一個主要的正確性限制。
https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/sentryexporter#known-limitations
總結
通過在 Sentry 中構建當前的跟蹤實現，我們學到了很多。本文檔試圖捕捉許多已知的限制，以作為未來改進的基礎。
追蹤是一個復雜的主題，馴服這種復雜性并非易事。
第一組中的問題 - 與 scope propagation(作用域傳播) 相關的問題 - 是 SDK 及其設計方式獨有的問題。解決這些問題將需要對所有 SDK 進行內部架構更改，包括重新設計面包屑等舊功能， 但進行此類更改是實現簡單易用的 tracing helper(如可在任何上下文中工作并捕獲準確可靠的性能數據的 trace 函數)的先決條件。請注意，此類更改幾乎肯定意味著發布新的主要 SDK 版本，這會破壞與現有版本的兼容性。
第二組中的問題 - 與 span ingestion model(跨度攝取模型) 相關的問題要復雜得多，因為為解決這些問題所做的任何更改都會影響產品的更多部分，并且需要多個團隊的協調努力。
盡管如此，對 ingestion model 進行更改將對產品產生不可估量的積極影響，因為這樣做會提高效率，使我們能夠收集更多數據，并減少 instrumentation 的負擔。
