Logging Best Practices

1---2name: logging-best-practices3description: Logging best practices focused on wide events (canonical log lines) for powerful debugging and analytics4license: MIT5metadata:6  author: boristane7  version: "1.0.0"8---9 10# Logging Best Practices Skill11 12Version: 1.0.013 14## Purpose15 16This skill provides guidelines for implementing effective logging in applications. It focuses on **wide events** (also called canonical log lines) - a pattern where you emit a single, context-rich event per request per service, enabling powerful debugging and analytics.17 18## When to Apply19 20Apply these guidelines when:21- Writing or reviewing logging code22- Adding console.log, logger.info, or similar23- Designing logging strategy for new services24- Setting up logging infrastructure25 26## Core Principles27 28### 1. Wide Events (CRITICAL)29 30Emit **one context-rich event per request per service**. Instead of scattering log lines throughout your handler, consolidate everything into a single structured event emitted at request completion.31 32```typescript33const wideEvent: Record<string, unknown> = {34  method: 'POST',35  path: '/checkout',36  requestId: c.get('requestId'),37  timestamp: new Date().toISOString(),38};39 40try {41  const user = await getUser(c.get('userId'));42  wideEvent.user = { id: user.id, subscription: user.subscription };43 44  const cart = await getCart(user.id);45  wideEvent.cart = { total_cents: cart.total, item_count: cart.items.length };46 47  wideEvent.status_code = 200;48  wideEvent.outcome = 'success';49  return c.json({ success: true });50} catch (error) {51  wideEvent.status_code = 500;52  wideEvent.outcome = 'error';53  wideEvent.error = { message: error.message, type: error.name };54  throw error;55} finally {56  wideEvent.duration_ms = Date.now() - startTime;57  logger.info(wideEvent);58}59```60 61### 2. High Cardinality & Dimensionality (CRITICAL)62 63Include fields with high cardinality (user IDs, request IDs - millions of unique values) and high dimensionality (many fields per event). This enables querying by specific users and answering questions you haven't anticipated yet.64 65### 3. Business Context (CRITICAL)66 67Always include business context: user subscription tier, cart value, feature flags, account age. The goal is to know "a premium customer couldn't complete a $2,499 purchase" not just "checkout failed."68 69### 4. Environment Characteristics (CRITICAL)70 71Include environment and deployment info in every event: commit hash, service version, region, instance ID. This enables correlating issues with deployments and identifying region-specific problems.72 73### 5. Single Logger (HIGH)74 75Use one logger instance configured at startup and import it everywhere. This ensures consistent formatting and automatic environment context.76 77### 6. Middleware Pattern (HIGH)78 79Use middleware to handle wide event infrastructure (timing, status, environment, emission). Handlers should only add business context.80 81### 7. Structure & Consistency (HIGH)82 83- Use JSON format consistently84- Maintain consistent field names across services85- Simplify to two log levels: `info` and `error`86- Never log unstructured strings87 88## Anti-Patterns to Avoid89 901. **Scattered logs**: Multiple console.log() calls per request912. **Multiple loggers**: Different logger instances in different files923. **Missing environment context**: No commit hash or deployment info934. **Missing business context**: Logging technical details without user/business data945. **Unstructured strings**: `console.log('something happened')` instead of structured data956. **Inconsistent schemas**: Different field names across services96 97## Guidelines98 99### Wide Events (`rules/wide-events.md`)100- Emit one wide event per service hop101- Include all relevant context102- Connect events with request ID103- Emit at request completion in finally block104 105### Context (`rules/context.md`)106- Support high cardinality fields (user_id, request_id)107- Include high dimensionality (many fields)108- Always include business context109- Always include environment characteristics (commit_hash, version, region)110 111### Structure (`rules/structure.md`)112- Use a single logger throughout the codebase113- Use middleware for consistent wide events114- Use JSON format115- Maintain consistent schema116- Simplify to info and error levels117- Never log unstructured strings118 119### Common Pitfalls (`rules/pitfalls.md`)120- Avoid multiple log lines per request121- Design for unknown unknowns122- Always propagate request IDs across services123 124References:125- [Logging Sucks](https://loggingsucks.com)126- [Observability Wide Events 101](https://boristane.com/blog/observability-wide-events-101/)127- [Stripe - Canonical Log Lines](https://stripe.com/blog/canonical-log-lines)