Logging Best Practices
Install this when agents write or review backend code so logs become one wide canonical event per request instead of scattered printf debugging.
Overview
Logging Best Practices is a journey-wide agent skill that teaches wide-event canonical logging—usable whenever a solo builder needs queryable production signals before committing scattered log statements.
Install
npx skills add https://github.com/boristane/agent-skills --skill logging-best-practicesWhat is this skill?
- Wide events pattern: one context-rich canonical log line per request at completion
- High cardinality and dimensionality guidance (20+ fields, user_id, request_id, feature flags)
- Single logger at startup plus middleware-owned infrastructure logging
- Business and environment context rules (subscription tier, cart value, commit hash, region)
- Aligned with Stripe canonical log lines and wide-events observability references
- 20+ fields per wide event target
- Single logger pattern
- Middleware-based logging infrastructure
Adoption & trust: 3.4k installs on skills.sh; 94 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your logs are a wall of unstructured lines, so debugging one user request takes grep gymnastics and you still miss subscription tier or deploy version context.
Who is it for?
Solo backend builders and small teams standardizing observability while agents write or review service code.
Skip if: Frontend-only projects with no server logging, or teams already locked into a conflicting proprietary logging schema they cannot change.
When should I use this skill?
Writing or reviewing code that needs production-grade logging, structured request completion events, or observability-friendly middleware.
What do I get? / Deliverables
Handlers and middleware emit one completion event with rich dimensions so agents and you can trace requests, compare releases, and answer incident questions from a single log row.
- Middleware and handler logging aligned to wide-event rules
- Review feedback on cardinality, dimensions, and anti-patterns
- Logger bootstrap configuration used application-wide
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
Add middleware that emits one wide event per API request with user and cart context.
Reject PRs that sprinkle debug logs instead of enriching the completion event.
Align log fields with dashboards so incidents filter by version and region quickly.
Reuse business fields in logs to correlate support tickets with subscription state.
Compare wide-events approach to your current logging vendor constraints before rewriting services.
How it compares
Opinionated observability skill for application code—not a log shipping agent or hosted APM product.
Common Questions / FAQ
Who is logging-best-practices for?
Indie developers and agents co-writing APIs or services who want Stripe-style canonical lines without hiring a platform engineer.
When should I use logging-best-practices?
Use it in Build when adding routes or jobs, in Ship during code review of logging changes, and in Operate when hardening fields before scaling traffic or on-call load.
Is logging-best-practices safe to install?
It is documentation-only guidance; review the Security Audits panel on this page and ensure agents do not log secrets or PII against your retention policy.
SKILL.md
READMESKILL.md - Logging Best Practices
{ "version": "1.0.0", "organization": "boristane", "date": "2025-01-20", "abstract": "Logging best practices focused on wide events (canonical log lines), high cardinality data, environment context, single logger pattern, and middleware-based logging infrastructure.", "references": [ "https://loggingsucks.com", "https://boristane.com/blog/observability-wide-events-101/", "https://stripe.com/blog/canonical-log-lines" ] } # Logging Best Practices Skill A skill for AI coding assistants to apply logging best practices when writing or reviewing code. ## Overview This skill teaches the **wide events** pattern (also known as canonical log lines) - emit a single, context-rich event per request per service instead of scattered log statements. ## Key Concepts - **Wide Events**: One comprehensive event per request, emitted at completion - **High Cardinality**: Support fields with millions of unique values (user_id, request_id) - **High Dimensionality**: Include many fields (20+) per event - **Business Context**: Always include user subscription, cart value, feature flags - **Environment Context**: Always include commit hash, version, region, instance ID - **Single Logger**: One logger instance configured at startup, used everywhere - **Middleware Pattern**: Handle logging infrastructure in middleware, business context in handlers ## Structure ``` logging-best-practices/ ├── SKILL.md # Agent instructions ├── README.md # This file ├── metadata.json # Version and references └── rules/ ├── wide-events.md # Core pattern (CRITICAL) ├── context.md # Cardinality, business & environment context (CRITICAL) ├── structure.md # Single logger, middleware, JSON format (HIGH) └── pitfalls.md # Common mistakes (MEDIUM) ``` ## Rules 1. **Wide Events** (CRITICAL) - One event per request, emit in finally block, request ID correlation 2. **Context** (CRITICAL) - High cardinality, dimensionality, business context, environment characteristics 3. **Structure** (HIGH) - Single logger, middleware pattern, JSON format, consistent schema 4. **Pitfalls** (MEDIUM) - Scattered logs, unknown unknowns, missing request correlation ## Reference - [Boris Tane's Blog - Logging Sucks](https://loggingsucks.com) - [Boris Tane's Blog - Observability wide events 101](https://boristane.com/blog/observability-wide-events-101/) - [Stripe Blog - Canonical Log Lines](https://stripe.com/blog/canonical-log-lines) --- title: Context, Cardinality, and Dimensionality impact: CRITICAL tags: logging, context, cardinality, dimensionality --- ## Context, Cardinality, and Dimensionality **Impact: CRITICAL** Wide events must be context-rich with high cardinality and high dimensionality. This enables you to answer questions you haven't anticipated yet - the "unknown unknowns" that traditional logging misses. ### High Cardinality High cardinality means a field can have millions or billions of unique values. User IDs, request IDs, and transaction IDs are high cardinality fields. Your logging must support querying against any specific value of these fields. Without high cardinality support, you cannot debug issues for specific users. ### High Dimensionality High dimensionality means your events have many fields (20-100+). More dimensions mean more questions you can answer without redeploying code. ```typescript const wideEvent = { // Timing timestamp: '2024-09-08T06:14:05.680Z', duration_ms: 268, // Request context method: 'POST', path: '/checkout', requestId: 'req_abc123', // Infrastructure service: 'checkout-service', version: '2.4.1', region: 'us-east-1', commit_hash: '690de31f', // User context (HIGH CARDINALITY - millions of unique values) user: { id: 'user_456', subscription: 'premium', account_age_days: 847, lifetime_value_cents: 284700, }, // Business context cart: { id: 'cart_xyz', item_count: 3, total_cents: