Shared Environments _ Browser Extensions.ja.md

https://docs.sentry.io/platforms/javascript/best-practices/shared-environments/

以下は、Sentry公式ドキュメント 「Sentry JavaScript SDK の Shared Environments ベストプラクティス」の内容を、日本語で整理したMarkdown形式の要約です。

---

Sentry JavaScript: Shared Environments ベストプラクティス（和訳まとめ）

概要

共有環境（Shared Environments）とは、同一の実行環境内で複数のSentryインスタンスが動作するケースを指します。(docs.sentry.dev)

該当する例

• ブラウザ拡張
• VSCode拡張
• サードパーティウィジェット
• プラグインアーキテクチャ
• ライブラリ
• その他、複数のSentryが同時に動く環境

👉 このような環境では、通常の初期化方法では問題が発生する可能性があります。

---

⚠️ やってはいけないこと

Sentry.init() を使わない

共有環境では Sentry.init() は グローバル状態を汚染するため非推奨です。(docs.sentry.dev)

問題例

• 拡張機能のイベントがWebサイトのSentryに送信される
• 逆にWebサイトのエラーが拡張のSentryに送信される
• データリークやノイズ増加

---

✅ 推奨アプローチ

1. Client を手動で作成する

import {
  BrowserClient,
  defaultStackParser,
  getDefaultIntegrations,
  makeFetchTransport,
  Scope,
} from "@sentry/browser";

const integrations = getDefaultIntegrations({}).filter(
  (integration) =>
    !["BrowserApiErrors", "Breadcrumbs", "GlobalHandlers"].includes(
      integration.name
    )
);

const client = new BrowserClient({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  transport: makeFetchTransport,
  stackParser: defaultStackParser,
  integrations,
});

const scope = new Scope();
scope.setClient(client);

client.init();

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

👉 ポイント：

• グローバルではなく ローカルなClient + Scope を使う
• 自前で管理することで衝突を防ぐ

---

2. グローバル依存の Integration を避ける

特に以下はNG：

• Breadcrumbs
• GlobalHandlers
• BrowserApiErrors

👉 理由：

• グローバルイベント（window, console など）をフックするため
• 他のSentryインスタンスと干渉する (docs.sentry.dev)

---

3. Integration を使わず手動送信を基本にする

共有環境では以下が推奨：

try {
  // 処理
} catch (error) {
  scope.captureException(error);
}

👉 「自動収集」ではなく「明示的に送信」する設計にする (docs.sentry.dev)

---

⚠️ エラーが送信されない場合

Inbound Filters の影響

ブラウザ拡張由来のエラーはフィルタされる場合あり

対処

• Project Settings → Inbound Filters を確認
• 必要に応じて無効化 (docs.sentry.dev)

---

⚙️ SDKの挙動に関する補足

Browser Extension 判定の回避（例外的ケース）

Sentry.init({
  dsn: "...",
  skipBrowserExtensionCheck: true,
});

👉 ただし通常は使用しない

理由：

• 問題の回避ではなく「検出の無効化」だけ
• データ混在・ノイズ増加のリスクあり (docs.sentry.dev)

---

📌 ベストプラクティスまとめ

• ❌ Sentry.init() は使わない（共有環境では）
• ✅ BrowserClient + Scope を手動構築
• ❌ グローバルIntegrationは使わない
• ✅ エラーは明示的に captureException
• ⚠️ フィルタ設定でイベントが消える可能性あり

---

💡 補足（設計観点）

共有環境ではSentryは以下のように考えると良いです：

観点	推奨
スコープ	ローカルに閉じる
エラー収集	明示的
Integration	最小限 or なし
依存	グローバル非依存

---