agentleFS
niieaniniieani/caara/.agents/skills/logging-best-practices/SKILL.md

logging-best-practices

Skill5 starsChanged 4 months agoMITView on GitHub

Logging best practices focused on wide events (canonical log lines) for powerful debugging and analytics

16 other projects use a version of this, 2 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use show-me, improve-codebase-architecture and 6 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • AnasX7Skill

    show-me

    Help the user understand the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts.

    Also in 3 projects that use this

  • GoogleSkill

    improve-codebase-architecture

    Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

    Also in 4 projects that use this

  • CloudflareSkill

    receiving-code-review

    Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation

    Also in 3 projects that use this

  • OpenAISkill

    executing-plans

    Use when you have a written implementation plan to execute in a separate session with review checkpoints

    Also in 3 projects that use this

  • OpenAISkill

    requesting-code-review

    Use when completing tasks, implementing major features, or before merging to verify work meets requirements

    Also in 3 projects that use this

  • SentrySkill

    security-review

    Finds exploitable application security vulnerabilities in code changes. Use for Warden security scans, appsec review, OWASP-style checks, authentication or authorization bugs, injection, XSS, SSRF, path traversal, secrets, unsafe crypto, webhook verification, open redirects, or sensitive data exposure.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

12 rules. 0 are common, 12 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 11 edited versions we read keep these.

  • 12

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Always include business context: user subscription tier, cart value, feature flags, account age.

    line 67
  2. Distinctive:

    Use one logger instance configured at startup and import it everywhere.

    line 75
  3. Distinctive:

    Use middleware to handle wide event infrastructure (timing, status, environment, emission).

    line 79
  4. Distinctive:

    Use JSON format consistently

    line 83
  5. Distinctive:

    Never log unstructured strings

    line 86
  6. Distinctive:

    Missing environment context: No commit hash or deployment info

    line 92
  7. Distinctive:

    Always include business context

    line 108
  8. Distinctive:

    Always include environment characteristics (commit_hash, version, region)

    line 109
  9. Distinctive:

    Use a single logger throughout the codebase

    line 112
  10. Distinctive:

    Use middleware for consistent wide events

    line 113
  11. Distinctive:

    Avoid multiple log lines per request

    line 120
  12. Distinctive:

    Always propagate request IDs across services

    line 122

“Common” is measured: kept by at least 6 in 10 of the 11 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Logging Best Practices Skill

Version: 1.0.0

Purpose

This 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.

When to Apply

Apply these guidelines when:

  • Writing or reviewing logging code
  • Adding console.log, logger.info, or similar
  • Designing logging strategy for new services
  • Setting up logging infrastructure

Core Principles

1. Wide Events (CRITICAL)

Emit 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.

const wideEvent: Record<string, unknown> = {
  method: 'POST',
  path: '/checkout',
  requestId: c.get('requestId'),
  timestamp: new Date().toISOString(),
};

try {
  const user = await getUser(c.get('userId'));
  wideEvent.user = { id: user.id, subscription: user.subscription };

  const cart = await getCart(user.id);
  wideEvent.cart = { total_cents: cart.total, item_count: cart.items.length };

  wideEvent.status_code = 200;
  wideEvent.outcome = 'success';
  return c.json({ success: true });
} catch (error) {
  wideEvent.status_code = 500;
  wideEvent.outcome = 'error';
  wideEvent.error = { message: error.message, type: error.name };
  throw error;
} finally {
  wideEvent.duration_ms = Date.now() - startTime;
  logger.info(wideEvent);
}

2. High Cardinality & Dimensionality (CRITICAL)

Include 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.

3. Business Context (CRITICAL)

Always 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."

4. Environment Characteristics (CRITICAL)

Include 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.

5. Single Logger (HIGH)

Use one logger instance configured at startup and import it everywhere. This ensures consistent formatting and automatic environment context.

6. Middleware Pattern (HIGH)

Use middleware to handle wide event infrastructure (timing, status, environment, emission). Handlers should only add business context.

7. Structure & Consistency (HIGH)

  • Use JSON format consistently
  • Maintain consistent field names across services
  • Simplify to two log levels: info and error
  • Never log unstructured strings

Anti-Patterns to Avoid

  1. Scattered logs: Multiple console.log() calls per request
  2. Multiple loggers: Different logger instances in different files
  3. Missing environment context: No commit hash or deployment info
  4. Missing business context: Logging technical details without user/business data
  5. Unstructured strings: console.log('something happened') instead of structured data
  6. Inconsistent schemas: Different field names across services

Guidelines

Wide Events (rules/wide-events.md)

  • Emit one wide event per service hop
  • Include all relevant context
  • Connect events with request ID
  • Emit at request completion in finally block

Context (rules/context.md)

  • Support high cardinality fields (user_id, request_id)
  • Include high dimensionality (many fields)
  • Always include business context
  • Always include environment characteristics (commit_hash, version, region)

Structure (rules/structure.md)

  • Use a single logger throughout the codebase
  • Use middleware for consistent wide events
  • Use JSON format
  • Maintain consistent schema
  • Simplify to info and error levels
  • Never log unstructured strings

Common Pitfalls (rules/pitfalls.md)

  • Avoid multiple log lines per request
  • Design for unknown unknowns
  • Always propagate request IDs across services

References:

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.