evlog

evlog

evlog に関わる作業（ワイドイベント、構造化エラー、ドレイン、サンプリング、監査証跡、AI SDK / eve テレメトリー、CLI プロダクトテレメトリー、クライアントロギング、プラグイン、@evlog/cli map のカバレッジスコアリングなど）では、このスキルを使用してください。

スナップショット：[email protected]、@evlog/[email protected]、@evlog/[email protected]（2026-10-01 に確認済み。これより新しいリリースはありません）。バージョンが異なる場合は、source-map.md を参照して最新情報を取得してください。

ワークフロー

1. コードを変更する前に、ローカルのロギング環境を確認します。
   • 使用中の evlog、任意の @evlog/cli / @evlog/telemetry / @evlog/nuxthub、フレームワークのピア依存関係、ドレイン先のパッケージバージョン。
   • 統合経路：Nuxt/Nitro モジュール、Next の createEvlog / withEvlog、TanStack Start の evlog/nitro/v3、Hono/Express/Fastify/Elysia ミドルウェア、Workers、Astro/Lambda ガイド、単独の initLogger。
   • パターン：散在する console / pino の行と log.set ワイドイベントのどちらを使っているか、createError({ why, fix })、監査、AI ラッパー、eve フック、クライアント取り込み、プラグイン。
2. バージョンや API が不明な場合は、ドキュメントを更新します。source-map.md から始めてください。
3. インストール、3 つのロギングモード、initLogger、コア API については、setup-core.md を参照してください。
4. ワイドイベントの設計、封印／fork、構造化エラー、カタログ、編集については、wide-events-errors.md を参照してください。
5. フレームワークとの接続とアダプターの選択については、frameworks-adapters.md を参照してください。
6. パイプライン、サンプリング、監査、AI、クライアントログ、evlog map / CI については、cli-advanced.md を参照してください。
7. プラグイン、ストリーム、診断、ツールキット、@evlog/telemetry、evlog/eve については、extend.md を参照してください。

実装時の判断

• 同じリクエスト／ジョブ／ターン内で多数の info 行を出すのではなく、作業単位ごとに 1 つのワイドイベント（log.set の後に自動 emit、または手動 emit）を優先してください。
• コンテキストは、意味のあるキーを使ってネストしたオブジェクト（user、cart、payment）にまとめます。userId / cartId のようなフラットな値の羅列や、汎用的な data の入れ物は避けてください。
• 適切なモードを使います。単発処理には log.*、ライフサイクルを管理する場合は createLogger / createRequestLogger、ミドルウェアが生成と送信を管理する場合はフレームワークの useLogger / req.log / c.get('log') を使います。
• タグ付きの log.info('tag', 'message') は、pretty モードではコンソールにのみ出力されます。オブジェクト形式は常にドレインに送信されます。
• 単独の Error ではなく、createError({ message, status, why, fix, link?, code?, internal? }) をスローしてください。クライアント側では parseError で解析します。
• emit 後（またはサンプリングによる破棄後）は、ロガーが 封印 され、レスポンス後の set は無視されます。意図的なバックグラウンドの子イベントには、利用可能な場合は log.fork を使います。
• ライブラリや共有パッケージでは、createLogger を使うかロガーを受け取るようにします。ホスト側で initLogger を呼び出してドレインを強制しては いけません。
• 本番環境では、アダプターを createDrainPipeline（バッチ処理 + 再試行）でラップし、ヘッドサンプリングとテールサンプリングを有効にします。エラーと金銭／認証関連の経路は保持してください。
• Nuxt/Nitro/Next/TanStack Start/Hono では、大規模なロギングのリファクタリングを行う前に bunx @evlog/cli map を実行してください。FIX FIRST を最初に修正します。CI では CLI のバージョンを固定してください。

検証

リポジトリに既存のチェックがあれば、それを優先してください。重要な evlog の変更では、関連する項目を実施してください。

• ローカルでルート／ジョブを実行し、期待するネストフィールドを含むワイドイベントが 1 つ 出力されることを確認します（開発時は pretty 表示）。
• createError の経路を強制的に通し、ログ内の why / fix と、クライアント側の parseError を確認します。
• エントリーポイントのカバレッジやセットアップを変更する場合は、bunx @evlog/cli map / doctor を実行します。
• パイプラインの変更時はドレインのスモークテスト（Axiom/Sentry/Loki/fs NDJSON）を行い、シャットダウン時にフラッシュします。
• サンプリング設定を確認します。本番相当の設定でもエラーと keep ルールが保持されることを確認します。
• RequestLogger、型付きフィールド、カタログのインポートを型チェックします。