boristane/logging-best-practices

logging-best-practices は何をしますか？

ログベストプラクティス：ワイドイベント（カノニカルログ行）に焦点を当て、強力なデバッグと分析を実現します。

概要

このスキルは、アプリケーションログの品質を向上させるための実践的なガイドです。ワイドイベント（カノニカルログ行） を活用することで、各処理のコンテキストを一つのログ行に集約し、可観測性を高めます。

目的

• デバッグの効率化：問題発生時に必要な情報を即座に取得
• 分析の強化：構造化されたデータにより、高度なクエリとメトリクス生成が可能
• 運用の負荷軽減：ログ量を適切に管理しつつ、必要な情報を過不足なく記録

主な特徴

• カノニカルログ行: 各リクエストやバッチ処理の開始から終了までを単一のログ行で表現
• ワイドイベント: ユーザーID、レイテンシ、ステータスコードなど、関連するすべてのコンテキストを含む
• 構造化ログ: JSONなどのフォーマットで出力し、機械可読性を確保
• ノイズ削減: 不要なログを排除し、シグナル対ノイズ比を最適化

対象プラットフォーム

• Claude Code
• Cursor
• Codex
• その他AIエージェント

使用方法

1. スキルをインポート
2. コードベースにカノニカルログ行パターンを導入
3. 各トランザクションの開始時にログ行を作成し、終了時にコンテキストを追加
4. ログ基盤（例：Elasticsearch, CloudWatch, Datadog）で分析

例

import logging

logger = logging.getLogger(__name__)

def process_request(user_id, request_data):
    # カノニカルログ行の作成
    canonical_log = {
        "event": "request",
        "user_id": user_id,
        "method": request_data.get("method"),
        "path": request_data.get("path"),
        "status": None,
        "latency_ms": None,
    }
    
    start_time = time.time()
    try:
        # リクエスト処理
        result = handle(request_data)
        canonical_log["status"] = 200
    except Exception as e:
        canonical_log["status"] = 500
        canonical_log["error"] = str(e)
    finally:
        canonical_log["latency_ms"] = (time.time() - start_time) * 1000
        logger.info("Canonical log line", extra=canonical_log)

ベストプラクティス

• ログレベルを適切に設定（INFO, WARNING, ERROR）
• 機密情報（パスワード、トークンなど）はログに含めない
• 一貫したキー名を使用し、分析ツールでの集約を容易にする
• ログの保持期間と量を考慮し、コストを管理する

参考リンク

• カノニカルログ行の解説
• 構造化ログのベストプラクティス

---

このスキルはAIエージェントによる自動生成と改善を想定しています。