Logging observability
Skill goonobu-dot/dev-skills-library/skills/logging-observability
15 auto-selectable Claude Code skills distilling engineering best practices (Kent Beck, Fowler, Google SRE, OWASP, Anthropic, Netflix…), with a bilingual offline learning site. Make Claude Code write better code — and learn the practices yourself.
npx -y skills add goonobu-dot/dev-skills-library --skill logging-observabilityAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- 29 days oldThe repository was created 29 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
- 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Logging and observability conventions: log level policy, structured logging, what to log at boundaries, never logging secrets/PII. Use when adding logging statements, designing error reporting/monitoring, replacing console.log/print debugging, or when the user says ログ, 監視, 障害調査の記録, ログレベル. Not for the act of debugging a specific bug (use systematic-debugging) or for general error-handling design (use error-handling-robustness).
SKILL.md
6.8 KB, as published. Nobody here has run it
Logging & Observability
本番運用を見据えたログ設計・実装のためのスキル。「何を」「どのレベルで」「どう構造化して」残すかを判断する。バグそのものの調査手順は systematic-debugging、エラー処理の設計は error-handling-robustness を使う。
使うタイミング
- 新機能にログを追加するとき
console.log/printによるデバッグ出力を本番コードに残さないよう置き換えるとき- 障害調査・監視のためのログ設計をレビューするとき
- ログに機密情報が混入していないか点検するとき
手順
ステップ1：ログレベルを正しく選ぶ
| レベル | 使う場面 |
|---|---|
| ERROR | 処理が失敗し、人間の対応が必要な事象（リトライで回復しない外部障害、想定外の例外） |
| WARN | 処理は継続できるが注意が必要な事象（リトライ発生、フォールバック使用、非推奨API使用） |
| INFO | ビジネス上意味のある通常イベント（リクエスト受付、ジョブ開始/終了、状態遷移） |
| DEBUG | 開発時のみ必要な詳細情報。本番ではデフォルト無効にする |
判断基準：「このログを見た運用担当者がすぐアクションを取るべきか」でERROR/WARNを分け、「後から障害調査で必要になりそうか」でINFO/DEBUGを分ける。
ステップ2：構造化ログにする
- 本番コードから
console.log/printを排除し、構造化ロガー（例：winston, structlog, zerolog等プロジェクトの標準）を採用する。 - ログは自由記述の文字列ではなく、キー・バリューのフィールドとして出力する（例：
{event: "order_created", order_id: "ord_123", user_id: "usr_456", duration_ms: 42}）。文字列連結でメッセージを組み立てない。 - 全ログにタイムスタンプ・ログレベル・リクエストID（トレースID）を必須フィールドとして付与し、1つのリクエストのログを横断的に追跡できるようにする。
- ログローテーション・保持期間を運用要件として明示的に設定する（無制限に溜め続けない）。
ステップ3：境界（バウンダリ）で何を残すかを決める
以下の境界を通過する箇所には最低限のログを入れる。
- 外部APIへのリクエスト／レスポンス（成功・失敗・レイテンシ）
- DBへの書き込み系操作の成否
- 認証・認可の成否（誰が・何に・成功/失敗したか）
- 非同期ジョブ・キューの開始/完了/失敗
- リトライ・フォールバックが発動した瞬間（WARNレベル）
逆に、境界を通過しない内部の細かい処理（ループの1イテレーションごと等）をINFOで出さない。ノイズになり本当に重要なログが埋もれる。
ステップ4：秘密情報・PIIを絶対にログへ出さない
実装中・レビュー中に必ずチェックする。
- パスワード、APIキー、トークン、Cookie、セッションIDをそのまま出力していないか
- クレジットカード番号、マイナンバー等の機微情報を出力していないか
- 氏名・メールアドレス・電話番号等のPIIを出す必要がある場合、マスキング（例：
u***@example.com）またはハッシュ化しているか - エラーオブジェクトを丸ごとログに出すとき、内部に機密情報（リクエストヘッダのAuthorization等）が含まれていないか確認したか
- ログ出力用のフィールドをホワイトリスト方式で選び、オブジェクト全体を
JSON.stringify的にダンプしていないか
判断基準：「このログが第三者に漏洩したとき、何か悪用できる情報が含まれるか」を自問する。含まれるなら出力しない。
ステップ5：エラーログの中身を実行可能にする
- エラーログには「何が」「なぜ」失敗したかに加え、対処のヒント（どの入力・どの依存先が問題だったか）を含める。
- スタックトレースは本番でも記録する（ユーザーには見せないが、ログには残す）。
- 同一エラーが連発する場合に備え、エラーの発生箇所を一意に特定できるフィールド（エラーコード、発生関数名）を付与する。
チェックリスト（実装・レビュー時）
-
console.log/printによるデバッグ出力が本番コードに残っていないか - ログレベルが「アクションの緊急度」に応じて正しく選ばれているか
- 構造化（キー・バリュー）形式で出力しているか
- リクエストID等でログを横断追跡できるか
- 秘密情報・PIIが平文で出力されていないか
- ログローテーション・保持期間が設定されているか
アンチパターン集
| アンチパターン | 現実 |
|---|---|
| すべてをINFOまたはERRORで出す | 本当に対応が必要なログが埋もれ、アラート疲れ（alert fatigue）を招く |
デバッグ用のconsole.logをそのまま本番に残す | 構造化されておらず検索・集計できない。本番のログ基盤に混入するとノイズになる |
| エラーオブジェクトを丸ごとダンプする | リクエストヘッダやトークンが誤って漏洩するリスクがある。フィールドを選んで出力する |
| ユーザーのメールアドレス・氏名を平文でログに残す | PII漏洩リスク。マスキングかハッシュ化が必要 |
| ログにトレースIDを付けない | 1つのリクエストが複数サービス・複数行のログにまたがったとき、追跡できず障害調査が長引く |
| 「後で見返すかもしれない」で全部DEBUGログを本番でも有効にする | ログ量が肥大化しストレージコストと検索性能を悪化させる。本番はデフォルト無効にする |
出典
- elsewhencode/project-guidelines（MIT License）— 構造化ロガー採用、
console.log排除、ログローテーションの方針を要約。