mcpField
L
logging-best-practices

logging-best-practices

github.com/ncklrsDevelopment53140 installsUpdated 35w ago
Repository

About logging-best-practices

A skill offering production logging guidance for development and operations teams. It focuses on one context-rich structured event per request, supporting log design, code reviews, and production debugging with queryability in mind.

Key features

  1. 01Wide events for each request
  2. 02Guidance on high-cardinality fields
  3. 03Outcome-based sampling strategies
  4. 04Detection of logging anti-patterns
  5. 05Query-first log architecture

Use cases

  1. 01Design logging for a new service
  2. 02Review log statements in code
  3. 03Debug production incidents
  4. 04Move to structured logs and reduce volume

Install

Copy the command and run it in a terminal.

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

After installing, type/logging-best-practicesin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with 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

Details

From the project README

Logging Best Practices

Expert guidance for production-grade logging based on Boris Tane's loggingsucks.com philosophy.

Core Philosophy

Stop logging "what your code is doing." Start logging "what happened to this request."

Traditional logging is optimized for writing, not querying. Developers emit logs for immediate debugging convenience without considering how they'll be searched later. This creates massive signal-to-noise ratios at scale.

The Wide Events Architecture

Instead of scattered log statements throughout your code, build one comprehensive event per request per service:

// ❌ 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);

Key Concepts

ConceptDefinition
Wide EventOne comprehensive, context-rich log per request per service
CardinalityNumber of unique values (user IDs = high, HTTP methods = low)
DimensionalityCount of fields per event (aim for 40+ meaningful fields)
Tail SamplingSample decisions after request completion based on outcomes

When to Apply This Skill

  • Implementing logging in new services
  • Reviewing code with log statements
  • Debugging production issues
  • Designing observability strategy
  • Migrating from printf-style to structured logging
  • Reducing log volume while improving queryability

What This Skill Provides

  1. Wide event patterns for different frameworks and languages
  2. Field design guidance for high-cardinality debugging
  3. Sampling strategies that preserve signal
  4. Anti-pattern detection in existing logging code
  5. Query-first thinking for log architecture

Comments

Markdown supported