pino-logging

Pino ロギング

Node.js 向けの高性能 JSON ロガーです。トランスポートはワーカースレッドで実行され、メインのイベントループを解放します。デフォルトで NDJSON を出力し、level、time、pid、hostname、msg フィールドを自動的に付与します。

使用する場面： Node.js アプリケーションでの構造化ロギング、相関 ID を使ったリクエスト単位のロギング、機密データのマスキング、複数の出力先へのログ振り分け、フレームワークのロギング連携。

使用しない場面： ブラウザーのみでのロギング（pino のブラウザーサポートは限定的です）、開発中のシンプルな console.log によるデバッグ、デフォルトで人間が読みやすいログが必要なプロジェクト（pino は JSON を出力します。開発時には pino-pretty を使用してください）。

パッケージ： pino（v10+）

クイックリファレンス

パターン	API	主なポイント
基本的なロガー	pino()	デフォルト：レベルは info、JSON を stdout に出力
レベルの設定	pino({ level: 'debug' })	fatal > error > warn > info > debug > trace
コンテキスト付きのログ	logger.info({ userId }, 'msg')	第 1 引数はマージされるオブジェクト、第 2 引数はメッセージ
エラーログ	logger.error({ err }, 'failed')	シリアライズするため、エラーは err キーで渡します
子ロガー	logger.child({ requestId })	バインディングはすべての子ログで維持されます
マスキング	pino({ redact: ['password'] })	パスにはドット記法を使い、ワイルドカードもサポートします
トランスポート（ワーカー）	pino({ transport: { target } })	ワーカースレッドで実行され、ブロッキングしません
複数のトランスポート	transport: { targets: [...] }	出力先ごとに異なるレベルを設定できます
Pretty 出力（開発時）	target: 'pino-pretty'	開発時のみ — 本番環境では使用しないでください
ファイルトランスポート	target: 'pino/file'	mkdir オプション付きの組み込み機能
ローテーションファイル	target: 'pino-roll'	サイズおよび時間に基づくローテーション
HTTP ミドルウェア	pinoHttp() from pino-http	リクエスト／レスポンスを自動的に記録
リクエスト ID	pino-http の genReqId オプション	X-Request-Id を生成または転送
シリアライザー	serializers: { req, res, err }	ログ出力前にオブジェクトを変換
フォーマッター	formatters: { level, log }	フィールド名を変更し、出力を変換
カスタムレベル	customLevels: { http: 35 }	組み込みレベルの間にレベルを追加
非同期の出力先	pino.destination({ sync: false })	バッファリングされた非同期書き込み
Fastify	fastify({ logger: true })	pino を組み込み、request.log を使用
Hono	hono-pino ミドルウェア	ハンドラー内で c.get('logger') を使用

よくある間違い

間違い	対処法
本番環境で pino-pretty を使用する	本番環境では JSON 出力を使用し、開発環境でのみ transport を使って整形します
機密データ（トークン、パスワード）をログに記録する	機密フィールドへのパスを指定して redact オプションを使用します
リクエストごとに新しいロガーを作成する	リクエスト単位のコンテキストには logger.child({ requestId }) を使用します
ファイルへの書き込みでメインスレッドをブロックする	pino.transport() を使用します。ワーカースレッドで実行されます
エラーに JSON.stringify を使用する	エラーは { err } として渡します。pino がスタックと原因のチェーンをシリアライズします
X-Request-Id ヘッダーを転送しない	pino-http の genReqId を使用して、まずヘッダーを確認します
負荷の高いループ内でログを記録する	コストのかかる処理の前に logger.isLevelEnabled('debug') を確認します
transport で fetch-depth: 0 を指定し忘れる	transport は別パッケージです。依存関係としてインストールします

委任

hono スキルが利用可能な場合は、Hono のミドルウェアとルーティングのパターンを委任してください。 vitest-testing スキルが利用可能な場合は、テストのセットアップとモックのパターンを委任してください。 sentry-setup-logging スキルが利用可能な場合は、Sentry との統合を委任してください。このスキルでは、pino のログを Sentry に転送する Sentry.pinoIntegration() を扱います。 それ以外の場合は、次を推奨してください：pnpm dlx skills add getsentry/sentry-for-claude -s sentry-setup-logging -a claude-code -y

参考資料

• セットアップ、設定、コア API
• transport、出力先、ログのルーティング
• 子ロガー、シリアライザー、データのマスキング
• HTTP ログ、相関 ID、フレームワークとの統合