logging-best-practices
Scannednpx machina-cli add skill ncklrs/startup-os-skills/logging-best-practices --openclawLogging 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
| Concept | Definition |
|---|---|
| Wide Event | One comprehensive, context-rich log per request per service |
| Cardinality | Number of unique values (user IDs = high, HTTP methods = low) |
| Dimensionality | Count of fields per event (aim for 40+ meaningful fields) |
| Tail Sampling | Sample 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
- Wide event patterns for different frameworks and languages
- Field design guidance for high-cardinality debugging
- Sampling strategies that preserve signal
- Anti-pattern detection in existing logging code
- Query-first thinking for log architecture
Source
git clone https://github.com/ncklrs/startup-os-skills/blob/main/skills/logging-best-practices/SKILL.mdView on GitHub Overview
This skill teaches production-grade logging based on Boris Tane's loggingsucks philosophy. It shifts from logging what code is doing to logging what happened to each request, enabling scalable search and faster debugging. It covers wide events, structured field design, smart sampling, and anti-pattern detection to improve observability.
How This Skill Works
You create a single wide event per request across a service, collecting context such as request_id, timestamp, service, version, user, cart, payment, outcome, and error, then emit it once (e.g., logger.info(event)). After the request completes, you apply tail sampling decisions to preserve signal while reducing log volume.
When to Use It
- Implementing logging in new services
- Reviewing code with log statements
- Debugging production issues
- Designing an observability strategy
- Migrating from printf-style to structured logging
Quick Start
- Step 1: Build a wide event during the request with fields such as request_id, timestamp, service, version, user, cart, payment, outcome, and error
- Step 2: Emit the event once (e.g., logger.info(event)) at the end of the request
- Step 3: After completion, apply tail sampling decisions to preserve signal for failures and high-value outcomes
Best Practices
- Adopt wide event patterns: one comprehensive, context-rich log per request per service
- Design fields for high cardinality to support deep debugging
- Implement tail sampling after request completion to preserve signal
- Detect and fix anti-patterns in existing logging code
- Adopt query-first thinking for log architecture and future queries
Example Use Cases
- Implement a wide event in a checkout service to replace scattered logs like 'Request started' and 'Payment failed' with a single structured event
- Migrate legacy printf-style logging to structured, per-request events to improve searchability
- Use high-cardinality fields (e.g., user ID, cart ID) and many optional fields to enable detailed filtering
- Apply tail sampling after request completion to keep noisy failures traceable while reducing volume
- Design observability strategy around per-request wide events across services rather than file-level logs
