Sentry(v20.12.1) K8S 雲原生架構探索，SENTRY FOR JAVASCRIPT SDK 配置詳解

為少發表於2021-01-12
K8S架構JavaScript

系列

  1. Sentry-Go SDK 中文實踐指南
  2. 一起來刷 Sentry For Go 官方文件之 Enriching Events
  3. Snuba：Sentry 新的搜尋基礎設施(基於 ClickHouse 之上)
  4. Sentry 10 K8S 雲原生架構探索，Vue App 1 分鐘快速接入
  5. Sentry(v20.12.1) K8S雲原生架構探索,玩轉前/後端監控與事件日誌大資料分析,高效能高可用+可擴充套件可伸縮叢集部署
  6. Sentry(v20.12.1) K8S 雲原生架構探索，Sentry JavaScript SDK 三種安裝載入方式

Basic Options

SDK 可以使用多種選項進行配置。這些選項在 SDK 中基本上是標準化的，但在更好地適應平臺特性方面存在一些差異。選項是在 SDK 首次初始化時設定的。

選項作為物件傳遞給 init() 函式：

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  maxBreadcrumbs: 50,
  debug: true,
});

Common Options

跨 SDK 的常見選項列表。這些功能在所有 SDK 中或多或少都是一樣的，但是為了更好地支援平臺，會存在一些細微的差異。可以從環境變數或你的 ~/.sentryclirc 檔案中自動的讀取的選項(SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_RELEASE)。有關更多資訊，請參見Working with Projects。

dsn

DSN 告訴 SDK 將事件傳送到哪裡。如果沒有提供這個值，SDK 將嘗試從 SENTRY_DSN 環境變數中讀取它。如果這個變數也不存在，SDK 就不會傳送任何事件。

在沒有程式環境（如瀏覽器）的執行時中，fallback 不會應用。

debug

開啟或關閉除錯模式。如果啟用了除錯，如果傳送事件時出現問題，SDK 將嘗試列印出有用的除錯資訊。預設值總是 false。一般不建議在生產環境中開啟它，儘管開啟 debug 模式不會引起任何安全問題。

release

設定 release（發行版）。某些 SDK 會嘗試自動配置 release，但是最好手動設定 release，以確保該 release 與您的 deploy integrations 或 source map uploads 同步。版本名稱是字串，但是 Sentry 會檢測到某些格式，並且它們的呈現方式可能有所不同。在 releases 文件中瞭解有關如何傳送 release 資料的更多資訊，以便 Sentry 可以告訴您 release 之間的迴歸並確定潛在的來源。

預設情況下，SDK 會嘗試從環境變數 SENTRY_RELEASE 中讀取該值（在瀏覽器 SDK 中，將從 window.SENTRY_RELEASE 中讀取該值，如果可用）。

environment

設定環境。此字串為自由形式，預設情況下不設定。一個 release 可以與多個環境相關聯，以便在 UI 中將它們分開（可以考慮staging 與 prod 或類似的方式）。

預設情況下，SDK 將嘗試從 SENTRY_ENVIRONMENT 環境變數中讀取該值（瀏覽器 SDK 除外）。

sampleRate

配置錯誤事件的取樣率，範圍為 0.0 到 1.0。預設值為 1.0，表示傳送了 100％ 的錯誤事件。如果設定為 0.1，則僅傳送 10％ 的錯誤事件。事件是隨機選擇的。

maxBreadcrumbs

這個變數控制應該捕獲的麵包屑( breadcrumbs )總數。預設值為 100。

attachStacktrace

當啟用時，堆疊跟蹤將自動附加到所有記錄的訊息。堆疊跟蹤總是附加到異常；然而，當設定此選項時，堆疊跟蹤也會與訊息一起傳送。例如，該選項意味著堆疊跟蹤顯示在所有日誌訊息的旁邊。

該選項預設為 off。

對於有堆疊跟蹤和沒有堆疊跟蹤的事件，Sentry中的分組是不同的。結果，在為某些事件啟用或禁用此 flag 時，您將獲得新的組。

sendDefaultPii

如果啟用此 flag，則某些個人識別資訊（PII）將由 active integrations 新增。預設情況下，不傳送此類資料。如果可能的話，我們建議預設情況下啟用此功能以傳送所有此類資料，並使用管理 敏感資料 的功能手動刪除您不想傳送的內容。

denyUrls

與不應該傳送到 Sentry 的錯誤 URL 相匹配的字串或正規表示式模式列表。預設情況下，將傳送所有錯誤。這是一個 “contains(包含)” 匹配整個檔案 URL。因此，如果你新增 foo.com，它也會匹配 https://bar.com/myfile/foo.com。預設情況下，將傳送所有錯誤。

allowUrls

匹配錯誤 URL 的字串列表或正規表示式模式的遺留別名，這些錯誤 URL 應該專門傳送給 Sentry。預設情況下，將傳送所有錯誤。這是一個 “contains(包含)” 匹配整個檔案 URL。因此，如果您將 foo.com 新增到它，它也將匹配 https://bar.com/myfile/foo.com。預設情況下，所有錯誤將被髮送。

autoSessionTracking

當設定為 true 時，SDK 將傳送 session 事件給 Sentry。所有瀏覽器 SDK 都支援這一點，每個頁面載入都向 Sentry 傳送一個 session。

normalizeDepth

Sentry SDK 將任何上下文資料標準化到給定深度。任何包含比其更深的結構的資料的 key 都將被修剪並使用其型別（[Object] 或 [Array]）進行標記，而無需進一步進行操作。預設情況下，walking 的深度為 3 級。

Integration Configuration

對於許多平臺，SDK 整合可以與之一起配置。在一些平臺上，這是 init() 呼叫的一部分，而在另一些平臺上，則應用不同的模式。

integrations

在一些 SDK 中，在庫初始化時通過這個引數配置整合。要了解更多資訊，請參閱我們的文件瞭解特定的整合。

defaultIntegrations

這可以用來禁用預設新增的整合。當設定為 false 時，不會新增預設的整合。

Hooks

這些選項可用於以各種方式 hook SDK，以定製事件的報告。

beforeSend

使用 SDK-specific 事件物件呼叫此函式，可以返回修改後的事件物件或不返回任何內容，以跳過報告事件。例如，這可以用於在傳送前手動剝離 PII。

beforeBreadcrumb

在將麵包屑(breadcrumb)新增到作用域(scope)之前，使用 SDK 特定的麵包屑(SDK-specific breadcrumb)物件呼叫此函式。當該函式未返回任何內容時，將刪除 breadcrumb。要傳遞 breadcrumb，請返回第一個引數，其中包含 breadcrumb 物件。回撥通常會獲得第二個引數（稱為“hint”），該引數包含建立 breadcrumb 的原始物件，以進一步自定義麵包屑的外觀。

Transport Options

Transports 被用來傳送事件到 Sentry。可以在某種程度上對傳輸進行定製，以更好地支援高度特定的部署。

transport

切換出用於傳送事件的 transport。如何運作取決於 SDK。例如，它可以用於捕獲事件以進行單元測試，或通過需要代理身份驗證的更復雜的設定傳送事件。

Tracing Options

tracesSampleRate

0 到 1 之間的數字，控制給定事務傳送到哨兵的概率百分比。(0表示0%，1表示100%)同樣適用於應用程式中建立的所有事務。必須定義這個或 tracesSampler 以啟用跟蹤。

tracesSampler

一個函式負責確定一個給定的事務將被髮送到 Sentry 的概率百分比。它將自動被傳遞有關事務和建立它的上下文的資訊，並且必須返回一個介於 0(被髮送的概率為0%)和 1(被髮送的概率為100%) 之間的數字。還可以用於過濾事務，對不需要的事務返回0。必須定義這個或 tracesSampleRate 來啟用跟蹤。

Releases & Health

一個 release 是部署到環境中的程式碼版本。當您向 Sentry 提供有關 release 的資訊時，您可以：

  • 確定新版本中引入的問題和迴歸
  • 預測哪個提交引起了問題，誰可能負責
  • 通過在提交訊息中包含問題編號來解決問題
  • 在部署程式碼時接收電子郵件通知

此外，releases 還用於將 source maps 應用到壓縮的 JavaScript 中，以檢視原始的、未轉換的原始碼。

Bind the Version

在配置客戶端 SDK 時包含一個 release ID(通常稱為 “version” )。這個 ID 通常是一個 git SHA 或自定義版本號。

release 名稱不能：

  • 包含換行符或空格
  • 使用正斜槓(/)，反斜槓(\)，句點(.)，或雙句點(..)
  • 超過 200 個字元

每個組織的釋出是全域性的；在它們前面加上一些特定於專案(project-specific)的東西，以方便區分。

Sentry.init({
  release: "my-project-name@2.3.12",
});

在 Node/npm 環境中使用 JavaScript 進行此操作的常見方法是使用process.env.npm_package_version，如下所示：

Sentry.init({
  release: "my-project-name@" + process.env.npm_package_version,
});

如何使版本對程式碼可用由您決定。例如，您可以使用在構建過程中設定的環境變數。

這會用 release 值標記每個事件。我們建議您在部署新版本之前先告訴 Sentry，因為這將釋放一些新功能，如關於 releases 的文件中所述。但是，如果您不這樣做，Sentry 會在第一次看到具有該 release ID 的事件時自動在系統中建立一個 release 實體。

配置完 SDK 後，您可以安裝 repository integration（儲存庫整合）或手動為 Sentry 提供自己的提交後設資料。閱讀有關設定發行版的文件，以獲取有關整合，關聯提交以及在部署發行版時告知 Sentry 的更多資訊。

Release Health

通過觀察使用者採用率，應用程式使用率，crashes 百分比和 session data 來監視 health of releases。Release health 將提供與使用者體驗相關的崩潰和錯誤影響的見解，並通過 release 詳細資訊，圖表和過濾器揭示每個新問題的趨勢。

初始化 SDK 後，SDK 將自動管理會話的開始和結束。

Sentry.init({
  autoSessionTracking: true
});

Environments

Sentry 收到帶有 environment 標籤的事件時，會自動建立環境。環境區分大小寫。環境名稱不能包含換行符，空格或正斜槓，字串 "None" 或超過 64 個字元。您不能刪除環境，但是可以隱藏它們。

Sentry.init({
  environment: "production",
});

Environments 可幫助您在 sentry.io 的“問題詳細資訊”頁面中更好地過濾 issues，releases 和 user feedback，您可以在 documentation that covers using environments 中瞭解更多資訊。

Filtering and Sampling Events

將 Sentry 新增到你的應用中能夠為你提供大量關於錯誤和效能的非常有價值的資訊。大量的資訊是有益的——只要這些資訊是正確的，數量合理。

Sentry SDK 提供了多個配置選項來幫助您控制這一點，使您既可以過濾掉不需要的事件，又可以從中獲取代表性的樣本。

Note: Sentry UI 還提供了使用 Inbound Filters 篩選事件的方法。 不過，我們建議您在客戶端級別進行過濾，因為這樣可以消除傳送您實際上不需要的事件的開銷。

Filtering Error Events

使用 beforeSend 回撥方法並配置，啟用或禁用 integrations，將您的 SDK 配置為過濾錯誤事件。

Using beforeSend

所有 Sentry SDK 都支援 beforeSend 回撥方法。在事件傳送到伺服器之前立即呼叫 beforeSend，因此這是您可以編輯其資料的最終位置。它接收事件物件作為引數，因此您可以根據自定義邏輯和事件上可用的資料，使用它來修改事件的資料或完全刪除（通過返回 null）。

Sentry.init({
  // ...

  beforeSend(event, hint) {
    const error = hint.originalException;
    if (
      error &&
      error.message &&
      error.message.match(/database unavailable/i)
    ) {
      event.fingerprint = ["database-unavailable"];
    }
    return event;
  },
});

還要注意，麵包屑(breadcrumbs)可以過濾，如 our Breadcrumbs documentation 所述。

Event Hints

before-send 回撥函式同時傳遞了 event 和第二個引數 hint，它包含一個或多個提示。

通常，hint 儲存原始異常，以便提取額外資料或影響分組。在本例中，如果捕獲了某種型別的異常，則強制將指紋(fingerprint)轉換為普通值：

Sentry.init({
  // ...

  beforeSend(event, hint) {
    const error = hint.originalException;
    if (
      error &&
      error.message &&
      error.message.match(/database unavailable/i)
    ) {
      event.fingerprint = ["database-unavailable"];
    }
    return event;
  },
});

當 SDK 為傳輸建立一個事件或麵包屑(breadcrumb)時，該傳輸通常是從某種源物件建立的。例如，錯誤事件通常是從日誌記錄或異常例項建立的。為了更好地定製，SDK 將這些物件傳送給特定的回撥( beforeSend、beforeBreadcrumb 或 SDK 中的事件處理器系統)。

Using Hints

  1. beforeSend / beforeBreadcrumb
  2. eventProcessors

Event 和 breadcrumb 的 hints 是包含用於將事件或麵包屑組合在一起的各種資訊的物件。通常，hints 保留原始異常，以便可以提取其他資料或影響分組。

對於事件，例如 event_id，originalException，syntheticException（在內部用於生成更清晰的堆疊跟蹤），以及您附加的任何其他任意的 data。

對於麵包屑，hints 的使用取決於實現。對於 XHR 請求，hint 包含 xhr 物件本身。對於使用者互動，hint 包含 DOM 元素和事件名稱等。

在此示例中，如果捕獲到某種型別的異常，則將指紋(fingerprint)強制為一個公共值：

Sentry.init({
  // ...

  beforeSend(event, hint) {
    const error = hint.originalException;
    if (
      error &&
      error.message &&
      error.message.match(/database unavailable/i)
    ) {
      event.fingerprint = ["database-unavailable"];
    }
    return event;
  },
});

Hints for Events

originalException

  • 導致 Sentry SDK 建立事件的原始異常。這對於更改 Sentry SDK 對事件進行分組或提取額外資訊的方式非常有用。

syntheticException

  • 當引發字串或非錯誤(non-error)物件時，Sentry 將建立綜合異常，以便您可以獲得基本的堆疊跟蹤。此異常儲存在此處以進一步提取資料。

Hints for Breadcrumbs

event

  • 對於通過瀏覽器事件建立的麵包屑，Sentry SDK 通常將事件作為 hint 提供給面包屑。 例如，這可用於將目標 DOM 元素中的資料提取到麵包屑中。

level / input

  • 對於從控制檯日誌擷取建立的麵包屑。這將保留原始控制檯日誌級別和日誌功能的原始輸入資料。

response / input

  • 用於從 HTTP 請求建立的麵包屑。這儲存了響應物件（來自 fetch API）和 fetch 函式的輸入引數。

request / response / event

  • 用於從 HTTP 請求建立的麵包屑。它儲存了請求和響應物件（來自節點 HTTP API）以及節點事件（response 或 error）。

xhr

  • 對於通過舊版 XMLHttpRequest API 通過 HTTP 請求建立的麵包屑。這將保留原始的 xhr 物件。

Decluttering Sentry

您可以構造允許的域列表，這可能會引發可接受的異常。例如，如果您的指令碼是從 cdn.example.com 載入的，而您的站點是 example.com，則可以將 allowUrls 設定為：

如果您想永遠阻止特定的 URL，也可以使用 denyUrls。

在 5.17.0 版之前，allowUrls 和 denyUrls 分別稱為 whitelistUrls 和 blacklistUrls。出於向後相容的原因，仍支援這些選項，但是在 6.0 版中將刪除它們。有關更多資訊，請參見我們的 Inclusive Language Policy。

此外，我們的社群已為日常工作（例如 Facebook，Chrome 擴充套件程式等）編制了常見的忽略規則列表。建議您檢查一下這些內容，看看它們是否適用於您，這很有用。Here is the original gist。這不是我們 SDK 的預設值；這只是一個廣泛示例的亮點。

Sentry.init({
  ignoreErrors: [
    // Random plugins/extensions
    "top.GLOBALS",
    // See: http://blog.errorception.com/2012/03/tale-of-unfindable-js-error.html
    "originalCreateNotification",
    "canvas.contentDocument",
    "MyApp_RemoveAllHighlights",
    "http://tt.epicplay.com",
    "Can't find variable: ZiteReader",
    "jigsaw is not defined",
    "ComboSearch is not defined",
    "http://loading.retry.widdit.com/",
    "atomicFindClose",
    // Facebook borked
    "fb_xd_fragment",
    // ISP "optimizing" proxy - `Cache-Control: no-transform` seems to
    // reduce this. (thanks @acdha)
    // See http://stackoverflow.com/questions/4113268
    "bmi_SafeAddOnload",
    "EBCallBackMessageReceived",
    // See http://toolbar.conduit.com/Developer/HtmlAndGadget/Methods/JSInjection.aspx
    "conduitPage",
  ],
  denyUrls: [
    // Facebook flakiness
    /graph\.facebook\.com/i,
    // Facebook blocked
    /connect\.facebook\.net\/en_US\/all\.js/i,
    // Woopra flakiness
    /eatdifferent\.com\.woopra-ns\.com/i,
    /static\.woopra\.com\/js\/woopra\.js/i,
    // Chrome extensions
    /extensions\//i,
    /^chrome:\/\//i,
    // Other plugins
    /127\.0\.0\.1:4001\/isrunning/i, // Cacaoweb
    /webappstoolbarba\.texthelp\.com\//i,
    /metrics\.itunes\.apple\.com\.edgesuite\.net\//i,
  ],
});

Sampling Error Events

要將錯誤的代表性樣本傳送到 Sentry，請在 SDK 配置中將 sampleRate 選項設定為介於 0（已傳送錯誤的0％）和 1（已傳送錯誤的100％）之間的數字。這是一個靜態比率，將同樣適用於所有錯誤。例如，要抽樣25％的錯誤：

Sentry.init({ sampleRate: 0.25 });

Note: 誤差取樣率不是動態的。更改它需要重新部署。此外，設定 SDK 取樣率會限制事件源的可見性。為專案設定速率限制（僅在高 volume 時才丟棄事件）可能更適合您的需求。

Filtering Transaction Events

為了防止某些事務被報告給 Sentry，可以使用 tracesSampler 配置選項，該選項允許您提供一個函式來評估當前事務，並在它不是您想要的事務時刪除它。(它還允許您以不同的速率對不同的事務進行取樣。)

Note: tracesSampler 和 tracesSampleRate 配置選項是互斥的。如果您定義了一個 tracesSampler 來過濾掉某些事務，那麼您還必須通過返回您希望它們被取樣的速率來處理未過濾的事務。

最簡單的形式（僅用於過濾）如下所示：

Sentry.init({
  // ...

  tracesSampler: samplingContext => {
    if ("...") {
      // Drop this transaction, by setting its sample rate to 0%
      return 0;
    } else {
      // Default sample rate for all others (replaces tracesSampleRate)
      return 0.1;
    }
  };
});

要了解有關 tracesSampler 選項的更多資訊，請參閱 SDK 的 performance docs。

Sampling Transaction Events

對於 Sentry 的效能監控，我們建議抽樣您的資料，有兩個原因。首先，儘管捕獲單個跟蹤涉及的開銷最小，但捕獲每個頁面載入或每個 API 請求的跟蹤都有可能向系統新增不希望的負載。其次，啟用抽樣允許您更好地管理髮送到 Sentry 的事件數量，這樣您就可以根據組織的需要調整您的數量。

在選擇取樣率時，目標不是收集太多資料，而是收集足夠的資料，以便得出有意義的結論。如果您不確定選擇什麼速率，那麼從一個較低的值開始，隨著您對流量模式和 volume 瞭解的更多，逐漸增加它，直到您找到了一個平衡效能和流量與資料準確性的速率。

要對事務進行取樣，可以將 tracesSampleRate 配置選項設定為 0(傳送的事務的 0%)到 1(傳送的事務的100%)之間的一個數字，或者將 tracesSampler 選項設定為一個函式，該函式將返回這個數字，該數字隨事務的不同而變化。

例如，將 tracesSampleRate 選項設定為 0.2 將導致 SDK 只傳送 20% 的可能事務事件：

Sentry.init({
  // ...

  tracesSampleRate: 0.2,
});

或者，你可以提供一個 tracesSampler 函式，以不同的速率取樣不同的事務:

Sentry.init({
  // ...

  tracesSampler: samplingContext => {
    // Examine provided context data (including parent decision, if any) along
    // with anything in the global namespace to compute the sample rate or
    // sampling decision for this transaction

    if ("...") {
      // These are important - take a big sample
      return 0.5;
    } else if ("...") {
      // These are less important or happen much more frequently - only take 1%
      return 0.01;
    } else if ("...") {
      // These aren't something worth tracking - drop all transactions like this
      return 0;
    } else {
      // Default sample rate
      return 0.1;
    }
  };
});

要了解更多關於 tracesSampler 選項的資訊，請檢視 SDK 的 performance docs。

Shutdown and Draining

大多數 SDK 的預設行為是在後臺通過網路非同步傳送事件。這意味著如果應用程式意外關閉，某些事件可能會丟失。SDK 提供了應對這種情況的機制。

close 方法可選地接受一個以毫秒為單位的超時，並返回一個 promise，當所有未決事件重新整理或超時開始時將 resolve 該 promise。

Sentry.close(2000).then(function() {
  // perform something after close
});

呼叫 close 後，當前客戶端將不能再使用。在關閉應用程式之前只呼叫 close 是很重要的。

或者，在保持客戶端啟用狀態以繼續使用的同時，flush 方法會清空事件佇列。

Default Integrations

所有 Sentry 的 SDK 都提供了整合（integrations），擴充套件了 SDK 的功能。

預設情況下，系統整合（System integrations）是啟用的，以整合到標準庫或直譯器本身中。它們已記錄在案，因此您既可以知道它們在做什麼，也可以在它們引起問題時禁用它們。

Enabled by Default

InboundFilters

Import name: Sentry.Integrations.InboundFilters

通過這種整合，您可以根據給定異常中的型別，訊息或 URL 忽略特定錯誤。

預設情況下，它忽略以 Script error 或 Javascript error: Script error 開頭的錯誤。

要配置這個整合，直接使用 ignoreErrors，denyUrls，和 allowUrls SDK 選項。請記住，denyURL 和 allowURL 只對捕獲的異常有效，而不是原始訊息事件。

FunctionToString

Import name: Sentry.Integrations.FunctionToString

這種整合使 SDK 可以提供原始的函式和方法名稱，即使我們的錯誤或麵包屑處理程式包裝了它們也是如此。

TryCatch

Import name: Sentry.Integrations.TryCatch

這個整合封裝了原生 time 和 events APIs (setTimeout, setInterval, requestAnimationFrame, addEventListener/removeEventListener) 在 try/catch 塊處理 async 異常。

Breadcrumbs

Import name: Sentry.Integrations.Breadcrumbs

這種整合封裝了原生 API 以捕獲麵包屑。預設情況下，Sentry SDK 封裝了所有 API。

Available options:

{ beacon: boolean; // Log HTTP requests done with the Beacon API
  console: boolean; // Log calls to `console.log`, `console.debug`, etc
  dom: boolean; // Log all click and keypress events
  fetch: boolean; // Log HTTP requests done with the Fetch API
  history: boolean; // Log calls to `history.pushState` and friends
  sentry: boolean; // Log whenever we send an event to the server
  xhr: boolean; // Log HTTP requests done with the XHR API
}

GlobalHandlers

Import name: Sentry.Integrations.GlobalHandlers

這個整合附加了全域性處理程式來捕獲未捕獲的 exceptions 和未處理的 rejections。

可用的選項：

{
  onerror: boolean;
  onunhandledrejection: boolean;
}

LinkedErrors

Import name: Sentry.Integrations.LinkedErrors

此整合允許您配置連結錯誤。它們將被遞迴地讀取到指定的限制，並由特定的 key 執行查詢。預設情況下，Sentry SDK 將限制設定為 5，使用的鍵 key 是 cause。

可用的選項：

{
  key: string;
  limit: number;
}

UserAgent

Import name: Sentry.Integrations.UserAgent

這種整合將 user-agent 資訊附加到事件中，這使我們能夠正確地分類並使用特定的作業系統(OS)，瀏覽器(browser)和版本(version)資訊對其進行標記。

Modifying System Integrations

要禁用系統整合，在呼叫 init() 時設定 defaultIntegrations: false。

要覆蓋它們的設定，請提供一個帶有配置到 integrations 選項的新例項。例如，關閉瀏覽器捕獲的控制檯呼叫：integrations: [new Sentry.Integrations.Breadcrumbs({ console: false })]。

Removing an Integration

這個例子移除了為事件新增麵包屑的預設啟用的整合：

Sentry.init({
  // ...

  integrations: function(integrations) {
    // integrations will be all default integrations
    return integrations.filter(function(integration) {
      return integration.name !== "Breadcrumbs";
    });
  },
});

Pluggable Integrations

這些可插拔的整合是為特定的應用程式和/或框架增加功能的程式碼片段。我們對它們進行了記錄，這樣您就可以看到它們的功能，並且可以啟用它們。

How to Enable

安裝 @sentry/integrations 包，並提供一個帶有你配置到 integrations 選項的新例項。載入 SDK 之後，包括外掛。

示例：

import * as Sentry from "@sentry/browser";
import { ReportingObserver as ReportingObserverIntegration } from "@sentry/integrations";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [new ReportingObserverIntegration()],
});

ExtraErrorData

Import name: Sentry.Integrations.ExtraErrorData

這個整合從錯誤物件中提取所有非原生(non-native)屬性，並將它們作為 extra 資料附加到事件中。

可用的選項：

{
  // limit of how deep the object serializer should go. Anything deeper than limit will
  // be replaced with standard Node.js REPL notation of [Object], [Array], [Function] or
  // a primitive value. Defaults to 3.
  depth: number;
}

CaptureConsole

Import name: Sentry.Integrations.CaptureConsole

這種整合捕獲所有的 Console API 呼叫，並使用 captureMessage 呼叫將它們重定向到 Sentry。然後，它會重新觸發以保留預設的原生行為。

{
  // array of methods that should be captured
  // defaults to ['log', 'info', 'warn', 'error', 'debug', 'assert']
  levels: string[];
}

Dedupe

Import name: Sentry.Integrations.Dedupe

這種整合可以對某些事件進行重複資料刪除。如果您收到許多重複的錯誤，可能會有所幫助。請注意，Sentry 將僅比較堆疊跟蹤和指紋。

Debug

Import name: Sentry.Integrations.Debug

通過這種整合，您可以檢查已處理事件的內容，該事件將被傳遞到 beforeSend 並有效地傳送到 Sentry SDK。無論何時註冊，它都將始終作為最後的整合執行。

可用的選項：

{
  // trigger DevTools debugger instead of using console.log
  debugger: boolean;

  // stringify event before passing it to console.log
  stringify: boolean;
}

RewriteFrames

Import name: Sentry.Integrations.RewriteFrames

這種整合允許您對堆疊跟蹤的每一幀應用轉換。在 streamlined 場景中，可以使用它來更改檔案框架的名稱，或者向它提供一個迭代函式來應用任何任意的轉換。

在 Windows 機器上，你必須使用 Unix 路徑並跳過 root 選項中的卷(volume)號來啟用。例如，C:\\Program Files\\Apache\\www 不能工作，但是，/Program Files/Apache/www 可以。

可用的選項：

{
  // root path that will be appended to the basename of the current frame's url
  root: string;

  // function that takes the frame, applies a transformation, and returns it
  iteratee: (frame) => frame;
}

ReportingObserver

Import name: Sentry.Integrations.ReportingObserver

此整合與 ReportingObserver API 掛鉤，並將捕獲的事件傳送到 Sentry。可以將其配置為僅處理特定的問題型別。

可用的選項：

{
  types: <'crash'|'deprecation'|'intervention'>[];
}

Custom Integrations

使用以下格式在 JavaScript 中新增一個自定義整合：

// All integration that come with an SDK can be found on Sentry.Integrations object
// Custom integration must conform Integration interface: https://github.com/getsentry/sentry-javascript/blob/master/packages/types/src/integration.ts

Sentry.init({
  // ...

  integrations: [new MyAwesomeIntegration()],
});

rrweb: Session Replays

Sentry 提供了與 rrweb 的 proof-of-concept（概念驗證） 整合，該工具包用於記錄和重放使用者會話。在功能豐富的單頁應用程式中診斷複雜的使用者行為時，這可能非常有用。

有關可用 hints 的資訊，請參閱 hints in JavaScript

回放使用 Attachments.

Configuration

首先，您需要新增 @sentry/rrweb 和 rrweb 軟體包：

npm install --save @sentry/rrweb rrweb

接下來，使用 Sentry SDK 註冊整合。這將根據您使用的框架而有所不同：

import * as Sentry from "@sentry/browser";
import SentryRRWeb from "@sentry/rrweb";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [
    new SentryRRWeb({
      // ...options
    }),
  ],
  // ...
});

有關配置的更多資訊，請參閱 @sentry/rrweb project on GitHub。

捕獲到事件的重播後，您會發現該事件在事件的 “Replay” 部分下的“問題詳細資訊”中可見。

Sampling

為了滿足組織的需求，您可能希望對 replay 進行取樣。最簡單的方法是在初始化 Sentry SDK 時做出抽樣決定。例如，以下是 Sentry 本身如何使用取樣來僅捕獲員工的樣本的方法：

const hasReplays = getCurrentUser().isStaff;

let integrations = [];
if (hasReplays) {
  console.log("[sentry] Instrumenting session with rrweb");
  integrations.push(new SentryRRWeb());
}

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations,
});

Sentry.setTag("rrweb.active", hasReplays ? "yes" : "no");

您會注意到我們還設定了 rrweb.active 標記，該標記可幫助我們識別附加了 replay 的事件，因為否則我們將無法找到它們。配置完成後，您將可以在搜尋查詢中簡單地使用 rrweb.active:yes。

Sentry Testkit

在為應用程式構建測試時，您希望斷言正確的 flow-tracking 或錯誤正在傳送到 Sentry，而不是真正地將其傳送到 Sentry 伺服器。這樣，您就不會在測試執行或其他 CI 操作期間用錯誤報告淹沒 Sentry。

Note: Wix, 一個 Sentry 合作伙伴, 負責維護Sentry Testkit。

Sentry Testkit 是一個 Sentry 外掛，允許攔截 Sentry 的報告，並進一步檢查正在傳送的資料。它允許 Sentry 在您的應用程式中原生工作，並且通過覆蓋預設 Sentry 的傳輸機制，報告並不真正傳送，而是在本地記錄到記憶體中。通過這種方式，可以在以後獲取記錄的報告，用於您自己的使用、驗證，或者您在本地開發/測試環境中的任何其他用途。

Installation

npm install sentry-testkit --save-dev

Using in tests

const sentryTestkit = require("sentry-testkit");

const { testkit, sentryTransport } = sentryTestkit();

// initialize your Sentry instance with sentryTransport
Sentry.init({
  dsn: "___PUBLIC_DSN___",
  transport: sentryTransport,
  //... other configurations
});

// then run any scenario that should call Sentry.catchException(...)

expect(testkit.reports()).toHaveLength(1);
const report = testkit.reports()[0];
expect(report).toHaveProperty(/*...*/);

您也可以在 sentry-testkit 倉庫中的 testing section 中看到更多用法示例。

Testkit API

Sentry Testkit 由一個非常簡單和直接的 API 組成。在 Sentry Testkit Docs 中可以看到完整的 API 描述和文件。

中文文件陸續同步到：

我是為少。
微信：uuhells123。
公眾號：黑客下午茶。
謝謝點贊支援???！

相關文章