sentry-svelte-sdk

Sentry Svelte SDK

プロジェクトをスキャンし、Svelte と SvelteKit 向けの Sentry のセットアップを完了できるよう案内する、独自のウィザードです。

このスキルを呼び出すタイミング

• Svelte／SvelteKit アプリに「Sentry を追加」または「Sentry をセットアップ」したいとユーザーが尋ねた場合
• Svelte または SvelteKit でエラー監視、トレーシング、セッションリプレイ、ロギングを利用したい場合
• @sentry/svelte、@sentry/sveltekit、または Svelte 向け Sentry SDK に言及した場合

注： 以下の SDK バージョンと API は、執筆時点の最新の Sentry ドキュメント（@sentry/sveltekit ≥10.8.0、SvelteKit ≥2.31.0）を反映しています。 実装前に必ずドキュメントで確認してください。

---

フェーズ 1：検出

推奨内容を提示する前に、次のコマンドを実行してプロジェクトの状況を把握してください。

# Detect framework type
cat package.json | grep -E '"svelte"|"@sveltejs/kit"|"@sentry/svelte"|"@sentry/sveltekit"'

# Check for SvelteKit indicators
ls svelte.config.js svelte.config.ts vite.config.ts vite.config.js 2>/dev/null

# Check SvelteKit version (determines which setup pattern to use)
cat package.json | grep '"@sveltejs/kit"'

# Check if Sentry is already installed
cat package.json | grep '"@sentry/'

# Check existing hook files
ls src/hooks.client.ts src/hooks.client.js src/hooks.server.ts src/hooks.server.js \
   src/instrumentation.server.ts 2>/dev/null

# Detect logging libraries (Node side)
cat package.json | grep -E '"pino"|"winston"|"consola"'

# Detect if there's a backend (Go, Python, Ruby, etc.) in adjacent directories
ls ../backend ../server ../api 2>/dev/null
cat ../go.mod ../requirements.txt ../Gemfile 2>/dev/null | head -3

確認すること：

質問	影響
package.json に @sveltejs/kit があるか？	SvelteKit 向けか、通常の Svelte 向けかを判断します
SvelteKit ≥2.31.0 か？	モダン（instrumentation.server.ts）か、レガシー設定かを判断します
@sentry/sveltekit がすでにあるか？	インストールを省略し、機能設定に直接進みます
vite.config.ts があるか？	Vite プラグインによるソースマップのアップロードが可能です
バックエンドディレクトリが見つかったか？	フェーズ 4 の関連付けの提案を行います

---

フェーズ 2：提案

確認した内容に基づき、具体的な推奨事項を提示します。自由回答形式の質問はせず、提案から始めてください。

推奨（基本的なカバレッジ）：

• ✅ エラー監視 — 常に推奨します。クライアントとサーバーの未処理エラーを自動で捕捉します
• ✅ トレーシング — SvelteKit ではクライアント側のナビゲーションスパンとサーバー側のリクエストスパンの両方があるため、常に推奨します
• ✅ セッションリプレイ — ユーザー向けの SvelteKit アプリに推奨します（クライアント側のみ）

任意（可観測性の強化）：

• ⚡ ロギング — Sentry.logger.* による構造化ログです。アプリでサーバー側のロギングを使用している場合や、ログとトレースの相関が必要な場合に推奨します

推奨の判断基準：

機能	推奨する条件
エラー監視	常に — 必須の基本機能です
トレーシング	SvelteKit では常に（クライアント＋サーバー）。通常の Svelte では API 呼び出しを行う場合
セッションリプレイ	ユーザー向けアプリ、ログインフロー、またはチェックアウトページがある場合
ロギング	アプリですでにサーバー側のロギングを使用している場合、または構造化ログの検索が必要な場合

次のように提案してください：「エラー監視＋トレーシング＋セッションリプレイのセットアップをおすすめします。構造化ロギングも追加しますか？」

---

フェーズ 3：案内

セットアップ方法の判断

プロジェクト	パッケージ	セットアップの複雑さ
SvelteKit（≥2.31.0）	@sentry/sveltekit	5 ファイルを作成／変更
SvelteKit（<2.31.0）	@sentry/sveltekit	3 ファイル（hooks.server.ts で初期化）
通常の Svelte（@sveltejs/kit なし）	@sentry/svelte	エントリーポイント 1 つ

---

方法 A：SvelteKit（推奨 — モダン、≥2.31.0）

オプション 1：ウィザード（推奨）

npx @sentry/wizard@latest -i sveltekit

ウィザードでは、ログイン、組織／プロジェクトの選択、認証トークンのセットアップを対話形式で進められるため、トークンを手動で作成する必要はありません。その後、SDK をインストールし、必要なファイル（クライアント／サーバーフック、Vite プラグイン設定）をすべて作成して、ソースマップのアップロードを設定し、確認用の /sentry-example-page を追加します。実行後は検証に進んでください。

オプション 2：手動セットアップ

ステップ 1 — インストール

npm install @sentry/sveltekit --save

ステップ 2 — svelte.config.js — インストルメンテーションを有効化

import adapter from "@sveltejs/adapter-auto";

const config = {
  kit: {
    adapter: adapter(),
    experimental: {
      instrumentation: { server: true },
      tracing: { server: true },
    },
  },
};

export default config;

ステップ 3 — src/instrumentation.server.ts — サーバー側の初期化（起動時に 1 回実行）

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

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.SENTRY_ENVIRONMENT,
  release: process.env.SENTRY_RELEASE,

  sendDefaultPii: true,
  tracesSampleRate: 1.0,    // lower to 0.1–0.2 in production
  enableLogs: true,
});

ステップ 4 — src/hooks.client.ts — クライアント側の初期化

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

Sentry.init({
  dsn: import.meta.env.PUBLIC_SENTRY_DSN ?? import.meta.env.VITE_SENTRY_DSN,
  environment: import.meta.env.MODE,

  sendDefaultPii: true,
  tracesSampleRate: 1.0,

  integrations: [
    Sentry.replayIntegration({
      maskAllText: true,
      blockAllMedia: true,
    }),
  ],

  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  enableLogs: true,
});

export const handleError = Sentry.handleErrorWithSentry();

ステップ 5 — src/hooks.server.ts — サーバーフック（モダンな設定ではここで初期化しません）

import * as Sentry from "@sentry/sveltekit";
import { sequence } from "@sveltejs/kit/hooks";

export const handleError = Sentry.handleErrorWithSentry();

// sentryHandle() instruments incoming requests and creates root spans
export const handle = Sentry.sentryHandle();

// If you have other handle functions, compose with sequence():
// export const handle = sequence(Sentry.sentryHandle(), myAuthHandle);

ステップ 6 — vite.config.ts — ソースマップ（SENTRY_AUTH_TOKEN が必要）

import { sveltekit } from "@sveltejs/kit/vite";
import { sentrySvelteKit } from "@sentry/sveltekit";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [
    // sentrySvelteKit MUST come before sveltekit()
    sentrySvelteKit({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
    sveltekit(),
  ],
});

.env に追加します（コミットしないでください）。

SENTRY_AUTH_TOKEN=sntrys_...
SENTRY_ORG=my-org-slug
SENTRY_PROJECT=my-project-slug

---

パス B：SvelteKit Legacy（2.31.0 未満、または @sentry/sveltekit 10.8.0 未満）

instrumentation.server.ts と svelte.config.js の変更はスキップします。代わりに、Sentry.init() を hooks.server.ts に直接記述します：

// src/hooks.server.ts (legacy — init goes here)
import * as Sentry from "@sentry/sveltekit";

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
  enableLogs: true,
});

export const handleError = Sentry.handleErrorWithSentry();
export const handle = Sentry.sentryHandle();

hooks.client.ts と vite.config.ts はモダンパスと同じです。

---

パス C：プレーンな Svelte（SvelteKit なし）

インストール：

npm install @sentry/svelte --save

エントリーポイント（src/main.ts または src/main.js）で、アプリをマウントする前に設定します：

import * as Sentry from "@sentry/svelte";
import App from "./App.svelte";

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN,
  environment: import.meta.env.MODE,

  sendDefaultPii: true,

  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.replayIntegration({
      maskAllText: true,
      blockAllMedia: true,
    }),
  ],

  tracesSampleRate: 1.0,
  tracePropagationTargets: ["localhost", /^https:\/\/yourapi\.io/],
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  enableLogs: true,
});

const app = new App({ target: document.getElementById("app")! });
export default app;

任意：Svelte コンポーネントのトラッキング（すべてのコンポーネントにトラッキングを自動挿入します）：

// svelte.config.js
import { withSentryConfig } from "@sentry/svelte";

export default withSentryConfig(
  { compilerOptions: {} },
  { componentTracking: { trackComponents: true } }
);

---

合意した各機能について

機能を一つずつ確認します。リファレンスファイルを読み込み、手順に従ってから、次に進む前に検証します：

機能	リファレンス	読み込むタイミング
エラーモニタリング	${SKILL_ROOT}/references/error-monitoring.md	常に（基本設定）
トレーシング	${SKILL_ROOT}/references/tracing.md	API 呼び出し／分散トレーシングが必要な場合
セッションリプレイ	${SKILL_ROOT}/references/session-replay.md	ユーザー向けアプリの場合
ロギング	${SKILL_ROOT}/references/logging.md	構造化ログ／ログとトレースの相関が必要な場合

各機能について：Read ${SKILL_ROOT}/references/<feature>.md を読み、手順に厳密に従って、動作を検証します。

---

SvelteKit ファイルの概要

ファイル	用途	モダン	レガシー
src/instrumentation.server.ts	サーバーの Sentry.init() — 起動時に一度実行	✅ 必須	❌
src/hooks.client.ts	クライアントの Sentry.init() ＋ handleError	✅ 必須	✅ 必須
src/hooks.server.ts	handleError ＋ sentryHandle()（init なし）	✅ 必須	✅ ここで init
svelte.config.js	experimental.instrumentation.server を有効化	✅ 必須	❌
vite.config.ts	ソースマップ用の sentrySvelteKit() プラグイン	✅ 推奨	✅ 推奨
.env	SENTRY_AUTH_TOKEN、SENTRY_ORG、SENTRY_PROJECT	✅ ソースマップ用	✅ ソースマップ用

---

設定リファレンス

主な Sentry.init() オプション

オプション	型	デフォルト	備考
dsn	string	—	必須。 環境変数を使用します。空の場合、SDK は無効になります
environment	string	"production"	例："staging"、"development"
release	string	—	例："[email protected]" または git SHA
sendDefaultPii	boolean	false	IP アドレスとリクエストヘッダーを含めます
tracesSampleRate	number	—	0～1。開発環境では 1.0、本番環境では 0.1–0.2 を使用します
tracesSampler	function	—	トランザクションごとのサンプリング。tracesSampleRate を上書きします
tracePropagationTargets	(string|RegExp)[]	—	分散トレーシングヘッダーを送信する URL
replaysSessionSampleRate	number	—	記録する全セッションの割合（クライアントのみ）
replaysOnErrorSampleRate	number	—	記録するエラーセッションの割合（クライアントのみ）
enableLogs	boolean	false	Sentry.logger.* API を有効にします
beforeSendLog	function	—	送信前にログをフィルタリング／変更します
debug	boolean	false	コンソールに詳細な SDK 出力を表示します

サーバー専用オプション（instrumentation.server.ts／hooks.server.ts）

オプション	型	備考
serverName	string	サーバーイベントに付与するホスト名タグ
includeLocalVariables	boolean	スタックフレームにローカル変数を追加します
shutdownTimeout	number	プロセス終了前にイベントをフラッシュするまでの時間（ミリ秒、デフォルト：2000）

アダプターの互換性

アダプター	サポート状況
@sveltejs/adapter-auto / adapter-vercel（Node）	✅ 完全対応
@sveltejs/adapter-node	✅ 完全対応
@sveltejs/adapter-cloudflare	⚠️ 部分対応 — 追加のセットアップが必要
Vercel Edge Runtime	❌ 非対応

---

検証

セットアップ後、テストイベントを発生させ、Sentry がデータを受信していることを確認します。

<script>
  import * as Sentry from "@sentry/sveltekit";
</script>

<button onclick={() => { throw new Error("Sentry client test"); }}>
  Test Client Error
</button>

<button onclick={() => Sentry.captureMessage("Sentry test message", "info")}>
  Test Message
</button>

// src/routes/sentry-test/+server.ts
export const GET = () => {
  throw new Error("Sentry server test");
};

Sentry ダッシュボードを確認します。

• Issues → 両方のエラーが数秒以内に表示されます
• Traces → ルートベースのトランザクションを探します
• Replays → ページを操作した後にセッションの記録が表示されます
• Logs → 構造化ログエントリーが表示されます（ロギングが有効な場合）

何も表示されない場合は、Sentry.init() で debug: true を設定し、ブラウザーまたはサーバーのコンソールで SDK の出力を確認します。

---

フェーズ 4：相互リンク

Svelte/SvelteKit のセットアップが完了したら、Sentry のカバレッジが不足している関連バックエンドがないか確認します。

# Look for backend in adjacent directories
ls ../backend ../server ../api ../go ../python 2>/dev/null
cat ../go.mod 2>/dev/null | head -3
cat ../requirements.txt ../pyproject.toml 2>/dev/null | head -3
cat ../Gemfile 2>/dev/null | head -3

Sentry が設定されていないバックエンドがある場合は、対応するスキルを提案します。

検出されたバックエンド	提案するスキル
Go（go.mod）	sentry-go-sdk
Python（requirements.txt、pyproject.toml）	sentry-python-sdk
Ruby（Gemfile）	sentry-ruby-sdk
Node.js（Express、Fastify など）	@sentry/node を使用します — docs.sentry.io/platforms/javascript/guides/express/ を参照してください

---

トラブルシューティング

問題	解決策
イベントが表示されない	debug: true を設定し、DSN を確認して、ブラウザーのコンソールで SDK のエラーを確認します
ソースマップが機能しない	npm run build を実行します（dev ではなく）。SENTRY_AUTH_TOKEN が設定されていることを確認します
サーバーエラーが捕捉されない	handleErrorWithSentry() が hooks.server.ts からエクスポートされていることを確認します
クライアントエラーが捕捉されない	handleErrorWithSentry() が hooks.client.ts からエクスポートされていることを確認します
セッションリプレイが記録されない	replayIntegration() がクライアントの初期化にのみ含まれていることを確認します（サーバーには含めないでください）
sentryHandle() と他のハンドラーが連結されない	sequence(Sentry.sentryHandle(), myHandle) でラップします
広告ブロッカーによってイベントがブロックされる	tunnel: "/sentry-tunnel" を設定し、サーバー側のリレーエンドポイントを追加します
SvelteKit のインストルメンテーションが有効にならない	svelte.config.js で experimental.instrumentation.server: true が設定されていることを確認します
Cloudflare アダプターの問題	アダプター固有の注意事項について、docs.sentry.io/platforms/javascript/guides/sveltekit/ を参照してください
wrapLoadWithSentry / wrapServerLoadWithSentry のエラー	これらは古いラッパーです。削除してください。≥10.8.0 では sentryHandle() がロード関数を自動的にインストルメントします