api-observability-setup-axiom-pino-sentry

オブザーバビリティのセットアップ（Pino + Axiom + Sentry）

クイックガイド： オブザーバビリティのためのプロジェクト初期セットアップです。pino、next-axiom、@sentry/nextjsをインストールします。AxiomのデータセットとVercelインテグレーションを設定します。SentryのDSNと設定ファイルをセットアップします。next.config.tsをwithAxiomでラップしてから、withSentryConfigでラップします。ランタイムごとのSentry初期化にはinstrumentation.tsを追加します。CIでSENTRY_AUTH_TOKENが設定されていると、ソースマップは自動的にアップロードされます。

---

詳細なリソース：

• コード例については、examples/フォルダーを参照してください：
  • examples/core.md - 依存関係、環境変数、next.config.ts、instrumentation
  • examples/sentry-config.md - Sentry設定ファイル（クライアント、サーバー、エッジ）
  • examples/pino-logger.md - リダクションを使ったPinoロガーのセットアップ
  • examples/axiom-integration.md - Web Vitalsとダッシュボードのクエリ
  • examples/ci-cd.md - GitHub Actionsによるソースマップのアップロード
  • examples/health-check.md - ヘルスチェックエンドポイント
• 判断フレームワークとアンチパターンについては、reference.mdを参照してください

---

<critical_requirements>

重要：このスキルを使用する前に

すべてのコードは、CLAUDE.mdのプロジェクト規約に従う必要があります（kebab-case、名前付きエクスポート、インポート順序、import type、名前付き定数）

（環境ごとに個別のAxiomデータセットを必ず作成してください。development、staging、production用です）

（Sentryの設定ファイル3つすべてを必ず設定してください。sentry.client.config.ts、sentry.server.config.ts、sentry.edge.config.tsです）

（ソースマップのアップロードを必ずCI/CDに追加してください。読みやすいスタックトレースにはSentryのソースマップが必要です）

（pino-prettyはdevDependencyとしてのみ必ずインストールしてください。本番環境では使用しないでください）

</critical_requirements>

---

自動検出： pino、next-axiom、@sentry/nextjs、Axiom、Sentry、オブザーバビリティのセットアップ、ロギングのセットアップ、エラートラッキングのセットアップ、ソースマップ、sentry.client.config、sentry.server.config、sentry.edge.config、withAxiom、withSentryConfig

使用する場合：

• ロギングとエラートラッキングが必要な新規プロジェクトをセットアップするとき
• オブザーバビリティが未導入の既存プロジェクトに追加するとき
• 別のロギング／エラートラッキングソリューションからAxiom + Sentryに移行するとき

使用しない場合：

• 既存コードに新しいログ文を追加するとき（継続的な使用であり、初期セットアップではありません）
• 初期セットアップ後にアラート、モニター、ダッシュボードを設定するとき
• 既存のオブザーバビリティを使って本番環境の問題をデバッグするとき

対象となる主なパターン：

• 依存関係のインストール（Pino、next-axiom、@sentry/nextjs、pino-pretty）
• 環境変数のテンプレート（.env.example）
• withAxiom()およびwithSentryConfig()ラッパーを使ったnext.config.ts
• Sentry設定ファイル（クライアント、サーバー、エッジ）
• Sentryの初期化用instrumentation.ts
• ソースマップのアップロード用GitHub Actions
• 開発／本番モードのPinoロガー
• ヘルスチェックエンドポイント
• Axiomの初期ダッシュボード設定

---

基本方針

本番アプリにオブザーバビリティは不可欠です。 ロギングとエラートラッキングがなければ、本番環境の問題のデバッグは当てずっぽうになります。Pino + Axiom + Sentryのスタックが提供する機能は次のとおりです：

• Pino：高速な構造化JSONロギング（Winstonの5倍高速）
• Axiom：Vercelインテグレーションによるログ、トレース、メトリクスの統合
• Sentry：ソースマップとリリース追跡に対応したエラートラッキング

このスキルの対象は初期セットアップのみです。 継続的な使用パターン（ログレベル、構造化フィールド、相関ID、アラート設定）については、オブザーバビリティの使用スキルを利用してください。

---

基本パターン

パターン 1：依存関係のインストール

すべてのオブザーバビリティパッケージを、適切な依存関係の種類でインストールします。

# Production dependencies
npm install pino next-axiom @sentry/nextjs

# Development dependencies (pretty printing for local dev)
npm install -D pino-pretty

理由： pino-pretty を devDependency にすることで、本番バンドルの肥大化（約 500KB）を防ぎます。すべてのコアパッケージは、実行時に使用するため本番依存関係にします。

適切な例と不適切な例を比較した詳細なコード例については、examples/core.md を参照してください。

---

パターン 2：環境変数のテンプレート

必要なオブザーバビリティ変数をすべて記載した .env.example を作成します。サービスごとにグループ化し、各値の取得場所をコメントで説明して、環境ごとに別々のデータセットを使用します。

必要な主な変数：

• NEXT_PUBLIC_AXIOM_DATASET - データセット名（例：myapp-dev、myapp-prod）
• NEXT_PUBLIC_AXIOM_TOKEN - 取り込み権限を持つ API トークン
• NEXT_PUBLIC_SENTRY_DSN - プロジェクト設定にある Sentry DSN
• SENTRY_AUTH_TOKEN - CI でソースマップをアップロードするためのトークン
• SENTRY_ORG / SENTRY_PROJECT - 組織とプロジェクトのスラッグ

すべての変数を含む完全なテンプレートについては、examples/core.md を参照してください。

---

パターン 3：withAxiom と withSentryConfig を使用した next.config.ts

Next.js の設定を withAxiom でラップしてロギングを統合し、その後 withSentryConfig でラップしてソースマップを処理します。

主な設定ポイント：

• 最初に withAxiom でラップし（内側）、Sentry で外側をラップします
• silent: !process.env.CI により、ローカルでのソースマップアップロードログを抑制します
• v9 以降では、ソースマップはデフォルトで非表示です（hideSourceMaps は不要）
• アップロード後にクリーンアップするには、sourcemaps.deleteSourcemapsAfterUpload を使用します

import { withSentryConfig } from "@sentry/nextjs";
import { withAxiom } from "next-axiom";

const nextConfig = {
  /* your config */
};

export default withSentryConfig(withAxiom(nextConfig), {
  org: process.env.SENTRY_ORG,
  project: process.env.SENTRY_PROJECT,
  authToken: process.env.SENTRY_AUTH_TOKEN,
  silent: !process.env.CI,
});

完全な設定例については、examples/core.md を参照してください。

---

パターン 4：Sentry 設定ファイル

クライアント、サーバー、エッジの各ランタイム用に、3 つすべての Sentry 設定ファイルを作成します。

必須ファイル：

• sentry.client.config.ts - リプレイ統合を含むクライアント側の設定
• sentry.server.config.ts - ローカル変数の取得を含むサーバー側の設定
• sentry.edge.config.ts - 機能が制限されたエッジランタイムの設定

主な考慮事項：

• サンプルレートには名前付き定数を使用します
• 環境に応じた設定（デバッグモード、サンプルレート）を行います
• beforeSend で想定内のエラーをフィルタリングします
• v9 以降では、hideSourceMaps と enableTracing は削除され、ソースマップはデフォルトで非表示です

完全なファイルテンプレートについては、examples/sentry-config.md を参照してください。

---

パターン 5：Instrumentation ファイル

Next.js で Sentry を適切に初期化するため、instrumentation.ts を作成します。動的インポートを使用して、各ランタイムに適した設定を読み込みます。

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

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./sentry.server.config");
  }

  if (process.env.NEXT_RUNTIME === "edge") {
    await import("./sentry.edge.config");
  }
}

// Next.js 15+ error handling hook
export const onRequestError = Sentry.captureRequestError;

理由： 動的インポートにより、ランタイムに適さない設定の読み込みを防ぎます。onRequestError フックは、Server Component のエラーを自動的に捕捉します（Next.js 15 以降）。

---

パターン 6：Web Vitals コンポーネント

ルートレイアウトに <AxiomWebVitals /> コンポーネントを追加し、Core Web Vitals（LCP、INP、CLS）を Axiom に自動報告します。

注： Web Vitals が送信されるのは本番環境へのデプロイ時のみで、ローカル開発時には送信されません。

実装例については、examples/axiom-integration.md を参照してください。

---

パターン 7：GitHub Actions によるソースマップのアップロード

デプロイ時にソースマップを Sentry にアップロードするよう、CI/CD を設定します。主な要件：

• ビルド環境に SENTRY_AUTH_TOKEN を設定すると、自動アップロードが有効になります
• リリースの作成には getsentry/action-release@v3 を使用します
• リリースを追跡できるよう、バージョンを git SHA に紐付けます

完全なワークフローテンプレートについては、examples/ci-cd.md を参照してください。

---

パターン 8：ヘルスチェックエンドポイント

オブザーバビリティスタックと連携するヘルスチェックエンドポイントを追加します。

• 浅いチェック - ロードバランサーのプローブに適した高速な応答です。Sentry のリリースとの相関付けに使うバージョンを含みます。
• 詳細なチェック - 依存関係を検証し、失敗を Pino 経由でログに記録して、Axiom ダッシュボードで確認できるようにします。

実装例については、examples/health-check.md を参照してください。

---

パターン 9：Pino ロガーのセットアップ

開発モードと本番モードで Pino を設定します。

• 開発：人が読みやすい出力にするため pino-pretty を使用します。
• 本番：ログ集約への取り込み用に JSON を使用します。
• 各ログにコンテキスト用の基本フィールドを含めます。
• 機密フィールドをマスキングします。

設定の詳細については、examples/pino-logger.md を参照してください。

---

パターン 10：Axiom ダッシュボードのセットアップ

セットアップ後、Axiom で初期ダッシュボードを作成します。

• 1 分あたりのリクエスト数
• エラー率
• 応答時間の P95
• 上位のエラー
• Web Vitals のメトリクス

APL クエリの例については、examples/axiom-integration.md を参照してください。

---

<decision_framework>

判断フレームワーク

判断ツリーの全容については、reference.md を参照してください。

• ログの送信先：各環境でログを送信する場所
• エラーに関する Sentry と Axiom の使い分け：各エラー種別を処理するシステム

</decision_framework>

---

<red_flags>

要注意事項

全項目については、reference.md を参照してください。

優先度：高

• Axiom トークンまたは Sentry DSN をバージョン管理にコミットする
• 本番環境で pino-pretty を使用する
• CI でソースマップのアップロードが欠落している
• すべての環境で同じ Axiom データセットを使用する

よくある間違い

• next.config.ts を withAxiom でラップし忘れる
• instrumentation.ts が欠落している
• 削除された Sentry オプション（hideSourceMaps、enableTracing、disableServerWebpackPlugin）を使用する
• 名前付き定数ではなく、サンプルレートをハードコードする

</red_flags>

---

<critical_reminders>

重要な注意事項

すべてのコードは CLAUDE.md のプロジェクト規約に従う必要があります

（環境ごとに個別の Axiom データセット（development、staging、production）を必ず作成してください）

（Sentry の設定ファイル 3 つ（sentry.client.config.ts、sentry.server.config.ts、sentry.edge.config.ts）をすべて必ず設定してください）

（CI/CD にソースマップのアップロードを必ず追加してください。読み取り可能なスタックトレースには Sentry のソースマップが必要です）

（pino-pretty は devDependency としてのみ必ずインストールしてください。本番環境では絶対に使用しないでください）

これらのルールに従わないと、ログの欠落、判読できないエラー、セキュリティ上の脆弱性が発生します。

</critical_reminders>