All Skills > SDK Setup > 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/ で確認してください。

---

Phase 1: 検出

推奨を行う前にプロジェクトを理解するために、以下のコマンドを実行してください：

# フレームワークのタイプを検出
cat package.json | grep -E '"svelte"|"@sveltejs/kit"|"@sentry/svelte"|"@sentry/sveltekit"'

# SvelteKit のインジケータをチェック
ls svelte.config.js svelte.config.ts vite.config.ts vite.config.js 2>/dev/null

# SvelteKit バージョンをチェック（どのセットアップパターンを使用するかを決定）
cat package.json | grep '"@sveltejs/kit"'

# Sentry がすでにインストールされているかを確認
cat package.json | grep '"@sentry/'

# 既存のフックファイルをチェック
ls src/hooks.client.ts src/hooks.client.js src/hooks.server.ts src/hooks.server.js \
   src/instrumentation.server.ts 2>/dev/null

# ロギングライブラリを検出（Node サイド）
cat package.json | grep -E '"pino"|"winston"|"consola"'

# 隣接するディレクトリにバックエンドがあるかを検出（Go、Python、Ruby など）
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）vs レガシー セットアップ
@sentry/sveltekit がすでに存在？	インストールをスキップ、機能設定に進む
vite.config.ts が存在？	Vite プラグイン経由のソースマップアップロードが利用可能
バックエンドディレクトリが見つかった？	Phase 4 クロスリンク提案をトリガー

---

Phase 2: 推奨

見つかったことに基づいて具体的な推奨を提示します。オープンエンドの質問をしないでください — 提案をリードしてください：

推奨（コア カバレッジ）：

• ✅ エラーモニタリング — 常に；クライアントとサーバー上の未処理エラーを自動キャプチャ
• ✅ トレーシング — SvelteKit はクライアント側ナビゲーション スパンとサーバー側リクエスト スパンの両方を備えています；常に推奨
• ✅ セッションリプレイ — ユーザーに公開される SvelteKit アプリに推奨（クライアント側のみ）

オプション（強化された可観測性）：

• ⚡ ロギング — Sentry.logger.* 経由の構造化ログ；アプリがサーバー側ロギングを使用または ログからトレースへの相関が必要な場合に推奨

推奨ロジック：

機能	推奨される場合...
エラーモニタリング	常に — 交渉の余地がないベースライン
トレーシング	SvelteKit の場合は常に（クライアント + サーバー）；API を呼び出す場合は通常の Svelte の場合
セッションリプレイ	ユーザーに公開されるアプリ、ログインフロー、またはチェックアウトページが存在
ロギング	アプリがすでにサーバー側ロギングを使用、または構造化ログ検索が必要

提案：「エラーモニタリング + トレーシング + セッションリプレイのセットアップを推奨します。構造化ロギングも追加しますか？」

---

Phase 3: ガイド

セットアップ パスを決定

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

---

Path 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 — サーバー側初期化（スタートアップ時に 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,    // 本番環境では 0.1–0.2 に低下
  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() は受信リクエストをインストルメント化し、ルート スパンを作成します
export const handle = Sentry.sentryHandle();

// 他の handle 関数がある場合は、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 は 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

---

Path B: SvelteKit レガシー （<2.31.0 または @sentry/sveltekit <10.8.0）

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

// src/hooks.server.ts (レガシー — 初期化はここに行く)
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 はモダン パスと同じです。

---

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

---

同意した各機能について

機能を 1 つずつ進めます。参照ファイルをロード、その手順に従い、移動する前に検証します：

機能	参照	ロードする場合...
エラーモニタリング	${SKILL_ROOT}/references/error-monitoring.md	常に（ベースライン）
トレーシング	${SKILL_ROOT}/references/tracing.md	API 呼び出し / 分散トレーシングが必要
セッションリプレイ	${SKILL_ROOT}/references/session-replay.md	ユーザーに公開されるアプリ
ロギング	${SKILL_ROOT}/references/logging.md	構造化ログ / ログからトレースへの相関

各機能について: ${SKILL_ROOT}/references/<feature>.md を読み、手順に従い、動作を検証してください。

---

SvelteKit ファイル サマリー

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

---

設定リファレンス

キー Sentry.init() オプション

オプション	タイプ	デフォルト	備考
dsn	string	—	必須。 env 変数を使用；空の場合、SDK は無効
environment	string	"production"	例："staging"、"development"
release	string	—	例："my-app@1.2.3" または 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	プロセス終了前にイベントをフラッシュする ms 数（デフォルト: 2000）

アダプター互換性

アダプター	サポート
@sveltejs/adapter-auto / adapter-vercel (Node)	✅ 完全
@sveltejs/adapter-node	✅ 完全
@sveltejs/adapter-cloudflare	⚠️ 部分的 — 追加セットアップが必要
Vercel Edge Runtime	❌ サポート対象外

---

検証

セットアップ後、Sentry がデータを受信していることを確認するためにテスト イベントをトリガーします：

<!-- src/routes/sentry-test/+page.svelte -->
<script>
  import * as Sentry from "@sentry/sveltekit";
</script>

<button onclick={() => { throw new Error("Sentry client test"); }}>
  クライアント エラーをテスト
</button>

<button onclick={() => Sentry.captureMessage("Sentry test message", "info")}>
  メッセージをテスト
</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 出力を確認してください。

---

Phase 4: クロスリンク

Svelte/SvelteKit セットアップを完了した後、Sentry カバレッジが不足している同じバックエンドをチェックします：

# 隣接するディレクトリでバックエンドを探す
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 エラー	これらはレガシー ラッパー — 削除してください；sentryHandle() は ≥10.8.0 で load 関数を自動的にインストルメント化