add-analytics

検出されたウェブスタックに、イベントトラッキング、エラー監視、ステータスエンドポイントを追加します。

フェーズ 1：スタックを検出する

プロジェクトを読み込み、何をインストールする必要があるか判断します。

1.1 フレームワーク

• next.config.* → Next.js（App Router と Pages Router のどちらかを確認）
• vite.config.* → Vite / React SPA
• astro.config.* → Astro
• nuxt.config.* → Nuxt
• Python バックエンド（main.py、app.py、manage.py）→ FastAPI / Django / Flask

1.2 既存の分析ツール

分析／監視ツールがすでにインストールされているか確認します。

• posthog-js または posthog-node → PostHog 導入済み
• @sentry/nextjs、@sentry/react、または sentry-sdk → Sentry 導入済み
• @vercel/analytics → Vercel Analytics 導入済み
• @google-analytics または gtag → GA 導入済み

すでにインストールされている場合は、新たにインストールするのではなく、設定を監査します。不足している点（エラーバウンダリーがない、サーバーサイドトラッキングがない、ヘルスエンドポイントがないなど）を確認します。

1.3 ユーザーに確認する

Detected: [framework]
Existing analytics: [what's already there, or "none"]

I'll set up:
1. PostHog — event tracking, user identification, feature flags
2. Sentry — error tracking with source maps
3. Health endpoint — /api/status for uptime monitoring

Need your project keys:
- PostHog API key (get from app.posthog.com → Project Settings)
- Sentry DSN (get from sentry.io → Project Settings → Client Keys)

Or I can set up the code and you add the keys later.

フェーズ 2：オブザーバビリティを実装する

このプロジェクトに必要な実装リファレンスのみを読み込みます。

• PostHog 分析： クライアントまたはサーバーのトラッキング、ページビュー、識別、型付きイベントを追加する前に、references/posthog.md を読んでください。
• Sentry エラートラッキング： Sentry、エラーバウンダリー、構造化ログを設定する前に、references/sentry.md を読んでください。
• ヘルスエンドポイント： Next.js または FastAPI のステータスルートと稼働時間監視を追加する前に、references/health-endpoint.md を読んでください。

既存の連携は維持してください。すでにシステムが導入されている場合は、再インストールするのではなく、リファレンスを使って不足している点を監査してください。各例は、検出されたフレームワークと認証方式に合わせてください。

フェーズ 3：環境変数

.env.local（または .env）に追加します。

# PostHog
NEXT_PUBLIC_POSTHOG_KEY=phc_...
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
POSTHOG_API_KEY=phc_...  # Same key, used server-side

# Sentry
NEXT_PUBLIC_SENTRY_DSN=https://[email protected]/456
SENTRY_AUTH_TOKEN=sntrys_...  # For source map uploads
SENTRY_ORG=your-org
SENTRY_PROJECT=your-project

これらが Git にコミットされていないことを確認してください。.gitignore に .env* が含まれているか確認します。

フェーズ 4：検証する

すべてを接続したら、各システムをテストします。

PostHog:
[ ] Open the app → check PostHog dashboard for a pageview event
[ ] Navigate between pages → each page triggers a pageview
[ ] Log in → user appears in PostHog with email/name (identified)
[ ] Track a custom event → appears in PostHog events
[ ] Log out → posthog.reset() called, new anonymous session

Sentry:
[ ] Add a temporary `throw new Error('sentry test')` to a page
[ ] Load the page → error appears in Sentry dashboard
[ ] Check that source maps resolve (you see your actual code, not minified)
[ ] Remove the test error
[ ] Error boundary renders fallback UI (not a white screen)

Health Endpoint:
[ ] GET /api/status returns 200 with uptime and database status
[ ] If database is down, returns 503
[ ] Set up monitoring service to ping it every 5 minutes

どのシステムが稼働し、正常に動作しているかをユーザーに伝えてください。

重要な注意事項

• PostHog の無料プラン： 月間最大 100 万イベントです。利用する前に、現在のプラン上限を確認してください。
• Sentry の無料プラン： 月間最大 5,000 エラーです。利用する前に、現在のプラン上限を確認してください。
• PostHog のイベントで PII をトラッキングしないでください（パスワードやクレジットカード番号は含めないでください）。ユーザー ID とメールアドレスは問題ありません。
• サンプルレートは重要です。 本番環境でトレースを 10％にすれば、コストをほぼゼロに抑えられます。特定の問題をデバッグする場合にのみ引き上げてください。
• ソースマップは Sentry に不可欠です。ソースマップがないと、エラースタックトレースには圧縮されたコードが表示されます。Sentry ウィザードは Next.js のソースマップを処理します。それ以外のフレームワークでは、ビルド時にマップをアップロードしてください。