Sentry For Vue 完整接入詳解(2021 Sentry v21.8.x)前方高能預警！三萬字，慎入！

內容源於：https://docs.sentry.io/platforms/javascript/guides/vue/

系列

• 1 分鍾快速使用 Docker 上手最新版 Sentry-CLI - 創建版本
• 快速使用 Docker 上手 Sentry-CLI - 30 秒上手 Source Maps
• Sentry For React 完整接入詳解

腦圖

公眾號：黑客下午茶

快速開始

Sentry 的 SDK 支持自動報告錯誤和異常。

安裝

Sentry 通過在應用程序 runtime 使用 SDK 捕獲數據。

# 使用 npm
npm install --save @sentry/vue @sentry/tracing
# 使用 yarn
yarn add @sentry/vue @sentry/tracing

配置

配置應該在應用程序的生命周期中盡早進行。

要在您的 Vue 應用程序中初始化 Sentry，請將其添加到您的 app.js 中：

Vue2

import Vue from "vue";
import Router from "vue-router";
import * as Sentry from "@sentry/vue";
import { Integrations } from "@sentry/tracing";

Vue.use(Router);

const router = new Router({
  // ...
});

Sentry.init({
  Vue,
  dsn: "https://[e-mail]/0",
  integrations: [
    new Integrations.BrowserTracing({
      routingInstrumentation: Sentry.vueRouterInstrumentation(router),
      tracingOrigins: ["localhost", "my-site-url.com", /^\//],
    }),
  ],
  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for performance monitoring.
  // We recommend adjusting this value in production
  tracesSampleRate: 1.0,
});

// ...

new Vue({
  router,
  render: h => h(App),
}).$mount("#app");

Vue3

import { createApp } from "vue";
import { createRouter } from "vue-router";
import * as Sentry from "@sentry/vue";
import { Integrations } from "@sentry/tracing";

const app = createApp({
  // ...
});
const router = createRouter({
  // ...
});

Sentry.init({
  app,
  dsn: "https://[e-mail]/0",
  integrations: [
    new Integrations.BrowserTracing({
      routingInstrumentation: Sentry.vueRouterInstrumentation(router),
      tracingOrigins: ["localhost", "my-site-url.com", /^\//],
    }),
  ],
  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for performance monitoring.
  // We recommend adjusting this value in production
  tracesSampleRate: 1.0,
});

app.use(router);
app.mount("#app");

此外，Vue 3 允許您使用具有相同 Sentry SDK 實例的多個應用程序，以及在 SDK 已經初始化后動態添加更多應用程序。

Vue 3 - 多個 App

const appOne = Vue.createApp(App);
const appTwo = Vue.createApp(App);
const appThree = Vue.createApp(App);

Sentry.init({
  app: [appOne, appTwo, appThree],
});

Vue 3 - 手動初始化

import * as Sentry from "@sentry/vue";

// ...
const app = createApp(App);

Sentry.init({
  app,
  // ...
});

const miscApp = createApp(MiscApp);
miscApp.mixin(Sentry.createTracingMixins({ trackComponents: true }));
Sentry.attachErrorHandler(miscApp, { logErrors: true });

SDK 接受一些不同的配置選項，可讓您更改其行為：

• attachProps（默認為 true）- 包括所有 Vue 組件的帶有事件的屬性(props)。
• logErrors (默認為 false) - 決定 SDK 是否也應該調用 Vue 的原始 logError 函數。
• trackComponents（默認為 false）- 決定是否通過 hooking 到其生命周期方法來跟蹤組件。可以設置為布爾值(boolean)，以啟用/禁用對所有組件的跟蹤，或設置為特定組件名稱的數組（區分大小寫）。
• timeout（默認為 2000）- 以毫秒為單位的時間，指示等待被跟蹤的根活動標記為完成(finished)並發送給 Sentry 的時間。
• hooks（默認為['activate', 'mount', 'update']）- 在組件生命周期 'activate' | 'create' | 'destroy' | 'mount' | 'unmount' | 'update' 期間要跟蹤的 hooks 列表。

如果啟用 SDK，Vue 將不會在內部調用其 logError。因此，Vue 渲染器中發生的錯誤將不會顯示在開發人員控制台中。要保留此功能，請傳遞 logErrors:true 選項。

驗證

此代碼段包含一個故意錯誤，因此您可以在設置后立即測試一切是否正常：

向頁面添加一個引發錯誤的按鈕：

// ...
<button @click="throwError">Throw error</button>
// ...

export default {
  // ...
  methods: {
    throwError() {
      throw new Error('Sentry Error');
    }
  }
};

配置

基本選項

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

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

Sentry.init({
  dsn: "https://[e-mail]/0",
  maxBreadcrumbs: 50,
  debug: true,
});

常見選項

跨 SDK 的常用選項列表。這些在所有 SDK 中的工作方式或多或少都相同，但為了更好地支持平台，將存在一些細微差別。 可以從環境變量（SENTRY_DSN、SENTRY_ENVIRONMENT、SENTRY_RELEASE）中讀取的選項會自動讀取。

dsn

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

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

更多：https://docs.sentry.io/product/sentry-basics/dsn-explainer/#dsn-utilization

debug

打開或關閉調試模式。如果啟用了調試，如果發送事件時出現問題，SDK 將嘗試打印出有用的調試信息。默認值總是 false。一般不建議在生產環境中打開它，盡管打開 debug 模式不會引起任何安全問題。

release

設置 release。某些 SDK 會嘗試自動配置 release，但是最好手動設置 release，以確保該 release 與您的 deploy integrations 或 source map uploads 同步。Release 名稱是字符串，但是 Sentry 會檢測到某些格式，並且它們的呈現方式可能有所不同。

更多：https://docs.sentry.io/product/releases/

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

environment

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

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

tunnel

設置將用於傳輸捕獲事件的 URL，而不是使用 DSN。這可用於解決廣告攔截器(ad-blockers)或對發送到 Sentry 的事件進行更精細的控制。此選項需要實現自定義服務器端點。

更多：https://docs.sentry.io/platforms/javascript/troubleshooting/#dealing-with-ad-blockers

sampleRate

配置錯誤事件的采樣率，范圍為 0.0 到 1.0。默認值為 1.0，表示發送了 100％ 的錯誤事件。如果設置為 0.1，則僅發送 10％ 的錯誤事件。事件是隨機選擇的。

maxBreadcrumbs

這個變量控制應該捕獲的面包屑總數。默認值為 100。

attachStacktrace

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

該選項默認為 off。

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

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 將向 Sentry 發送 session 事件。這在所有瀏覽器 SDK 中都受支持，每個頁面加載和頁面導航都向 Sentry 發出一個 session。在移動 SDK 中，當應用進入后台超過 30 秒時，會話結束。

initialScope

要設置為初始作用域的數據。初始作用域可以定義為對象或回調函數，如下所示。

對象：

Sentry.init({
  dsn: "https://[e-mail]/0",
  debug: true,
  initialScope: {
    tags: {"my-tag": "my value"},
    user: {id: 42, email: "[e-mail]"},
  }
});

回調函數：

Sentry.init({
  dsn: "https://[e-mail]/0",
  debug: true,
  initialScope: scope => {
    scope.setTags({ a: 'b' });
    return scope;
  },
});

maxValueLength

單個值在被截斷之前可以具有的最大字符數（默認為 250）。

normalizeDepth

Sentry SDK 將任何上下文數據標准化到給定的深度。 任何包含結構比這更深的數據的 key 都將使用其類型（[Object] 或 [Array]）進行修剪和標記，而不會進一步遍歷樹。默認情況下，步行執行 3 級深度。

集成配置

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

integrations

在某些 SDK 中，在庫初始化時通過此參數配置集成。

更多：

defaultIntegrations

這可以用來禁用默認添加的集成。當設置為 false 時，不會添加默認的集成。

Hooks

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

beforeSend

使用 SDK-specific 事件對象調用此函數，可以返回修改后的事件對象或不返回任何內容，以跳過報告事件。例如，這可以用於在發送前手動剝離 PII。

beforeBreadcrumb

在將面包屑添加到作用域之前，使用 SDK 特定的面包屑(SDK-specific breadcrumb)對象調用此函數。當該函數未返回任何內容時，將刪除 breadcrumb。要傳遞 breadcrumb，請返回第一個參數，其中包含 breadcrumb 對象。回調通常會獲得第二個參數（稱為“hint”），該參數包含創建 breadcrumb 的原始對象，以進一步自定義面包屑的外觀。

傳輸選項

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

transport

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

跟蹤選項

tracesSampleRate

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

tracesSampler

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

集成

默認集成

Sentry 的所有 SDK 都提供集成，可擴展 SDK 的功能。

默認情況下啟用系統集成以集成到標准庫或解釋器本身。 它們被記錄在案，因此您既可以了解它們的作用，也可以在它們引起問題時禁用它們。

默認啟用

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 可以提供原始的函數和方法名稱，即使我們的錯誤(error)或面包屑處理程序(breadcrumbs handlers)包裝了它們也是如此。

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。

可用選項：

{
  // 記錄對 `console.log`、`console.debug` 等的調用
  console: boolean;

  // 記錄所有點擊和按鍵事件
  // - 當提供帶有 `serializeAttribute` key 的對象時，
  //   面包屑集成將在 DOM 元素中查找給定的屬性，同時生成面包屑路徑。
  //   匹配的元素后跟它們的自定義屬性，而不是它們的 `id` 或 `class` 名稱。
  dom: boolean | { serializeAttribute: string | string[] };

  // 記錄使用 `Fetch API` 完成的 `HTTP` 請求
  fetch: boolean;

  // 記錄對 `history.pushState` 的調用
  history: boolean;

  // 每當我們向服務器發送事件時記錄
  sentry: boolean;

  // 記錄使用 XHR API 完成的 HTTP 請求
  xhr: boolean;
}

GlobalHandlers

Import name: Sentry.Integrations.GlobalHandlers

這個集成附加了全局處理程序來捕獲未捕獲的 exceptions 和未處理的 rejections。

可用的選項：

{
  onerror: boolean;
  onunhandledrejection: boolean;
}

LinkedErrors

Import name: Sentry.Integrations.LinkedErrors

此集成允許您配置 linked 錯誤。它們將被遞歸地讀取到指定的限制，並由特定的 key 執行查找。默認情況下，Sentry SDK 將限制設置為 5，使用的鍵 key 是 cause。

可用的選項：

{
  key: string;
  limit: number;
}

這是如何實現的代碼示例：

document
  .querySelector("#get-reviews-btn")
  .addEventListener("click", async event => {
    const movie = event.target.dataset.title;
    try {
      const reviews = await fetchMovieReviews(movie);
      renderMovieReviews(reviews);
    } catch (e) {
      const fetchError = new Error(`Failed to fetch reviews for: ${movie}`);
      fetchError.cause = e;
      Sentry.captureException(fetchError);
      renderMovieReviewsError(fetchError);
    }
  });

UserAgent

Import name: Sentry.Integrations.UserAgent

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

Dedupe

Import name: Sentry.Integrations.Dedupe

這種集成消除了某些事件的重復數據。如果您收到許多重復的錯誤，這會很有幫助。請注意，Sentry 只會比較堆棧跟蹤(stack traces)和指紋(fingerprints)。默認情況下為瀏覽器啟用此集成。

import * as Sentry from "@sentry/browser";
import { Dedupe as DedupeIntegration } from "@sentry/integrations";

Sentry.init({
  dsn: "https://[e-mail]/0",
  integrations: [new DedupeIntegration()],
});

CDN

<script
  src="https://browser.sentry-cdn.com/6.12.0/bundle.min.js"
  integrity="sha384-S3qfdh3AsT1UN84WIYNuOX9vVOoFg3nB17Jp5/pTFGDBGBt+dtz7MGAV845efkZr"
  crossorigin="anonymous"
></script>

<script
  src="https://browser.sentry-cdn.com/6.12.0/dedupe.min.js"
  integrity="sha384-3IMGY+DN27Yns7KDiKL3sOWXBYlILQ/bxLogt02NG7DL7qEJHIMbpnXfqNlO0J8G"
  crossorigin="anonymous"
></script>

Sentry.init({
  dsn: "https://[e-mail]/0",
  integrations: [new Dedupe()],
});

修改系統集成

要禁用系統集成，請在調用 init() 時設置 defaultIntegrations: false。

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

刪除集成

此示例刪除了用於向事件添加面包屑的默認啟用集成：

Sentry.init({
  // ...

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

可插拔集成

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

如何啟用

安裝 @sentry/integrations 包，並提供一個帶有你配置到 integrations 選項的新實例。加載 SDK 之后，包括插件。

示例：

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

Sentry.init({
  dsn: "https://[e-mail]/0",
  integrations: [new ReportingObserverIntegration()],
});

CDN

<script
  src="https://browser.sentry-cdn.com/6.12.0/bundle.min.js"
  integrity="sha384-S3qfdh3AsT1UN84WIYNuOX9vVOoFg3nB17Jp5/pTFGDBGBt+dtz7MGAV845efkZr"
  crossorigin="anonymous"
></script>

<script
  src="https://browser.sentry-cdn.com/6.12.0/reportingobserver.min.js"
  integrity="sha384-20D83MPBNSRANJFguhj0o9Qo7p9MCemwdMMQXotwA8742WuIwga85k+T7qEgIMWK"
  crossorigin="anonymous"
></script>

Sentry.init({
  dsn: "https://[e-mail]/0",
  integrations: [new ReportingObserver()],
});

ExtraErrorData

Import name: Sentry.Integrations.ExtraErrorData

這個集成從錯誤對象中提取所有非原生(non-native)屬性，並將它們作為 extra 數據附加到事件中。

可用的選項：

import * as Sentry from "@sentry/browser";
import { ExtraErrorData as ExtraErrorDataIntegration } from "@sentry/integrations";

Sentry.init({
  dsn: "https://[e-mail]/0",
  integrations: [new ExtraErrorDataIntegration(
    {
      // 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;
    }
  )],
});

CDN

<script
  src="https://browser.sentry-cdn.com/6.12.0/bundle.min.js"
  integrity="sha384-S3qfdh3AsT1UN84WIYNuOX9vVOoFg3nB17Jp5/pTFGDBGBt+dtz7MGAV845efkZr"
  crossorigin="anonymous"
></script>

<script
  src="https://browser.sentry-cdn.com/6.12.0/extraerrordata.min.js"
  integrity="sha384-DMO/ZWwA4ztkOtskx1Uad3cH6lbfSA/PGdW2IZ7A/c2qd/BU6zh5xiJ5D4nxJbye"
  crossorigin="anonymous"
></script>

Sentry.init({
  dsn: "https://[e-mail]/0",
  integrations: [new ExtraErrorData(
    {
      // 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。然后，它會重新觸發以保留默認的原生行為。

import * as Sentry from "@sentry/browser";
import { CaptureConsole as CaptureConsoleIntegration } from "@sentry/integrations";

Sentry.init({
  dsn: "https://[e-mail]/0",
  integrations: [new CaptureConsoleIntegration(
    {
      // array of methods that should be captured
      // defaults to ['log', 'info', 'warn', 'error', 'debug', 'assert']
      levels: string[];
    }
  )],
});

CDN

<script
  src="https://browser.sentry-cdn.com/6.12.0/bundle.min.js"
  integrity="sha384-S3qfdh3AsT1UN84WIYNuOX9vVOoFg3nB17Jp5/pTFGDBGBt+dtz7MGAV845efkZr"
  crossorigin="anonymous"
></script>

<script
  src="https://browser.sentry-cdn.com/6.12.0/captureconsole.min.js"
  integrity="sha384-FJ5n80A08NroQF9DJzikUUhiCaQT2rTIYeJyHytczDDbIiejfcCzBR5lQK4AnmVt"
  crossorigin="anonymous"
></script>

Sentry.init({
  dsn: "https://[e-mail]/0",
  integrations: [new CaptureConsole(
    {
      // array of methods that should be captured
      // defaults to ['log', 'info', 'warn', 'error', 'debug', 'assert']
      levels: string[];
    }
  )],
});

Debug

Import name: Sentry.Integrations.Debug

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

可用的選項：

import * as Sentry from "@sentry/browser";
import { Debug as DebugIntegration } from "@sentry/integrations";

Sentry.init({
  dsn: "https://[e-mail]/0",
  integrations: [new DebugIntegration(
    {
      // trigger DevTools debugger instead of using console.log
      debugger: boolean;

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

CDN

<script
  src="https://browser.sentry-cdn.com/6.12.0/bundle.min.js"
  integrity="sha384-S3qfdh3AsT1UN84WIYNuOX9vVOoFg3nB17Jp5/pTFGDBGBt+dtz7MGAV845efkZr"
  crossorigin="anonymous"
></script>

<script
  src="https://browser.sentry-cdn.com/6.12.0/debug.min.js"
  integrity="sha384-OIzIETBTnmaXcnCVlI4DzHq1+YxDdBS6uyZPp8yS60YZNUqzIQvrudJplBqEZ09K"
  crossorigin="anonymous"
></script>

Sentry.init({
  dsn: "https://[e-mail]/0",
  integrations: [new Debug(
    {
      // trigger DevTools debugger instead of using console.log
      debugger: boolean;

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

Offline

Import name: Sentry.Integrations.Offline

此集成使用 Web 瀏覽器的在線和離線事件來檢測何時沒有可用的網絡連接。如果離線，它會將事件保存到 Web 瀏覽器的客戶端存儲（通常是 IndexedDB），然后在網絡連接恢復時自動上傳事件。

Online and offline events

• https://developer.mozilla.org/en-US/docs/Web/API/Navigator/Online_and_offline_events

此插件不會嘗試為其他場景提供本地存儲或重試。 例如，如果瀏覽器有本地連接但沒有互聯網連接，那么它可能會報告它在線，並且在這種情況下，Sentry 的 Offline 插件不會嘗試保存或重試任何發送失敗。

import * as Sentry from "@sentry/browser";
import { Offline as OfflineIntegration } from "@sentry/integrations";

Sentry.init({
  dsn: "https://[e-mail]/0",
  integrations: [new OfflineIntegration(
    {
      // limit how many events will be localled saved. Defaults to 30.
      maxStoredEvents: number;
    }
  )],
});

CDN

<script
  src="https://browser.sentry-cdn.com/6.12.0/bundle.min.js"
  integrity="sha384-S3qfdh3AsT1UN84WIYNuOX9vVOoFg3nB17Jp5/pTFGDBGBt+dtz7MGAV845efkZr"
  crossorigin="anonymous"
></script>

<script
  src="https://browser.sentry-cdn.com/6.12.0/offline.min.js"
  integrity="sha384-rRq5WRQ3OncIj4lduaVZMtyfVwZnqeWXM0nXyXckOrhFLS2mlKEYX+VAlbLlIZL4"
  crossorigin="anonymous"
></script>

Sentry.init({
  dsn: "https://[e-mail]/0",
  integrations: [new Offline(
    {
      // limit how many events will be localled saved. Defaults to 30.
      maxStoredEvents: number;
    }
  )],
});

RewriteFrames

Import name: Sentry.Integrations.RewriteFrames

這種集成允許您對堆棧跟蹤的每個幀應用轉換。 在流線型(streamlined)場景中，它可用於更改其來源的文件幀的名稱，或者可以使用迭代函數為其提供任意變換。

在 Windows 機器上，您必須使用 Unix 路徑並跳過 root 選項中的卷號才能啟用。例如 C:\\Program Files\\Apache\\www 將不起作用，但是 /Program Files/Apache/www 將起作用。

可用的選項：

import * as Sentry from "@sentry/browser";
import { RewriteFrames as RewriteFramesIntegration } from "@sentry/integrations";

Sentry.init({
  dsn: "https://[e-mail]/0",
  integrations: [new RewriteFramesIntegration(
    {
      // root path that will be stripped from the current frame's filename by the default iteratee if the filename is an absolute path
      root: string;

      // a custom prefix that will be used by the default iteratee (default: `app://`)
      prefix: string;

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

CDN

<script
  src="https://browser.sentry-cdn.com/6.12.0/bundle.min.js"
  integrity="sha384-S3qfdh3AsT1UN84WIYNuOX9vVOoFg3nB17Jp5/pTFGDBGBt+dtz7MGAV845efkZr"
  crossorigin="anonymous"
></script>

<script
  src="https://browser.sentry-cdn.com/6.12.0/rewriteframes.min.js"
  integrity="sha384-WOm9k3kzVt1COFAB/zCXOFx4lDMtJh/2vmEizIwgog7OW0P/dPwl3s8f6MdwrD7q"
  crossorigin="anonymous"
></script>

Sentry.init({
  dsn: "https://[e-mail]/0",
  integrations: [new RewriteFrames(
    {
      // root path that will be stripped from the current frame's filename by the default iteratee if the filename is an absolute path
      root: string;

      // a custom prefix that will be used by the default iteratee (default: `app://`)
      prefix: string;

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

使用示例：

例如，如果文件的完整路徑是 /www/src/app/file.js：

用法	堆棧跟蹤中的路徑	描述
RewriteFrames()	app:///file.js	默認行為是替換除文件名之外的絕對路徑，並使用默認前綴 (app:///) 作為前綴。
RewriteFrames({prefix: 'foo/'})	foo/file.js	使用前綴 foo/ 代替默認前綴 app:///。
RewriteFrames({root: '/www'})	app:///src/app/file.js	root 定義為 /www，因此僅從路徑的開頭修剪該部分。

ReportingObserver

Import name: Sentry.Integrations.ReportingObserver

此集成掛鈎到 ReportingObserver API 並將捕獲的事件發送到 Sentry。它可以配置為僅處理特定的 issue 類型。

可用的選項：

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

Sentry.init({
  dsn: "https://[e-mail]/0",
  integrations: [new ReportingObserverIntegration(
    {
      types: <'crash'|'deprecation'|'intervention'>[];
    }
  )],
});

CDN

<script
  src="https://browser.sentry-cdn.com/6.12.0/bundle.min.js"
  integrity="sha384-S3qfdh3AsT1UN84WIYNuOX9vVOoFg3nB17Jp5/pTFGDBGBt+dtz7MGAV845efkZr"
  crossorigin="anonymous"
></script>

<script
  src="https://browser.sentry-cdn.com/6.12.0/reportingobserver.min.js"
  integrity="sha384-20D83MPBNSRANJFguhj0o9Qo7p9MCemwdMMQXotwA8742WuIwga85k+T7qEgIMWK"
  crossorigin="anonymous"
></script>

Sentry.init({
  dsn: "https://[e-mail]/0",
  integrations: [new ReportingObserver(
    {
      types: <'crash'|'deprecation'|'intervention'>[];
    }
  )],
});

Vue Router 集成

Vue 跟蹤集成允許您在初始應用程序加載期間跟蹤渲染性能。

Sentry 使用 mixins 功能在其生命周期階段提供對 Vue 組件的訪問。
當 Sentry 遇到一個名為 root 的組件，它是一個頂級 Vue 實例（如 new Vue({})），
我們使用我們的 BrowserTracing 集成，並創建一個名為 Vue Application Render 的新跨度。
一旦創建了 Vue Application Render 跨度，它將等待它的所有子組件都渲染完畢，然后才將跨度標記為完成(finished)。

所描述的檢測功能將為您提供有關 Vue 實例渲染性能的非常高級的信息。
但是，集成還可以提供有關特定活動期間實際發生的情況的更細粒度的詳細信息。 為此，您需要指定要跟蹤的組件和要偵聽的鈎子（https://vuejs.org/v2/api/#Options-Lifecycle-Hooks）。
您還可以為所有組件打開跟蹤。但是，如果您的應用程序由數百個組件組成，則可能會相當嘈雜。
我們鼓勵更具體。如果您不提供 hooks，Sentry 將跟蹤組件的 mount 和 update 鈎子。

請注意，在指定 hooks 時，我們使用簡單動詞而不是 before 和 -ed 對。
例如，destroy 是正確的。beforeDestroy 和 destroyed 是不正確的。

要設置 Vue Tracing 集成，您首先需要配置 BrowserTracing 集成本身。
有關如何執行此操作的詳細信息，請查看我們的性能文檔。
配置完 BrowserTracing 集成后，繼續配置 Vue 集成本身。
Sentry 將新的跟蹤功能構建到原始 Vue 錯誤處理程序集成中，因此無需添加任何新包。
您只需要提供適當的配置。

跟蹤 Vue 應用程序的最基本配置（僅跟蹤頂級組件）如下所示：

import Vue from "vue";
import * as Sentry from "@sentry/browser";
import { Integrations } from "@sentry/tracing";

Sentry.init({
  // ...
  integrations: [new Integrations.BrowserTracing()],

  // We recommend adjusting this value in production, or using tracesSampler
  // for finer control
  tracesSampleRate: 1.0,
});

如果要跟蹤子組件，並查看有關渲染過程的更多詳細信息，請配置集成以跟蹤它們：

Sentry.init({
  Vue,
  trackComponents: true,
});

或者，您可以選擇更多粒度：

Sentry.init({
  Vue,
  integrations: [new Integrations.BrowserTracing()],
  trackComponents: [
    "App",
    "RwvHeader",
    "RwvFooter",
    "RwvArticleList",
    "Pagination",
  ],
});

例如，如果您想知道某些組件是否在初始頁面加載期間被刪除，請向默認值添加一個 destroy 鈎子：

Sentry.init({
  Vue,
  integrations: [new Integrations.BrowserTracing()],
  trackComponents: [
    "App",
    "RwvHeader",
    "RwvFooter",
    "RwvArticleList",
    "Pagination",
  ],
  hooks: ["mount", "update", "destroy"],
});

您可以指定頂級活動應等待最后一個組件渲染的時間。
每個新的渲染周期都會消除超時的抖動，並從頭開始計數。
一旦達到超時，跟蹤就完成了，所有的信息都會發送給 Sentry。

Sentry.init({
  Vue,
  integrations: [new Integrations.BrowserTracing()],
  trackComponents: true,
  timeout: 4000,
});

配置

tracingOptions: {
  /**
   * Decides whether to track components by hooking into its lifecycle methods.
   * Can be either set to `boolean` to enable/disable tracking for all of them.
   * Or to an array of specific component names (case-sensitive).
   * Default: false
   */
  trackComponents: boolean | string[];
  /**
   * How long to wait (in ms) until the tracked root activity is marked as finished and sent to Sentry
   * Default: 2000
   */
  timeout: number;
  /**
   * List of hooks to keep track of during component lifecycle.
   * Available hooks: 'activate' | 'create' | 'destroy' | 'mount' | 'unmount' | 'update'
   * Based on https://vuejs.org/v2/api/#Options-Lifecycle-Hooks
   */
  hooks: string[];
}

使用 Vue Router

如果您使用 Vue Router，您可以使用我們提供的集成來獲得更好的 transaction 名稱。這是如何使用它的完整示例：

import Vue from "vue";
import App from "./App";
import * as Sentry from "@sentry/vue";
import { Integrations } from "@sentry/tracing";
import Router from "vue-router";
import HelloWorld from "@/components/HelloWorld";

Vue.use(Router);

const Foo = { template: "<div>foo</div>" };
const Bar = { template: "<div>bar</div>" };

const router = new Router({
  routes: [
    {
      path: "/",
      name: "HelloWorld",
      component: HelloWorld,
    },
    { path: "/foo/:id", component: Foo },
    { path: "/bar", component: Bar },
  ],
});

Vue.config.productionTip = false;

Sentry.init({
  Vue: Vue,
  dsn: "https://[e-mail]/0",
  tracesSampleRate: 1.0,
  integrations: [
    new Integrations.BrowserTracing({
      routingInstrumentation: Sentry.vueRouterInstrumentation(router),
    }),
  ],
  trackComponents: true,
});

/* eslint-disable no-new */
new Vue({
  el: "#app",
  router,
  components: { App },
  template: "<App/>",
});

自定義集成

使用以下格式向 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 重播

Sentry 提供了與 rrweb 的概念驗證集成 - 一個用於記錄和重放用戶會話的工具包。 這在診斷豐富的單頁應用程序中的復雜用戶行為時非常有用。

更多信息：

• https://www.rrweb.io/
• https://docs.sentry.io/platforms/javascript/guides/react/configuration/filtering/#using-hints
• https://docs.sentry.io/platforms/javascript/guides/react/enriching-events/attachments/

配置

要開始，您需要添加 @sentry/rrweb 和 rrweb 包：

npm install --save @sentry/rrweb rrweb

接下來注冊與 Sentry SDK 的集成。這將根據您使用的框架而有所不同：

// If you're using one of our integration packages, like `@sentry/react` or
// `@sentry/angular`, substitute its name for `@sentry/browser` here
import * as Sentry from "@sentry/browser";
import SentryRRWeb from "@sentry/rrweb";

Sentry.init({
  dsn: "https://[e-mail]/0",
  integrations: [
    new SentryRRWeb({
      // ...options
    }),
  ],
  // ...
});

捕獲事件的重播后，您會在事件的“重播(Replay)”部分下的“問題詳細信息(Issue Details)”中找到它。

• 更多：https://github.com/getsentry/sentry-rrweb

采樣

為了滿足您組織的需求，您可能更喜歡對回放進行采樣。最簡單的方法是在初始化 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: "https://[e-mail]/0",
  integrations,
});

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

您會注意到我們還設置了 rrweb.active 標簽，這有助於我們識別附加了重播(replay)的事件，否則我們將無法找到它們。 配置完成后，您就可以在搜索查詢中簡單地使用 rrweb.active:yes。

Release & 運行狀況

Release 是部署到環境中的代碼版本。當您向 Sentry 提供有關您的版本的信息時，您可以：

• 確定新版本中引入的問題和回歸
• 預測哪個提交導致了問題以及誰可能負責
• 通過在提交消息中包含問題編號來解決問題
• 部署代碼時接收電子郵件通知

此外，release用於將 source maps 應用於被壓縮的 JavaScript 以查看原始的、未轉換的源代碼。

綁定版本

配置客戶端 SDK 時包含 release ID（通常稱為“版本 version”）。

release 名稱不能：

• 包含換行符、制表符、正斜杠 (/) 或反斜杠 (\)
• 是（全部）句號 (.)、雙句號 (..) 或空格 ( )
• 超過 200 個字符

該值可以是任意的，但我們推薦以下任一命名策略：

• 語義版本控制： package@version 或 package@version+build（例如，my.project.name@2.3.12+1234）
  • package 是 project/app 的唯一標識符（iOS 上的 CFBundleIdentifier，Android 上的 packageName）
  • version 是類似於 semver 的結構 <major>.<minor?>.<patch?>.<revision?>-<prerelease?>（iOS 上的 CFBundleShortVersionString，Android 上的 versionName）
  • build 是標識 app 迭代的數字（iOS 上的 CFBundleVersion，Android 上的 versionCode）
• Commit SHA： 如果您使用 DVCS，我們建議使用標識哈希 identifying hash（例如，commit SHA，da39a3ee5e6b4b0d3255bfef95601890afd80709）。您可以讓 Sentry CLI 使用 sentry-clireleases proposal-version 為支持的版本控制系統自動確定此哈希值。

每個組織的發布都是全局性的；為它們添加特定於項目的前綴，以便於區分。

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

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

• 更多：https://docs.npmjs.com/misc/scripts#packagejson-vars

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

您如何使版本(version)可用於您的代碼取決於您。例如，您可以使用在構建過程中設置的環境變量。

這用 release 值標記每個事件。我們建議您在部署之前告訴 Sentry 一個新 release，因為這將解鎖我們關於 releases 的文檔中討論的更多功能。但是，如果您不這樣做，Sentry 將在第一次看到具有該 release ID 的事件時自動在系統中創建一個 release 實體。

• release:https://docs.sentry.io/product/releases/

配置您的 SDK 后，您可以安裝 repository integration 或手動為 Sentry 提供您自己的 commit metadata。 閱讀我們關於設置 releases 的文檔，以獲取有關集成 integrations、關聯提交 associating commits以及在部署 releases 時通知 Sentry 的更多信息。

• 設置 releases: https://docs.sentry.io/product/releases/setup/

Release 運行狀況

通過觀察用戶采用情況、應用程序使用情況、崩潰百分比和會話數據來監控 release 的運行狀況。 release 運行狀況將深入了解與用戶體驗相關的崩潰和錯誤的影響，並通過 release 詳細信息、圖表和過濾器揭示每個新問題的趨勢。

• health of releases : https://docs.sentry.io/product/releases/health/
• crashes：https://docs.sentry.io/product/releases/health/#crash
• session data：https://docs.sentry.io/product/releases/health/#session

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

我們為每個頁面加載創建一個會話。對於單頁應用程序，我們將為每次導航更改（History API）創建一個新會話。

我們將會話標記為：

• 如果unhandled error 或 unhandled promise rejection 冒泡到全局處理程序，則崩潰。
• 如果 SDK 捕獲包含異常的事件（這包括手動捕獲的錯誤），則會出現錯誤。

要接收有關用戶采用的數據，例如用戶崩潰率百分比和采用特定版本的用戶數，請在初始化 SDK 時將用戶設置在 initialScope 上。

默認情況下，JavaScript SDK 正在發送會話。
要禁用發送會話，請將 autoSessionTracking 標志設置為 false：

Sentry.init({
  autoSessionTracking: false // default: true
});

環境

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

• hidden-environments: https://docs.sentry.io/product/sentry-basics/environments/#hidden-environments

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

環境可幫助您在 sentry.io 的問題詳細信息頁面中更好地過濾問題、版本和用戶反饋，您可以在我們涵蓋使用環境的文檔中了解更多信息。

• environments：https://docs.sentry.io/product/sentry-basics/environments/

過濾

將 Sentry 添加到您的應用程序可為您提供大量關於錯誤和性能的非常有價值的信息，否則您將無法獲得這些信息。 大量的信息是好的——只要它是正確的信息，並且數量合理。

Sentry SDK 有幾個配置選項可以幫助您過濾事件。

我們還提供入站過濾器 Inbound Filters來過濾 sentry.io 中的事件。 不過，我們建議在客戶端級別進行過濾，因為它消除了發送您實際上不想要的事件的開銷。 了解有關事件中可用字段的更多信息。

• Inbound Filters: https://docs.sentry.io/product/data-management-settings/filtering/
• fields available in an event：https://develop.sentry.dev/sdk/event-payloads/

過濾錯誤事件

通過使用 beforeSend 回調方法和配置、啟用或禁用集成來配置您的 SDK 以過濾錯誤事件。

使用 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 文檔中所討論的，breadcrumbs 可以被過濾。

• breadcrumbs: https://docs.sentry.io/product/error-monitoring/breadcrumbs/

Event Hints

before-send 回調傳遞 event 和第二個參數 hint，該參數包含一個或多個 hints。

通常，hint 保存原始異常，以便可以提取附加數據或影響分組。 在本例中，如果捕獲到某種類型的異常，指紋將被強制為一個公共值：

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 可用的信息，請參閱：

• hints in JavaScript: https://docs.sentry.io/platforms/javascript/guides/react/configuration/filtering/#using-hints

當 SDK 創建用於傳輸(transmission)的事件或面包屑時，該傳輸通常是從某種源對象創建的。例如，錯誤事件通常是從日志記錄或異常實例中創建的。為了更好地定制，SDK 將這些對象發送到某些回調（beforeSend、beforeBreadcrumb 或 SDK 中的事件處理器系統）。

使用 Hints

Hints 可在兩個地方獲得：

1. beforeSend / beforeBreadcrumb
2. eventProcessors

事件和面包屑 hints 是包含用於組合事件或面包屑的各種信息的對象。 通常 hints 保存原始異常，以便可以提取附加數據或影響分組。

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

對於面包屑，hints 的使用取決於實現。對於 XHR 請求，hint 包含 xhr 對象本身；對於用戶交互，提示包含 DOM 元素和事件名稱等。

在本例中，如果捕獲到某種類型的異常，指紋將被強制為一個公共值：

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

當引發字符串(string)或非錯誤(non-error)對象時，Sentry 會創建一個合成異常(synthetic exception)，以便您可以獲得基本的堆棧跟蹤。 此異常存儲在此處以供進一步提取數據。

Hints for Breadcrumbs

event

對於從瀏覽器事件創建的面包屑，Sentry SDK 通常將事件作為 hint 提供給面包屑。例如，這可用於將目標 DOM 元素中的數據提取到面包屑中。

level / input

對於從控制台日志(console.log)攔截創建的面包屑。 這保存了原始 console log level 和 log function 的原始輸入數據。

response / input

對於從 HTTP 請求創建的面包屑。它保存響應對象（來自 fetch API）和 fetch 函數的輸入參數。

request / response / event

對於從 HTTP 請求創建的面包屑。這包含請求和響應對象（來自 node HTTP API）以及 node event（response或error）。

xhr

對於通過遺留 XMLHttpRequest API 完成的 HTTP 請求創建的面包屑。這保存了原始的 xhr 對象。

整理 Sentry

您可以構建一個允許的域列表，這些域可能會引發可接受的異常。 例如，如果您的腳本是從 cdn.example.com 加載的並且您的站點是 example.com，您可以將 allowUrls 設置為：

Sentry.init({
  allowUrls: [
    /https?:\/\/((cdn|www)\.)?example\.com/
  ]
});

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

Note
在 5.17.0 版本之前，allowUrls 和 denyUrls 分別稱為 whitelistUrls 和 blacklistUrls。
出於向后兼容性的原因，這些選項仍受支持，但它們將在 6.0 版中刪除。 有關更多信息，請參閱

Inclusive Language Policy：https://develop.sentry.dev/inclusion/

此外，我們的社區還為日常事務編制了一份常見的忽略規則列表，例如 Facebook、Chrome extensions 等。 這很有用，建議您檢查一下這些內容，看看它們是否適用於您。這不是我們 SDK 的默認值； 這只是一個廣泛示例的一個亮點。

• Here is the original gist：https://gist.github.com/impressiver/5092952

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,
  ],
});

使用采樣過濾 Transaction 事件

為了防止某些 transactions 被報告給 Sentry，請使用 tracesSampler 配置選項，它允許您提供一個函數來評估當前 transaction 並在它不是您想要的時候刪除它。 （它還允許您以不同的采樣率對不同的 transaction 進行抽樣。）

注意： tracesSampler 和 tracesSampleRate 配置選項是互斥的。 如果您定義了一個 tracesSampler 來過濾掉某些 transaction，您還必須通過返回您希望對它們進行采樣的速率來處理未過濾 transaction 的情況。

最簡單的形式，僅用於過濾 transaction，它看起來像這樣：

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;
    }
  };
});

關閉與清空

大多數 SDK 的默認行為是在后台通過網絡異步發送事件。 這意味着如果應用程序意外關閉，某些事件可能會丟失。SDK 提供了處理這種情況的機制。

close 方法可選地接受以毫秒為單位的 timeout，並返回一個 promise，該 promise 在刷新所有掛起事件或 timeout 生效時 resolve。

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

調用 close 后，不能再使用當前客戶端。 僅在關閉應用程序之前立即調用 close 很重要。

或者，flush 方法清空事件隊列，同時保持客戶端啟用以供繼續使用。

采樣

將 Sentry 添加到您的應用程序可為您提供大量關於錯誤和性能的非常有價值的信息，否則您將無法獲得這些信息。 大量的信息是好的——只要它是正確的信息，並且數量合理。

采樣 Error 事件

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

Sentry.init({ sampleRate: 0.25 });

更改錯誤采樣率需要重新部署。
此外，設置 SDK 采樣率會限制對事件源的可見性。
為您的項目設置速率限制（僅在 volume 高時丟棄事件）可能更適合您的需求。

采樣 Transaction 事件

我們建議對您的 transaction 進行抽樣，原因有兩個：

1. 捕獲單個跟蹤涉及的開銷最小，但捕獲每個頁面加載或每個 API 請求的跟蹤可能會給您的系統增加不必要的負載。
2. 啟用采樣可以讓您更好地管理發送到 Sentry 的事件數量，因此您可以根據組織的需求定制您的數量。

選擇采樣率的目標是在性能和數量問題與數據准確性之間找到平衡。 您不想收集太多數據，但希望收集足夠的數據以得出有意義的結論。 如果您不確定要選擇什么速率，請從一個較低的值開始，隨着您對流量模式和流量的了解越來越多，逐漸增加它。

配置 Transaction 采樣率

Sentry SDK 有兩個配置選項來控制發送到 Sentry 的 transaction 量，讓您可以獲取具有代表性的樣本：

1. 統一采樣率（tracesSampleRate）：

• 提供均勻的事務橫截面，無論它們在您的應用程序中的哪個位置或在什么情況下發生。
• 使用默認繼承(inheritance)和優先(precedence)行為

2. 采樣函數（tracesSampler）其中：

• 以不同的速率采樣不同的 transaction
• 完全過濾掉一些 transaction
• 修改默認優先級和繼承行為

inheritance: https://docs.sentry.io/platforms/javascript/guides/react/configuration/sampling/#inheritance

precedence:
https://docs.sentry.io/platforms/javascript/guides/react/configuration/sampling/#precedence

Filters:
https://docs.sentry.io/platforms/javascript/guides/react/configuration/filtering/

設置統一采樣率

為此，請將 Sentry.init() 中的 tracesSampleRate 選項設置為 0 到 1 之間的數字。設置此選項后，創建的每個 transaction 都有該百分比的機會被發送到 Sentry。（因此，例如，如果您將 tracesSampleRate 設置為 0.2，大約 20% 的 transaction 將被記錄和發送。）看起來像這樣：

Sentry.init({
  // ...

  tracesSampleRate: 0.2,
});

設置采樣函數

要使用采樣函數，請將 Sentry.init() 中的 tracesSampler 選項設置為一個函數，該函數將接受 samplingContext 對象並返回介於 0 和 1 之間的采樣率。例如：

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;
    }
  };
});

為方便起見，該函數還可以返回一個布爾值。返回 true 等同於返回 1，並且將保證 transaction 將發送到 Sentry。返回 false 相當於返回 0，並保證 transaction 不會被發送到 Sentry。

采樣 Context 數據

默認采樣 Context 數據

在 transaction 事務時傳遞給 tracesSampler 的 SamplingContext 對象中包含的信息因平台和集成(integration)而異。

對於基於瀏覽器的 SDK，它至少包括以下內容：

// contents of `samplingContext`
{
  transactionContext: {
    name: string; // human-readable identifier, like "GET /users"
    op: string; // short description of transaction type, like "pageload"
  }
  parentSampled: boolean; // if this transaction has a parent, its sampling decision
  location: Location | WorkerLocation; // the window.location or self.location object
  ... // custom context as passed to `startTransaction`
}

自定義采樣 Context 數據

使用自定義檢測創建 transaction 時，您可以通過將數據作為可選的第二個參數傳遞給 startTransaction 來將數據添加到 samplesContext。 如果您希望采樣器可以訪問某些數據，但又不想將其作為標簽(tag)或數據(data)附加到 transaction 中，例如敏感信息或太大而無法與 transaction 一起發送的信息，這將非常有用。例如：

Sentry.startTransaction(
  {
    // `transactionContext` - will be recorded on transaction
    name: 'Search from navbar',
    op: 'search',
    tags: {
      testGroup: 'A3',
      treatmentName: 'eager load',
    },
  },
  // `customSamplingContext` - won't be recorded
  {
    // PII
    userId: '12312012',
    // too big to send
    resultsFromLastSearch: { ... }
  },
);

繼承

無論 transaction 的抽樣決策如何，該決策都將傳遞到其子跨度，並從那里傳遞到它們隨后在其他服務中引起的任何 transaction。 （有關如何完成傳播的更多信息，請參閱連接服務。）

• Connecting Services: https://docs.sentry.io/platforms/javascript/performance/

如果當前正在創建的 transaction 是那些后續事務之一（換句話說，如果它有父 transaction），則上游（父）采樣決策將始終包含在采樣上下文數據中，以便您的 tracesSampler 可以選擇是否和何時繼承該決策。 （在大多數情況下，繼承是正確的選擇，以避免部分跟蹤痕跡。）

在某些 SDK 中，為了方便起見，tracesSampler 函數可以返回一個布爾值，這樣如果這是所需的行為，則可以直接返回父級的決策。

tracesSampler: samplingContext => {
  // always inherit
  if (samplingContext.parentSampled !== undefined) {
    return samplingContext.parentSampled
  }

  ...
  // rest of sampling logic here
}

如果您使用的是 tracesSampleRate 而不是 tracesSampler，則決策將始終被繼承。

強制抽樣決策

如果您在 transaction 創建時知道是否要將 transaction 發送到 Sentry，您還可以選擇將采樣決策直接傳遞給 transaction 構造函數（注意，不是在 customSamplingContext 對象中）。如果您這樣做，transaction 將不受 tracesSampleRate 的約束，也不會運行 tracesSampler，因此您可以指望通過的決策不會被覆蓋。

Sentry.startTransaction({
  name: "Search from navbar",
  sampled: true,
});

優先級

transaction 以多種方式結束抽樣決策。

• 根據 tracesSampleRate 中設置的靜態采樣率隨機采樣
• 根據 tracesSampler 采樣函數返回的采樣率隨機采樣
• tracesSampler 返回的絕對決策（100% 機會或 0% 機會）
• 如果 transaction 有父級，繼承其父級的抽樣決策
• 絕對決策傳遞給 startTransaction

當有可能不止一個發揮作用時，以下優先規則適用：

1. 如果將抽樣決策傳遞給 startTransaction（請參閱上面的強制抽樣決策），則將使用該決策，而不管其他任何事情
2. 如果定義了 tracesSampler，則將使用其決策。 它可以選擇保留或忽略任何父采樣決策，或使用采樣上下文數據來做出自己的決策或為 transaction 選擇采樣率。
3. 如果未定義 tracesSampler，但存在父采樣決策，則將使用父采樣決策。
4. 如果未定義 tracesSampler 並且沒有父采樣決策，則將使用 tracesSampleRate。

Sentry Testkit

在為您的應用程序構建測試時，您希望斷言正確的流跟蹤(flow-tracking)或錯誤正在發送到 Sentry，但沒有真正將其發送到 Sentry 服務器。 這樣您就不會在測試運行或其他 CI 操作期間用錯誤報告淹沒 Sentry。

注意：Sentry 合作伙伴 Wix 維護 Sentry Testkit。

• Wix：https://wix.github.io/sentry-testkit/

Sentry Testkit 是一個 Sentry 插件，它允許攔截 Sentry 的 report 並進一步檢查正在發送的數據。它使 Sentry 能夠在您的應用程序中原生工作，並且通過覆蓋默認 Sentry 的傳輸機制(transport mechanism)，報告不會真正發送，而是本地記錄到內存中。 這樣，您可以稍后獲取記錄的報告以供您自己使用、驗證或您在本地開發/測試環境中可能擁有的任何其他用途。

Sentry Testkit: https://wix.github.io/sentry-testkit/

安裝

npm install sentry-testkit --save-dev

在測試中使用

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

const { testkit, sentryTransport } = sentryTestkit();

// initialize your Sentry instance with sentryTransport
Sentry.init({
  dsn: "https://[e-mail]/0",
  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: https://github.com/wix/sentry-testkit/tree/master/test

Testkit API

Sentry Testkit 由一個非常簡單直接的 API 組成。 請參閱 Sentry Testkit Docs 中的完整 API 描述和文檔。

Sentry Testkit Docs: https://wix.github.io/sentry-testkit/

用法

Sentry 的 SDK 與您的運行時環境掛鈎，並根據平台自動報告錯誤、未捕獲的異常和未處理的拒絕以及其他類型的錯誤。

關鍵術語：

• event 是向 Sentry 發送數據的一個實例。 通常，此數據是錯誤(error)或異常(exception)。
• issue 是一組相似的事件。
• 事件的報告稱為捕獲(capturing)。當一個事件被捕獲時，它被發送到 Sentry。

最常見的捕獲形式是捕獲錯誤。可以捕獲為錯誤的內容因平台而異。 一般來說，如果你有一些看起來像異常的東西，它可以被捕獲。對於某些 SDK，您還可以省略 captureException 的參數，Sentry 將嘗試捕獲當前異常。它對於手動向 Sentry 報告錯誤或消息也很有用。

在捕獲事件時，您還可以記錄導致該事件的面包屑(breadcrumbs)。 面包屑與事件不同：它們不會在 Sentry 中創建事件，而是會被緩沖，直到發送下一個事件。 在我們的面包屑文檔中了解有關面包屑的更多信息。

breadcrumbs: https://docs.sentry.io/platforms/javascript/guides/react/enriching-events/breadcrumbs/

捕獲 Errors

通過包含和配置 Sentry，我們的 React SDK 會自動附加全局處理程序(global handlers)來捕獲未捕獲的異常和未處理的 promise 拒絕，如官方 ECMAScript 6 標准中所述。您可以通過在 GlobalHandlers 集成中將 onunhandledrejection 選項更改為 false 並手動掛接到每個事件處理程序，然后直接調用 Sentry.captureException 或 Sentry.captureMessage 來禁用此默認行為。

您可以將 Error 對象傳遞給 captureException() 以將其捕獲為事件。也可以傳遞非 Error(non-Error) 對象和字符串(string)，但請注意 Sentry 中的結果事件(resulting events)可能會丟失堆棧跟蹤。

import * as Sentry from "@sentry/react";

try {
  aFunctionThatMightFail();
} catch (err) {
  Sentry.captureException(err);
}

捕獲 Messages

另一種常見的操作是捕獲裸消息。消息是應該發送給 Sentry 的文本信息。通常不會發出消息，但它們對某些團隊很有用。

Sentry.captureMessage("Something went wrong");

設置 Level

級別 - 類似於日志級別 - 通常基於集成默認添加。 您還可以在事件中覆蓋它。

要設置超出范圍的級別，您可以為每個事件調用 captureMessage()：

Sentry.captureMessage("this is a debug message", "debug");

要在作用域內設置級別，您可以調用 setLevel()：

Sentry.configureScope(function(scope) {
  scope.setLevel(Sentry.Severity.Warning);
});

或每個事件：

Sentry.withScope(function(scope) {
  scope.setLevel("info");
  Sentry.captureException("info");
});

SDK 指紋

所有事件都有一個指紋。具有相同指紋的事件被組合成一個 issue。

默認情況下，Sentry 將運行一種內置分組算法，以根據事件中可用的信息（如堆棧跟蹤stacktrace、異常exception和消息message）生成指紋。 要擴展默認分組行為或完全更改它，您可以使用以下選項的組合：

1. 在您的 SDK 中，使用 SDK 指紋識別，如下所述
2. 在您的項目中，使用指紋規則或堆棧跟蹤規則
   • Fingerprint Rules: https://docs.sentry.io/product/data-management-settings/event-grouping/fingerprint-rules/
   • Stack Trace Rules：https://docs.sentry.io/product/data-management-settings/event-grouping/stack-trace-rules/

在受支持的sdk中，您可以覆蓋 Sentry 的默認分組，該分組將指紋屬性作為字符串數組傳遞。指紋數組的長度不受限制。這類似於指紋規則功能，它總是可用的，可以實現類似的結果。

• fingerprint-rules：https://docs.sentry.io/product/data-management-settings/event-grouping/fingerprint-rules/

基本示例

在最基本的情況下，直接傳遞值：

function makeRequest(method, path, options) {
  return fetch(method, path, options).catch(function(err) {
    Sentry.withScope(function(scope) {
      // group errors together based on their request and response
      scope.setFingerprint([method, path, String(err.statusCode)]);
      Sentry.captureException(err);
    });
  });
}

您可以使用變量替換將動態值填充到通常在服務器上計算的指紋中。 例如，可以添加值 {{ default }} 以將整個正常生成的分組哈希添加到指紋中。 這些值與服務器端指紋識別相同。有關更多信息，請參閱：

Variables: https://docs.sentry.io/product/data-management-settings/event-grouping/fingerprint-rules/#variables

以更大的粒度對錯誤進行分組

您的應用程序查詢遠程過程調用模型 (RPC) 接口或外部應用程序編程接口 (API) 服務，因此堆棧跟蹤通常是相同的（即使傳出請求非常不同）。

以下示例將進一步拆分 Sentry 將創建的默認組（由 {{ default }} 表示），並考慮到錯誤對象的一些屬性：

class MyRPCError extends Error {
  constructor(message, functionName, errorCode) {
    super(message);

    // The name of the RPC function that was called (e.g. "getAllBlogArticles")
    this.functionName = functionName;

    // For example a HTTP status code returned by the server.
    this.errorCode = errorCode;
  }
}

Sentry.init({
  ...,
  beforeSend: function(event, hint) {
    const exception = hint.originalException;

    if (exception instanceof MyRPCError) {
      event.fingerprint = [
        '{{ default }}',
        String(exception.functionName),
        String(exception.errorCode)
      ];
    }

    return event;
  }
});

更進一步地分組錯誤

通用錯誤（例如數據庫連接錯誤）具有許多不同的堆棧跟蹤，並且永遠不會組合在一起。

以下示例將通過從數組中省略 {{ default }} 來完全覆蓋 Sentry 的分組：

class DatabaseConnectionError extends Error {}

Sentry.init({
  ...,
  beforeSend: function(event, hint) {
    const exception = hint.originalException;

    if (exception instanceof DatabaseConnectionError) {
      event.fingerprint = ['database-connection-error'];
    }

    return event;
  }
});

Source Maps

生成 Source Maps

大多數現代 JavaScript 編譯器都支持 source maps。以下是一些常用工具的說明。

我們建議使用 Sentry 的 Webpack 插件來配置 source maps 並在構建過程中自動上傳它們。

sentry-webpack-plugin: https://github.com/getsentry/sentry-webpack-plugin

source-map-support

要依賴 Sentry 的 source map 解析，您的代碼不能使用 source-map-support 包。 該包以一種阻止我們的處理器正確解析它的方式覆蓋捕獲的堆棧跟蹤。

source-map-support：https://www.npmjs.com/package/source-map-support

Webpack

Sentry 提供了一個方便的 Webpack 插件，可以配置 source maps 並自動將它們上傳到 Sentry。

要使用該插件，您首先需要安裝它：

npm install --save-dev @sentry/webpack-plugin
// or
yarn add --dev @sentry/webpack-plugin

然后，配置它webpack.config.js：

const SentryWebpackPlugin = require("@sentry/webpack-plugin");

module.exports = {
  // other webpack configuration
  devtool: 'source-map',
  plugins: [
    new SentryWebpackPlugin({
      // sentry-cli configuration - can also be done directly through sentry-cli
      // see https://docs.sentry.io/product/cli/configuration/ for details
      authToken: process.env.SENTRY_AUTH_TOKEN,
      org: "example-org",
      project: "example-project",
      release: process.env.SENTRY_RELEASE,

      // other SentryWebpackPlugin configuration
      include: ".",
      ignore: ["node_modules", "webpack.config.js"],
    }),
  ],
};

此外，Webpack 插件會自動設置 window.SENTRY_RELEASE，因此您的 Sentry.init 調用不需要包含 release 值。

將 Webpack 插件設置為最后運行的插件；
否則，插件收到的 source maps 可能不是最終的。

高級用法

如果您更喜歡手動上傳 source maps，請配置 Webpack 去輸出 source maps：

module.exports = {
  devtool: 'source-map',
  output: {
    // Make maps auto-detectable by sentry-cli
    filename: "[name].js",
    sourceMapFilename: "[name].js.map",
    // Other `output` configuration
  },
  // Other webpack configuration
};

如果您使用 SourceMapDevToolPlugin 對 source map 生成進行更細粒度的控制，請關閉 noSources，以便 Sentry 可以在事件堆棧跟蹤中顯示正確的源代碼上下文。

SourceMapDevToolPlugin：https://webpack.js.org/plugins/source-map-dev-tool-plugin

Rollup

您可以配置 Rollup 以生成 source maps，然后您可以使用 sentry-cli 上傳 source maps：

• Rollup：https://rollupjs.org/
• upload using sentry-cli：https://docs.sentry.io/product/cli/releases/#sentry-cli-sourcemaps

export default {
  entry: "./src/app.js",
  output: {
    file: "bundle.js",
    format: "cjs",
    sourceMap: true,
  },
};

SystemJS

SystemJS 可以配置為輸出 source maps，然后您可以使用 sentry-cli 上傳 source maps：

builder.bundle("src/app.js", "dist/app.min.js", {
  minify: true,
  sourceMaps: true,
  sourceMapContents: true,
});

此示例配置將您的原始、未轉換的源代碼內聯到生成的 source map 文件中。Sentry 需要 source map 和您的原始源文件來執行反向轉換。 如果您選擇不內聯源文件，則除了 source map 外，您還必須使這些源文件可供 Sentry 使用（見下文）。

• SystemJS：https://github.com/systemjs/builder
• upload using sentry-cli：https://docs.sentry.io/product/cli/releases/#sentry-cli-sourcemaps

TypeScript

TypeScript 編譯器可以輸出 source maps，然后您可以使用 sentry-cli 上傳源映射。

將 sourceRoot 屬性配置為 / 以從生成的源代碼引用中去除構建路徑前綴。這允許 Sentry 相對於您的源根文件夾匹配源文件：

{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSources": true,
    "sourceRoot": "/"
  }
}

UglifyJS

我們強烈建議您使用更高級的打包器（或轉譯器），因為 UglifyJS 配置會變得非常復雜，並且很難達到預期的結果。

UglifyJS 可以配置為輸出 source maps，然后您可以使用 sentry-cli 上傳：

uglifyjs app.js \
  -o app.min.js.map \
  --source-map url=app.min.js.map,includeSources

UglifyJS：https://github.com/mishoo/UglifyJS

上傳 Source Maps

Webpack

Sentry 使用 releases 來將正確的 source maps 與您的事件相匹配。release API 旨在允許您在 Sentry 中存儲源文件（和 source maps）。

您可以在我們的 Webpack 插件的幫助下完成此操作，該插件在內部使用我們的 Sentry CLI。

1. 從您的 [Account] > API keys 創建一個新的身份驗證令牌
2. 確認您在“Scopes”下選擇了 project:write
3. 使用 npm 安裝 @sentry/webpack-plugin
4. 使用必要的配置創建 .sentryclirc 文件，如本頁所述
5. 更新你的 webpack.config.js

const SentryPlugin = require("@sentry/webpack-plugin");

module.exports = {
  // ... other config above ...
  plugins: [
    new SentryPlugin({
      release: process.env.RELEASE,
      include: "./dist",
    }),
  ],
};

使用我們的 Sentry Webpack 插件文檔了解有關插件進一步配置的更多信息。
sentry-webpack-plugin：https://github.com/getsentry/sentry-webpack-plugin

此外，您需要配置 client 以發送 release：

Sentry.init({
  dsn: "https://[e-mail]/0",
  release: process.env.RELEASE,
});

您不必使用 RELEASE 環境變量。只要您上傳的版本與 SDK 的 init 調用的版本相匹配，您就可以以任何形式提供它們。

Releases API：https://docs.sentry.io/api/releases/

Sentry CLI

使用 sentry-cli 上傳 Source Maps

使用 sentry-cli 上傳 source maps 時，您需要設置構建系統以創建版本(release)並上傳與該版本對應的各種源文件。要讓 Sentry 對您的堆棧跟蹤進行解碼，請同時提供：

• 要部署的文件（換句話說，您的編譯/壓縮/打包(transpilation/minification/bundling) 過程的結果；例如，app.min.js）
• 對應的 source maps

如果 source map 文件不包含您的原始源代碼 (sourcesContent)，您還必須提供原始源文件。 如果源文件丟失，Sentry CLI 將嘗試自動將源嵌入到您的 source maps 中。

Sentry 使用 releases 將正確的 source maps 與您的事件相匹配。
要創建新版本，請運行以下命令（例如，在發布期間）：

releases：https://docs.sentry.io/product/releases/

sentry-cli releases new <release_name>

release 名稱在您的組織中必須是唯一的，並且與您的 SDK 初始化代碼中的 release 選項相匹配。
然后，使用 upload-sourcemaps 命令掃描文件夾中的 source maps，處理它們，並將它們上傳到 Sentry。

sentry-cli releases files <release_name> upload-sourcemaps /path/to/files

您可以通過導航到 [Project] > Project Settings > Source Maps 找到上傳到 Sentry 的工件。

此命令會將所有以 .js 和 .map 結尾的文件上傳到指定的版本(release)。如果你想改變這些擴展 — 例如，上傳 typescript 源文件 — 使用 --ext 選項：

sentry-cli releases files <release_name> upload-sourcemaps --ext ts --ext map /path/to/files

到目前為止，該版本處於草稿狀態（“unreleased”）。
上傳所有 source maps 后，您的應用程序已成功發布，使用以下命令完成 release：

sentry-cli releases finalize <release_name>

為方便起見，您可以將 --finalize 標志傳遞給新命令，這將立即完成 release。

有關更多信息，請參閱我們的 sentry-cli 文檔。

• sentry-cli：https://docs.sentry.io/product/cli/releases/#managing-release-artifacts

Web 應用程序可在多個來源訪問的情況並不少見。 請參閱我們關於多源的文檔以了解如何處理此問題。

• multiple origins：https://docs.sentry.io/platforms/javascript/guides/react/sourcemaps/uploading/multiple-origins/

公開托管

將 source maps 提供給 Sentry 的最可靠方法是上傳它們，因為它減少了網絡流量並確保將使用正確版本的代碼和源映射。

默認情況下，Sentry 將在您編譯的 JavaScript 文件中查找 source map 指令。這些指令位於最后一行，格式如下：

//# sourceMappingURL=<url>

當 Sentry 遇到這樣的指令時，它會解析相對於它所在的源文件的 source map URL，並嘗試一個 HTTP 請求來獲取它。

例如，如果您有一個位於 http://example.org/js/app.min.js 的壓縮的 JavaScript 文件，並且在該文件的最后一行，可以找到以下指令：

//# sourceMappingURL=app.js.map

Sentry 將嘗試從 http://example.org/js/app.js.map 獲取 app.js.map。

或者，在 source map 生成期間，您可以指定 source map 所在的完全限定 URL：

//# sourceMappingURL=http://example.org/js/app.js.map

雖然從您的服務器向 Sentry 提供 source maps 是最自然的集成，但並不總是可取的：

• Sentry 可能並不總是能夠訪問您的服務器。
• 如果您未在 asset URL 中指定版本，則可能存在版本不匹配
• 額外的延遲可能意味着源映射並非適用於所有錯誤。

由於這些原因，最好事先將 source maps 上傳到 Sentry（見下文）。

在防火牆后面工作

雖然推薦的解決方案是將您的源工件(打包轉譯后的代碼)上傳到 Sentry，但有時需要允許來自 Sentry 的內部 IP 的通信。
有關 Sentry public IP 的更多信息，請參閱：

• IP Ranges：https://docs.sentry.io/product/security/ip-ranges/

安全訪問 Source Maps

如果您想對 source maps 保密並選擇不將 source maps 直接上傳到 Sentry，您可以在項目設置中啟用 “Security Token” 選項。

這將導致從 Sentry 的服務器發出的來自你的 “Allowed Domains” 的 url 的出站請求附加 HTTP header X-Sentry-Token 頭:

GET /assets/bundle.min.js
X-Sentry-Token: {token}

token 是您在項目設置中定義的安全值。然后，您可以配置您的 Web 服務器以允許在此 header/token 對存在時訪問您的 source maps。 您也可以覆蓋默認 header 名稱 (X-Sentry-Token) 並使用 HTTP Basic Authentication，例如通過傳遞 Authorization: Basic {encoded_password}。

多個 Origin

Web 應用程序可在多個來源訪問的情況並不少見。例如：

• 網站可通過 https 和 http 運行
• 地理定位網址：例如 https://us.example.com、https://eu.example.com
• 多個靜態 CDN：如 https://static1.example.com、https://static2.example.com
• 客戶特定的域/子域

在這種情況下，相同的 JavaScript 和 source map 文件可能位於兩個或多個不同的來源。 在這種情況下，我們建議在路徑上使用我們特殊的波浪號 (~) 前綴。

例如，如果您有以下內容：

• https://static1.example.com/js/app.js
• https://static2.example.com/js/app.js

您可以使用 ~/js/app.js 的 URL 上傳。這將告訴 Sentry 忽略域並將 artifact 用於任何來源。

此外，您還可以以多個名稱上傳同一個文件。 在引擎蓋(hood)下 Sentry 將對這些進行重復數據刪除。

~ 前綴告訴 Sentry 對於給定的 URL，路徑為 /js/app.js 的協議和主機名的任何組合都應該使用這個工件。

驗證文件

確保 source maps 本身有效並正確上傳可能非常具有挑戰性。 為了解決這個問題，我們維護了一個在線驗證工具，可用於針對您的托管源測試您的 source map：sourcemaps.io。

• https://sourcemaps.io/

此外，您可以在使用 sentry-cli 上傳 source maps 時使用 --validate 標志，這將嘗試在本地解析源映射並查找引用。 請注意，在已知情況下，驗證標志將在設置正確時指示失敗（如果您引用了外部 source maps，則驗證工具將指示失敗）。

除了驗證步驟之外，您還可以檢查這些：

• 確保您的文件的 URL 前綴正確。 這很容易出錯。
• 上傳壓縮文件的匹配 source maps。
• 確保您在服務器上的壓縮文件實際上引用了您的文件。

最佳實踐

一個簡單的設置

在這個簡單的項目中，minified/transpiled 的文件及其 source maps 位於同一目錄中：

├── build/
│   ├── worker.js
│   ├── worker.js.map
│   ├── app.js
│   ├── app.js.map
│   ├── index.html
├── package.json
├── public/
│   └── index.html
├── sentry.properties
├── src/
│   ├── app.js
│   └── worker.js
├── webpack.config.js

對於這個項目，我們可以使用一個簡單的 Sentry 配置：

const SentryWebpackPlugin = require("@sentry/webpack-plugin");
// ...
plugins: [
  new SentryWebpackPlugin({
    authToken: process.env.SENTRY_AUTH_TOKEN,
    org: "example-org",
    project: "example-project",
      include: "build",
    configFile: "sentry.properties",
    release: process.env.SENTRY_RELEASE,
  }),
],
// ...

我們建議使用 Webpack 插件將 source maps 集成到 Sentry。 如果您的項目中沒有使用 Webpack，則可以使用 Sentry CLI。

一致的版本

要讓 Sentry 將錯誤堆棧跟蹤與您的 source maps 相關聯，請將您的版本號定義為 Webpack 插件選項或 Sentry CLI 參數（無論您使用哪個）。如果您使用 Sentry CLI，您還應該在 Sentry.init() 調用中定義相同的版本號。 確保版本號一致性的最簡單方法是將其設置為項目中的環境變量：

# ...
SENTRY_RELEASE="1.2.3"
# ...

然后，如果您使用的是 sentry-webpack-plugin：

// ...
new SentryWebpackPlugin({
  // ... other options
  release: process.env.SENTRY_RELEASE,
});
// ...

或者，如果您使用的是 Sentry CLI：

sh sentry-cli releases new "$SENTRY_RELEASE" sentry-cli releases files "$SENTRY_RELEASE" upload-sourcemaps /path/to/sourcemaps

// ...
Sentry.init({
  // ... other options
  release: process.env.SENTRY_RELEASE,
});
// ...

正確的 Source Paths

您的 release artifacts（bundle 文件和源 source maps）的文件名應與堆棧跟蹤中報告的路徑匹配。 您可以使用上傳配置來調整文件的名稱。 Webpack 插件和 Sentry CLI 都有相同的選項；下面介紹了與 source maps 相關的內容。還可以使用我們的 RewriteFrames 集成來調整堆棧跟蹤內的路徑。

根據您的設置，您可能需要在開發和生產環境中為 source maps 進行不同的配置，因為堆棧跟蹤中的路徑可能不同。

Webpack 和 Sentry CLI 的選項

這些選項和示例將有助於集成您的source maps。

include

此選項接受一個或多個路徑來遞歸掃描源和 *.map 文件。例如：

1. 包括您的轉譯器/捆綁器輸出文件的位置：

• include: './app/.next'
• include: './build'

2. 包括來自多個文件夾：

• 包括：['./src', './lib']

3. 遞歸搜索整個項目：

• include: '.'

rewrite

允許重寫匹配的 source maps，以便在可能的情況下將索引映射扁平化並內聯缺失的源。默認為 true。

應該啟用此選項以使 stripPrefix 和 stripCommonPrefix 工作。

urlPrefix

此選項在所有文件名的開頭添加一個公共前綴。默認為 ~/，這是一個匹配任何 scheme 和 hostname 的通配符（http://my.web.site/path/to/script.js 的 http://my.web.site/ 部分）。

當應用程序的入口點（通常是瀏覽器端的 index.html 和 Node 的 index.js）位於源/源映射文件之上一個或多個級別時，此選項很有用，如下例所示：

├── build/
│   ├── index.html
│   ├── static/
│   │   ├── app.js
│   │   ├── app.js.map

在這種情況下，請按照以下示例進行配置：

// ...
new SentryWebpackPlugin({
  // ...
  include: "build/static/",
  urlPrefix: "~/static/"
  // ...
}),
// ...

stripPrefix

此選項從 sourcemap 中（例如，在 sources entry 中）引用的文件名中刪除給定的前綴。 當您需要修剪捆綁器/開發(bundler/development)服務器可能添加到文件名的額外前綴時，這很有用，例如 webpack://_N_E/。

請注意，使用 stripPrefix 選項不會更改上傳文件的名稱。 當您將目標文件的父文件夾作為不需要的前綴時，請在包含 Webpack 插件選項或傳遞給 sentry-cli 的 path/to/sourcemaps 中包含要刪除的部分。例如，如果您的文件存儲在 ./build/static/js/ 並且您在 Webpack 插件配置中有 include: "build"，您的文件將使用類似 ~/static/js/bundle.js 的名稱上傳。如果您更新您的配置 include: "build/static/js"，您的文件將上傳為 ~/bundle.js（等等）。

調整幀(Frames)

或者，您可以使用 Sentry 的 RewriteFrames 集成來微調堆棧跟蹤內的路徑。

import { RewriteFrames } from "@sentry/integrations";

Sentry.init({
  dsn: "https://[e-mail]/0",
  integrations: [
    new RewriteFrames({
      // ... options
    }),
  ],
});

對 Source Maps 進行故障排除

Source maps 有時很難開始。如果您遇到問題：

驗證在您的 SDK 中配置了一個 release

要定位和應用上傳的 source maps，需要通過 CLI 或 API（以及隨其上傳的正確工件）創建 release，並且需要在您的 SDK 配置中指定新創建的 release 的名稱。

要驗證這一點，請從 Sentry UI 打開 issue 並檢查 release 是否已配置。如果屏幕右側的 “Release” 旁邊顯示 “not configured” 或 “N/A”（或者如果您在標簽列表中沒有看到 release tag），則需要返回並標記你的錯誤。如果設置正確，您將看到 "Release: my_example_release"。

驗證工件(artifacts)已上傳

正確配置您的 release 並標記問題后，您可以通過導航到 [Project] » Project Settings » Source Maps 找到上傳到 Sentry 的工件。

此外，請確保所有必要的文件都可用。要讓 Sentry de-minify 堆棧跟蹤，您必須同時提供 minify 的文件（例如 app.min.js）和相應的 source map。如果 source map 文件不包含您的原始源代碼 (sourcesContent)，您必須另外提供原始源代碼文件。或者，sentry-cli 會自動將源代碼（如果缺少）嵌入到您的 source maps 中。

驗證 sourceMappingURL 是否存在

一些 CDN 會自動從靜態文件（包括 JavaScript 文件）中去除注釋。 這可能會導致刪除 JavaScript 文件的 sourceMappingURL 指令，因為它被視為注釋。例如，CloudFlare 有一個名為 Auto-Minify 的功能，如果啟用它，它將去除 sourceMappingURL。

• Auto-Minify：https://blog.cloudflare.com/an-all-new-and-improved-autominify/

仔細檢查您部署的最終 JavaScript 文件是否存在 sourceMappingURL。

或者，您可以在 minify 的文件上設置 SourceMap HTTP header，而不是 sourceMappingURL。如果此 header 存在，Sentry 將使用它來發現 source map 的位置。

驗證 artifact 發布值是否與您的 SDK 中配置的值匹配

每當您使用分發標識符（SDK 中的 dist 配置選項）時，在 source map 上傳期間必須使用相同的值。相反，如果您的 source map 使用 dist 值上傳，則必須在您的 SDK 中設置相同的值。要將 dist 值添加到您上傳的 source maps，請使用 --dist 標志和 sentry-cli 或 dist 選項和 @sentry/webpack-plugin。要在 SDK 中設置 dist 值，請使用 Sentry.init() 中的 dist 選項。

要驗證 SDK 中的分發設置是否正確，請在 Sentry UI 中打開一個 issue 並檢查 dist 標簽是否存在。對於工件，轉到項目設置中的 Source Maps 頁面，選擇您剛剛檢查的事件中顯示的 release，並驗證 dist 值（在 upload time 旁邊的小橢圓中）與事件上的值匹配。

驗證 artifact 名稱與 sourceMappingURL 值匹配

bundled 或 minified 的 JavaScript 文件最后一行的 sourceMappingURL 注釋告訴 Sentry（或瀏覽器）在哪里找到相應的 source map。這可以是完全限定的 URL、相對路徑或文件名本身。 將 artifact 上傳到 Sentry 時，您必須使用文件解析為的值命名源映射文件。

也就是說，如果您的文件類似於：

// -- end script.min.js
//# sourceMappingURL=script.min.js.map

並托管在 http://example.com/js/script.min.js，然后 Sentry 將在 http://example.com/js/script.min.js.map 查找該 source map 文件。 因此，您上傳的 artifact 必須命名為 http://example.com/js/script.min.js.map（或 ~/js/script.min.js.map）。

或者，如果您的文件類似於：

//-- end script.min.js
//# sourceMappingURL=https://example.com/dist/js/script.min.js.map

那么您上傳的 artifact 也應該命名為：

https://example.com/dist/js/script.min.js.map（或 ~/dist/js/script.min.js.map）。

最后，如果您的文件類似於：

//-- end script.min.js
//# sourceMappingURL=../maps/script.min.js.map

那么您上傳的 artifact 應命名為 https://example.com/dist/maps/script.min.js.map（或 ~/dist/maps/script.min.js.map）。

驗證 artifact 名稱與堆棧跟蹤幀匹配

如果您已上傳 source maps，但它們並未應用於 Sentry 問題中的代碼，請查看事件的 JSON 並查找 abs_path 以准確查看我們嘗試解析文件的位置 - 對於 例如，http://localhost:8000/scripts/script.js（對於堆棧跟蹤中的每一幀，abs_path 將出現一次 - 將其與未 deminified 的文件匹配。）。 可以在事件發生日期旁邊的 issue 頁面頂部找到指向 JSON 視圖的鏈接。上傳的 artifact 名稱必須與這些值匹配。

如果您的路徑中有動態值（例如，https://www.site.com/{some_value}/scripts/script.js），您可能需要使用 rewriteFrames 集成來更改您的 abs_path 值。

使用 sentry-cli

如果您的 sourceMappingURL 注釋類似於：

// -- end script.min.js (located at http://localhost:8000/scripts/script.min.js)
//# sourceMappingURL=script.min.js.map

正確上傳這些文件的示例 sentry-cli 命令如下所示（假設您在 /scripts 目錄中，從上一級目錄運行 Web 服務器，這就是我們使用 --url-prefix 選項的原因） ：

sentry-cli releases files VERSION upload-sourcemaps . --url-prefix '~/scripts'

此命令上傳當前目錄中的所有 JavaScript 文件。 Sentry 中的 Artifacts 頁面現在應如下所示：

~/scripts/script.js
~/scripts/script.min.js
~/scripts/script.min.js.map

或者，您可以指定要上傳的文件。 例如：

sentry-cli releases files VERSION upload-sourcemaps script.min.js script.min.js.map --url-prefix '~/scripts'

您還可以使用完全限定的 URL 上傳它。例如：

sentry-cli releases files VERSION upload-sourcemaps . --url-prefix 'http://localhost:8000/scripts'

使用 API

您也可以使用 API 上傳 artifact。

curl -X POST \
  https://sentry.io/api/0/organizations/ORG_SLUG/releases/VERSION/files/ \
  -H 'Authorization: Bearer AUTH_TOKEN' \
  -H 'content-type: multipart/form-data' \
  -F file=@script.min.js.map \
  -F 'name=~/scripts/script.min.js.map'

使用 ~

~ 在 Sentry 中用於替換 scheme 和 domain。

http://example.com/dist/js/script.js 將匹配 ~/dist/js/script.js 或 http://example.com/dist/js/script.js

但不會匹配 ~/script.js。

在發生錯誤之前驗證 artifact 已上傳

Sentry 期望給定版本中的源代碼和 source maps 在該 release 中發生錯誤之前上傳到 Sentry。

如果您在 Sentry 捕獲錯誤后上傳 artifact，Sentry 將不會返回並追溯將任何源注釋(source annotations)應用於這些錯誤。 只有在 artifact 上傳后觸發的新錯誤才會受到影響。

驗證您的 source maps 是否正確構建

我們維護一個在線驗證工具，可用於針對您的托管源測試您的source maps：sourcemaps.io。

• https://sourcemaps.io/

或者，如果您使用 Sentry CLI 將 source maps 上傳到 Sentry，您可以使用 --validate 命令行選項來驗證您的 source maps 是否正確。

驗證您的 source maps 在本地工作

如果您發現 Sentry 沒有正確映射文件名、行或列映射，您應該驗證您的 source maps 是否在本地運行。為此，您可以將 Node.js 與 Mozilla 的source-map library 結合使用。

• https://github.com/mozilla/source-map

首先，將 source-map 作為 npm 模塊全局安裝：

npm install -g source-map

然后，編寫一個腳本來讀取您的 source map 文件並測試映射。 下面是一個例子：

var fs = require("fs"),
  path = require("path"),
  sourceMap = require("source-map");

// file output by Webpack, Uglify, and so forth
var GENERATED_FILE = path.join(".", "app.min.js.map");

// line and column located in your generated file (for example, the source of your error
// from your minified file)
var GENERATED_LINE_AND_COLUMN = { line: 1, column: 1000 };

var rawSourceMap = fs.readFileSync(GENERATED_FILE).toString();
new sourceMap.SourceMapConsumer(rawSourceMap).then(function(smc) {
  var pos = smc.originalPositionFor(GENERATED_LINE_AND_COLUMN);

  // should see something like:
  // { source: 'original.js', line: 57, column: 9, name: 'myfunc' }
  console.log(pos);
});

如果您在本地獲得與通過 Sentry 獲得的結果相同（不正確）的結果，請仔細檢查您的 source map 生成配置。

驗證您的源文件不是太大

對於單個 artifact，Sentry 接受的最大文件大小為 40 MB。

用戶通常會達到此限制，因為他們在臨時構建階段傳輸源文件。例如，在 Webpack/Browserify 合並所有源文件之后，但在 minification 之前。 如果可能，請發送原始源文件。

驗證 artifact 沒有被 gzip

Sentry API 目前僅適用於以純文本（UTF-8 編碼）形式上傳的 source maps 和源文件。如果文件以壓縮格式（例如 gzip）上傳，它們將不會被正確解釋。

這有時發生在生成 pre-compressed minified 文件的構建腳本和插件中。 例如，Webpack 的 compression 插件。您需要禁用此類插件並在生成的 source maps/source files 上傳到 Sentry 后執行壓縮。

• https://github.com/webpack/compression-webpack-plugin

驗證 worker 與 Web 共享相同的卷（如果通過 Docker 運行自托管 Sentry）

Sentry 在其 worker 中進行 source map 計算。 這意味着 worker 需要訪問通過前端上傳的文件。仔細檢查 cron worker 和 web worker 是否可以從同一個磁盤讀取/寫入文件。

故障排除

如果您需要幫助解決 Sentry JavaScript SDK integration 問題，您可以閱讀此處記錄的邊緣案例。

調試附加數據

您可以查看事件的 JSON payload 以了解 Sentry 如何在事件中存儲其他數據。數據的形狀可能與描述不完全匹配。

有關更多詳細信息，請參閱有關事件有效負載的完整文檔。

• https://develop.sentry.dev/sdk/event-payloads/

最大 JSON Payload 大小

maxValueLength 的默認值為 250，但如果您的消息較長，您可以根據需要調整此值。 請注意，並非每個值都受此選項影響。

CORS 屬性和 Header

要了解從不同來源的腳本引發的 JavaScript 異常，請執行以下兩項操作：

1. 添加 crossorigin="anonymous" 腳本屬性

 <script src="http://another-domain.com/app.js" crossorigin="anonymous"></script>

腳本屬性告訴瀏覽器 “anonymously” 獲取目標文件。 請求此文件時，瀏覽器不會將潛在的用戶識別信息（如 cookie 或 HTTP 憑據）傳輸到服務器。

2. 添加 Cross-Origin HTTP header

Access-Control-Allow-Origin: *

跨域資源共享 (CORS) 是一組 API（主要是 HTTP header），用於規定文件應該如何跨域下載和提供服務。

通過設置 Access-Control-Allow-Origin: *，服務器向瀏覽器表明任何來源都可以獲取此文件。 或者，您可以將其限制為您控制的已知來源：

 Access-Control-Allow-Origin: https://www.example.com

大多數社區 CDN 正確設置了 Access-Control-Allow-Origin header。

 $ curl --head https://ajax.googleapis.com/ajax/libs/jquery/2.2.0/jquery.js | \
 grep -i "access-control-allow-origin"

 Access-Control-Allow-Origin: *

意外的 OPTIONS 請求

如果您的應用程序由於執行額外的 OPTIONS 請求而開始行為異常，則很可能是不需要的 sentry-trace 請求 header 的問題，當您在瀏覽器 SDK 中為我們的 Tracing Integration 使用過於通用的配置時可能會發生這種情況。

要解決此問題，請在 SDK 初始化期間更改 trackingOrigins 選項。 有關更多詳細信息，請參閱我們的性能監控文檔中的自動檢測。

• https://docs.sentry.io/platforms/javascript/performance/instrumentation/automatic-instrumentation/#tracingorigins

instrument.js Console Log 語句的行號

如果調試時在您的控制台中顯示了 instrument.js，請將 Sentry 添加到您的框架黑盒設置中，例如：/@sentry/，以便 Chrome 在調試時忽略 SDK 堆棧幀。

• blackboxing：https://docs.sentry.io/platforms/javascript/guides/react/troubleshooting/

處理廣告攔截器(Ad-Blockers)

當您使用我們的 CDN 時，廣告攔截或腳本攔截擴展可能會阻止我們的 SDK 被正確獲取和初始化。因此，對 SDK API 的任何調用都將失敗，並可能導致您的應用程序出現意外行為。

此外，即使正確下載並初始化 SDK，也可能會阻止需要接收捕獲數據的 Sentry 端點。這將阻止任何錯誤報告、會話運行狀況或性能數據的傳遞，從而使其在 sentry.io 中實際上不可用。

您可以通過上述多種方式解決第一個 issue 。但是，端點阻塞只能使用隧道解決。

使用 tunnel 選項

隧道是一個 HTTP 端點，充當 Sentry 和您的應用程序之間的代理。 由於您控制此服務器，因此不會有任何發送到它的請求被阻止的風險。 當端點位於同一個源下時（盡管它不必為了隧道工作），瀏覽器不會將任何對端點的請求視為第三方請求。因此，這些請求將應用不同的安全措施，默認情況下不會觸發廣告攔截器。可以在下面找到流程的快速摘要。

從 JavaScript SDK 6.7.0 版開始，您可以使用 tunnel 選項告訴 SDK 將事件傳送到配置的 URL，而不是使用 DSN。 這允許 SDK 從查詢參數中刪除 sentry_key，這是廣告攔截器首先阻止發送事件的主要原因之一。此選項還會阻止 SDK 發送預檢請求，這是需要在查詢參數中發送 sentry_key 的要求之一。

要啟用 tunnel 選項，請在 Sentry.init 調用中提供相對或絕對 URL。當您使用相對 URL 時，它是相對於當前來源的，這是我們推薦的形式。使用相對 URL 不會觸發預檢 CORS 請求，因此不會阻止任何事件，因為廣告攔截器不會將這些事件視為第三方請求。

Sentry.init({
  dsn: "https://[e-mail]/0",
  tunnel: "/tunnel",
});

配置完成后，所有事件都將發送到 /tunnel 端點。 但是，此解決方案需要在服務器上進行額外配置，因為現在需要解析事件並將其重定向到 Sentry。 這是您的服務器組件的示例：

<?php
// Change $host appropriately if you run your own Sentry instance.
$host = "sentry.io";
// Set $known_project_ids to an array with your Sentry project IDs which you
// want to accept through this proxy.
$known_project_ids = array(  );

$envelope = stream_get_contents(STDIN);
$pieces = explode("\n", $envelope, 2);
$header = json_decode($pieces[0], true);
if (isset($header["dsn"])) {
    $dsn = parse_url($header["dsn"]);
    $project_id = intval(trim($dsn["path"], "/"));
    if (in_array($project_id, $known_project_ids)) {
      $options = array(
        'http' => array(
            'header'  => "Content-type: application/x-sentry-envelope\r\n",
            'method'  => 'POST',
            'content' => $envelope
        )
      );
      echo file_get_contents(
          "https://$host/api/$project_id/envelope/",
          false,
          stream_context_create($options));
    }
}

// Requires .NET Core 3.1 and C# 9 or higher
using System;
using System.Collections.Generic;
using System.IO;
using System.Net.Http;
using System.Text.Json;
using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;

// Change host appropriately if you run your own Sentry instance.
const string host = "sentry.io";
// Set knownProjectIds to a list with your Sentry project IDs which you
// want to accept through this proxy.
var knownProjectIds = new HashSet<string>() {  };

var client = new HttpClient();
WebHost.CreateDefaultBuilder(args).Configure(a =>
    a.Run(async context =>
    {
        context.Request.EnableBuffering();
        using var reader = new StreamReader(context.Request.Body);
        var header = await reader.ReadLineAsync();
        var headerJson = JsonSerializer.Deserialize<Dictionary<string, object>>(header);
        if (headerJson.TryGetValue("dsn", out var dsnString)
            && Uri.TryCreate(dsnString.ToString(), UriKind.Absolute, out var dsn))
        {
            var projectId = dsn.AbsolutePath.Trim('/');
            if (knownProjectIds.Contains(projectId) && string.Equals(dsn.Host, host, StringComparison.OrdinalIgnoreCase)) {
              context.Request.Body.Position = 0;
              await client.PostAsync($"https://{dsn.Host}/api/{projectId}/envelope/",
                  new StreamContent(context.Request.Body));
            }
        }
    })).Build().Run();

查看我們的示例存儲庫以了解更多信息。

• https://github.com/getsentry/examples/tree/master/tunneling

如果您的用例與 SDK 包本身被阻止有關，以下任何一種解決方案都可以幫助您解決此問題。

直接使用 Package

處理腳本阻塞擴展的最佳方法是直接通過 npm 使用 SDK 包並將其與您的應用程序捆綁在一起。 這樣，您就可以確保代碼始終如您所願。

第二種方法是從我們的 CDN 下載 SDK 並自己托管。這樣，SDK 仍將與您的其余代碼分開，但您可以確定它不會被阻止，因為它的來源將與您網站的來源相同。

您可以使用 curl 或任何其他類似工具輕松獲取它：

curl https://browser.sentry-cdn.com/5.20.1/bundle.min.js -o sentry.browser.5.20.1.min.js -s

使用 JavaScript Proxy API

最后一個選項是使用 Proxy 保護，這將確保您的代碼不會中斷，即使您調用我們的 SDK，它被阻止。 除了 Internet Explorer 之外的所有瀏覽器都支持 Proxy。此外，如果 Proxy 不在您用戶的任何瀏覽器中，它將被悄悄跳過，因此您不必擔心它會破壞任何內容。

將此代碼段直接放在包含我們的 CDN 包的 <script> 標簽上方。可讀格式的代碼片段如下所示：

if ("Proxy" in window) {
  var handler = {
    get: function(_, key) {
      return new Proxy(function(cb) {
        if (key === "flush" || key === "close") return Promise.resolve();
        if (typeof cb === "function") return cb(window.Sentry);
        return window.Sentry;
      }, handler);
    },
  };
  window.Sentry = new Proxy({}, handler);
}

如果您想直接復制和粘貼代碼段，這里將其 minified：

<script>
  if ("Proxy" in window) {
    var n = {
      get: function(o, e) {
        return new Proxy(function(n) {
          return "flush" === e || "close" === e
            ? Promise.resolve()
            : "function" == typeof n
            ? n(window.Sentry)
            : window.Sentry;
        }, n);
      },
    };
    window.Sentry = new Proxy({}, n);
  }
</script>

直接使用 Client

為了能夠管理多個 Sentry 實例而它們之間沒有任何沖突，您需要創建自己的 Client。 如果您的應用程序集成在其中，這也有助於防止跟蹤任何父應用程序錯誤。在這個例子中，我們使用 @sentry/browser 但它也適用於 @sentry/node。

import { BrowserClient } from "@sentry/browser";

const client = new BrowserClient({
  dsn: "https://[e-mail]/0",
});

client.captureException(new Error("example"));

雖然上面的示例應該可以正常工作，但 Client 上缺少一些方法，如 configureScope 和 withScope，因為 Hub 負責狀態管理。這就是為什么創建新 Hub 並將 Client 綁定到它可能更容易的原因。結果是一樣的，但你也會得到狀態管理。

import { BrowserClient, Hub } from "@sentry/browser";

const client = new BrowserClient({
  dsn: "https://[e-mail]/0",
});

const hub = new Hub(client);

hub.configureScope(function(scope) {
  scope.setTag("a", "b");
});

hub.addBreadcrumb({ message: "crumb 1" });
hub.captureMessage("test");

try {
  a = b;
} catch (e) {
  hub.captureException(e);
}

hub.withScope(function(scope) {
  hub.addBreadcrumb({ message: "crumb 2" });
  hub.captureMessage("test2");
});

處理集成

集成是在 Client 上設置的，如果您需要處理多個 Client 和 Hub，您還必須確保正確進行集成處理。這是一個如何使用多個 Client 和多個運行全局集成的 Hub 的工作示例。

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

// Very happy integration that'll prepend and append very happy stick figure to the message
class HappyIntegration {
  constructor() {
    this.name = "HappyIntegration";
  }

  setupOnce() {
    Sentry.addGlobalEventProcessor(event => {
      const self = Sentry.getCurrentHub().getIntegration(HappyIntegration);
      // Run the integration ONLY when it was installed on the current Hub
      if (self) {
        event.message = `\\o/ ${event.message} \\o/`;
      }
      return event;
    });
  }
}

HappyIntegration.id = "HappyIntegration";

const client1 = new Sentry.BrowserClient({
  dsn: "https://[e-mail]/0",
  integrations: [...Sentry.defaultIntegrations, new HappyIntegration()],
  beforeSend(event) {
    console.log("client 1", event);
    return null; // Returning null does not send the event
  },
});
const hub1 = new Sentry.Hub(client1);

const client2 = new Sentry.BrowserClient({
  dsn: "https://[e-mail]/0", // Can be a different DSN
  integrations: [...Sentry.defaultIntegrations, new HappyIntegration()],
  beforeSend(event) {
    console.log("client 2", event);
    return null; // Returning null does not send the event
  },
});
const hub2 = new Sentry.Hub(client2);

hub1.run(currentHub => {
  // The hub.run method makes sure that Sentry.getCurrentHub() returns this hub during the callback
  currentHub.captureMessage("a");
  currentHub.configureScope(function(scope) {
    scope.setTag("a", "b");
  });
});

hub2.run(currentHub => {
  // The hub.run method makes sure that Sentry.getCurrentHub() returns this hub during the callback
  currentHub.captureMessage("x");
  currentHub.configureScope(function(scope) {
    scope.setTag("c", "d");
  });
});

第三方 Promise 庫

當您包含和配置 Sentry 時，我們的 JavaScript SDK 會自動附加 global handlers 以 capture 未捕獲的 exceptions 和未處理的 promise rejections。 您可以通過在 GlobalHandlers 集成中將 onunhandledrejection 選項更改為 false 並手動掛接到每個事件處理程序，然后直接調用 Sentry.captureException 或 Sentry.captureMessage 來禁用此默認行為。

如果您使用第三方庫來實現 Promise，您可能還需要管理您的配置。 此外，請記住，瀏覽器通常會實施安全措施，在提供來自不同來源的腳本文件時阻止錯誤報告。

具有“非錯誤異常Non-Error Exception”的事件

如果您看到錯誤消息 “Non-Error exception (or promise rejection) captured with keys: x, y, z.”，這會發生在您 a) 使用 plain object 調用 Sentry.captureException() 時，b) 拋出一個 plain object，或者 c) 拒絕一個帶有 plain object 的 promise。

您可以在 “Additional Data” 部分的 __serialized__ 條目中查看有問題的非錯誤對象的內容。

為了更好地了解這些錯誤事件，我們建議根據 __serialized__ 數據的內容找到 plain object 被傳遞或拋出到 Sentry 的位置，然后將 plain object 轉換為 Error 對象。

支持的瀏覽器

Sentry 的 JavaScript SDK 支持以下瀏覽器：

Android	Firefox	Chrome	IE	iPhone	Edge	Safari
4.4	latest	latest	IE 10	iOS12	latest	latest
5.0				IE 11	iOS13
6.0
7.1
8.1
9.0
10.0

支持 <= IE 11

在 5.7.0 版本之前，我們的 JavaScript SDK 需要一些 polyfills 用於舊版瀏覽器，如 IE 11 及更低版本。如果您正在使用它，請在加載我們的 SDK 之前升級到最新版本或添加下面的腳本標簽。

<script src="https://polyfill.io/v3/polyfill.min.js?features=Promise%2CObject.assign%2CString.prototype.includes%2CNumber.isNaN"></script>

我們需要以下 polyfill：

• Promise
• Object.assign
• Number.isNaN
• String.prototype.includes

此外，請記住在 HTML 頁面頂部定義有效的 HTML doctype，以確保 IE 不會進入兼容模式(compatibility mode)。

公眾號：黑客下午茶