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

Basic Options

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

選項作為對象傳遞給 init() 函數：

Sentry.init({
  dsn: "https://[email protected]/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: "[email protected]",
});

在 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

beforeSend / beforeBreadcrumb
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 方法會清空事件隊列。