debug
Tiny namespaced debugging utility used by Express.js, Mongoose, Socket.IO, and most major Node.js frameworks for conditional debug output. Logging is controlled via the DEBUG environment variable — only enabled namespaces produce output. Zero overhead when disabled. Works in both Node.js and browser. The standard approach for adding conditional debug output to Node.js libraries without polluting production logs.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
MIT licensed. Zero dependencies. Warning: debug output may include sensitive values — avoid logging credentials/secrets in debug calls that could be enabled in production.
⚡ Reliability
Best When
You're writing a reusable Node.js library or framework and want to add optional debug output that users can enable via DEBUG environment variable with zero production overhead.
Avoid When
You're building application-level logging — use Winston or Pino. Debug is for library internals, not application observability.
Use Cases
- • Add conditional debug logging to Node.js libraries and frameworks controlled by DEBUG environment variable
- • Enable granular debug output for specific agent components by setting DEBUG=agent:*, agent:http without code changes
- • Debug third-party library internals by enabling their built-in debug output: DEBUG=express:* node app.js
- • Add development-only diagnostic logging to agent middleware that has zero production overhead
- • Instrument agent library code so users can enable debug output without modifying source
Not For
- • Production application logging — debug is for developer diagnostics; use Winston or Pino for application logging
- • Structured JSON logging — debug outputs human-readable text with colors; not suitable for log aggregation
- • Log level control (info, warn, error) — debug is binary on/off per namespace, not level-based
Interface
Authentication
Local library — no authentication required. MIT licensed.
Pricing
MIT licensed. Zero cost.
Agent Metadata
Known Gotchas
- ⚠ DEBUG environment variable controls output — DEBUG=* enables all namespaces; DEBUG=myapp:* enables only myapp namespaces; must be set before process starts
- ⚠ Namespace convention: use colons for hierarchy (myapp:http, myapp:db, myapp:worker) — DEBUG=myapp:* enables all sub-namespaces
- ⚠ Negation in DEBUG: DEBUG=*,-myapp:verbose enables everything except myapp:verbose — useful for excluding noisy namespaces
- ⚠ In browser, debug uses localStorage — set localStorage.debug='*' in browser console; different from Node.js env var approach
- ⚠ debug() is NOT async-safe for ordering — multiple concurrent async operations may interleave debug output; add request IDs or use structured logging instead
- ⚠ Output goes to stderr by default in Node.js — redirect with DEBUG_FD=1 or override debug.log function: debug.log = console.log.bind(console)
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for debug.
Scores are editorial opinions as of 2026-03-06.