sentry-svelte-sdk

すべてのスキル > SDK のセットアップ > 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）に基づいています。 実装前に、必ず docs.sentry.io/platforms/javascript/guides/sveltekit/ で確認してください。

---

フェーズ 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（手動セットアップ）に進んでください。

オプション 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 — サーバー側の初期化（起動時に一度実行）

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

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

  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/guides/sveltekit/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
  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,

  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/guides/sveltekit/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
  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 レガシー版（<2.31.0 または @sentry/sveltekit <10.8.0）

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

// 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,

  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/guides/sveltekit/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },

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

---

合意した各機能について

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

機能	リファレンス	読み込むタイミング
エラーモニタリング	${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 を実行し、手順に正確に従って、動作を検証します。

---

設定リファレンス

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

オプション	型	デフォルト	備考
dsn	string	—	必須。 環境変数を使用します。空の場合、SDK は無効になります
environment	string	"production"	例："staging"、"development"
release	string	—	例："[email protected]" または Git SHA
dataCollection	object	—	収集するデータを制御します（userInfo、cookies、headers など）
dataCollection.userInfo	boolean	true	計装から user.* フィールドを自動入力します
dataCollection.cookies	boolean|object	true	Cookie の収集とフィルタリング
dataCollection.httpHeaders	object	{request: true, response: true}	リクエスト／レスポンスの HTTP ヘッダーを収集します
dataCollection.httpBodies	string[]	["incomingRequest", "outgoingRequest", "incomingResponse", "outgoingResponse"]	収集する HTTP ボディの種類
dataCollection.queryParams	boolean|object	true	クエリパラメーターの収集とフィルタリング
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	❌ 非対応

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 がデータを受信していることを確認します。

<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 が設定されていることを確認します
サーバーのエラーがキャプチャされない	hooks.server.ts から handleErrorWithSentry() がエクスポートされていることを確認します
クライアントのエラーがキャプチャされない	hooks.client.ts から handleErrorWithSentry() がエクスポートされていることを確認します
セッションリプレイが記録されない	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 のエラー	これらはレガシーラッパーです。削除してください。sentryHandle() は ≥10.8.0 で load 関数を自動的に計測します