mcpField
L
logging-best-practices

logging-best-practices

github.com/ncklrs開発53140 回インストール35 週間前に更新
リポジトリ

logging-best-practices について

開発・運用チーム向けに、本番環境のログ設計を指針するスキルです。リクエストごとにコンテキストを含む構造化イベントを記録し、ログ設計、コードレビュー、本番障害の調査を検索しやすさの観点から支援します。

主な機能

  1. 01リクエストごとのワイドイベント
  2. 02高カーディナリティ項目の設計指針
  3. 03結果に応じたサンプリング戦略
  4. 04既存ログのアンチパターン検出
  5. 05検索を重視したログ設計

活用シーン

  1. 01新規サービスのログ設計
  2. 02コード内のログ記述のレビュー
  3. 03本番障害の調査
  4. 04構造化ログへの移行とログ量削減

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/ncklrs/startup-os-skills --skill logging-best-practices

インストール後、Claude Code で/logging-best-practicesを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

metadata.json
rules/
_sections.md
antipattern-otel-silver-bullet.md
antipattern-scattered-logs.md
antipattern-string-search.md
architecture-event-lifecycle.md
architecture-wide-events.md
fields-business-context.md
fields-high-cardinality.md
fields-required-context.md
sampling-always-keep.md
sampling-tail-sampling.md

詳細

ロギングのベストプラクティス

Boris Tane のloggingsucks.comの哲学に基づく、本番環境向けロギングの専門的なガイダンスです。

基本理念

「コードが何をしているか」のロギングをやめ、「このリクエストに何が起きたか」のロギングを始めましょう。

従来のロギングは、クエリではなく書き込みに最適化されています。開発者は、後でどのように検索されるかを考慮せず、その場のデバッグの利便性のためにログを出力します。その結果、規模が大きくなるにつれて、シグナル対ノイズ比が著しく悪化します。

ワイドイベントのアーキテクチャ

コード全体にログ文を散在させるのではなく、サービスごとにリクエストごとの包括的なイベントを1つ作成しましょう。

// ❌ Traditional scattered logging
logger.info("Request started");
logger.info(`User ${userId} found`);
logger.info("Fetching cart");
logger.debug(`Cart has ${items.length} items`);
logger.info("Processing payment");
logger.error(`Payment failed: ${error.message}`);

// ✅ Wide event - build throughout request, emit once
const event = {
  request_id: req.id,
  timestamp: Date.now(),
  service: "checkout",
  version: "2.3.1",

  user: { id: userId, tier: "premium", account_age_days: 847 },
  cart: { id: cartId, item_count: 3, total_cents: 15999 },
  payment: { method: "card", provider: "stripe", latency_ms: 234 },

  outcome: "failure",
  error: { type: "PaymentDeclined", code: "card_declined", retriable: true }
};

logger.info(event);

主な概念

概念定義
ワイドイベントリクエストごと、サービスごとに1つ記録する、包括的でコンテキストが豊富なログ
カーディナリティ一意な値の数（ユーザー ID は高く、HTTP メソッドは低い）
次元数イベントごとのフィールド数（意味のあるフィールドを40個以上目指します）
テールサンプリングリクエスト完了後に、その結果に基づいてサンプリングを決定します

このスキルを適用する場面

  • 新しいサービスにロギングを実装するとき
  • ログ文を含むコードをレビューするとき
  • 本番環境の問題をデバッグするとき
  • オブザーバビリティ戦略を設計するとき
  • printf 形式から構造化ロギングに移行するとき
  • クエリのしやすさを高めながらログ量を削減するとき

このスキルで提供する内容

  1. さまざまなフレームワークや言語向けのワイドイベントのパターン
  2. 高カーディナリティのデバッグに向けたフィールド設計のガイダンス
  3. シグナルを維持するサンプリング戦略
  4. 既存のロギングコードにおけるアンチパターンの検出
  5. ログアーキテクチャにおけるクエリファーストの考え方

コメント

Markdown 対応