Adding Debug Logs the Right Way — Visibility Without Noise

Debug logs are the cheapest debugging tool you have. They're also the most often misused — either there are zero of them and you're guessing, or there are so many that the signal is lost in the noise.

Here's how to add them well.

Log at the Boundaries, Not the Lines

Beginners log every line ("entering function," "left the if block"). This generates noise without surfacing anything actionable.

Instead, log at the boundaries of your system:

• Input boundary — what data came in (API request body, form submission, file uploaded, click event)
• Decision boundary — which branch did the code take, and why
• Side-effect boundary — what was written to the database, what HTTP call was made, what was rendered
• Output boundary — what response was sent back

Five well-placed logs almost always beat fifty scattered ones.

Log the Values, Not Just the Path

A log that says "*processing user signup*" tells you the code executed. A log that says "*processing user signup, email=test@x.com, plan=pro, referral_code=null*" tells you what the code is actually working with.

Include the variables that matter to the bug. If you're debugging a discount-code issue, log the discount code at every boundary it crosses. If you're debugging an auth issue, log the user ID and role.

Use Levels So You Can Filter

Most logging libraries support levels (debug, info, warn, error). Use them:

• debug — boundary logs you'd only want when actively investigating
• info — meaningful events that should always be visible (user signed up, payment succeeded)
• warn — unexpected but recoverable (retry attempt, validation failure)
• error — actual failures with stack traces

In production, set the level to info. While debugging, flip a single env var to enable debug and you'll get the boundary-level visibility without permanently flooding the log files.

Use Structured Logs for Anything Non-Trivial

```js // not great console.log("user signup failed for " + email);

// much better logger.debug({ event: "signup_failed", email, reason: validationError, ip: req.ip }); ```

Structured logs are searchable. When you're trying to find every signup that failed with reason weak_password in the last hour, structured logs give you that in one grep. Unstructured logs make you parse strings.

Don't Log Sensitive Data

The fastest way to turn a debug log into a security incident is to log the value of a password, an API key, or a credit card number. Even temporarily. Even just on your dev machine. Logs end up in places you don't expect — error trackers, monitoring tools, support tickets.

Rule of thumb: if the field would make you nervous in a screenshot, don't log it. Log a redacted version (pw_length=8, pw_has_special=true) instead.

Clean Up When You're Done

The last 5% of a debug session is removing the temporary logs. Either:

• Delete them entirely if they were truly one-off
• Demote them from info to debug if they might be useful again
• Keep them as info if they capture a meaningful boundary that should always be visible

A codebase littered with abandoned console.log statements from old debugging sessions is hard to read and gives nobody confidence. Take 5 minutes to clean up.

When to Skip Logging and Use a Debugger

For interactive bug hunting where you need to inspect arbitrary state, a real debugger (Chrome DevTools, VS Code debugger, lldb) beats logs every time. Logs are best for:

• Bugs that only show up in production
• Bugs that only show up under load
• Bugs whose conditions are hard to recreate manually
• Bugs in async / event-driven code where stepping through is awkward

For everything else, breakpoints are faster.

---

Need someone to instrument a tricky bug? I take on debugging engagements at any size — a single bug Quick Win for $1,500 or a broader Discovery audit for $500 if you need someone to figure out which bugs to tackle first. Email me a description of the symptom and I'll tell you what it'd take to nail it.