Connect with Amin Boulouma Official

🏠 Documentation Hub 📝 Engineering Blog 💻 GitHub Repository

Elevating Debugging Skills: Logger, Pdb, and Control Flow

Amin Boulouma, Software Engineer

Effective debugging isn’t just about finding errors; it’s about gaining visibility into the state of your application as it runs. By combining structured logging with interactive breakpoints (pdb), you create a powerful dual-layer observability system.

The Debugging Feedback Loop

When you integrate logger.debug with pdb.set_trace(), you are bridging the gap between historical telemetry (logs) and live inspection (debugger).

Mastering the Toolkit

1. Passive Observability: logger.debug

Logs provide the “story” of how your code reached a specific state. Using them effectively requires structured output.

• Tip: Always include the variable name alongside the value to avoid “mystery logs” in your terminal.

2. Active Intervention: pdb

When logs aren’t enough to diagnose the why, you need an interactive session. pdb (Python Debugger) allows you to pause execution, inspect local variables, and step through code line-by-line.

The Control Sequence: continue and quit

Once you hit a pdb.set_trace(), you control the flow with two essential commands:

Command	Action	When to use it
n (next)	Execute the current line and move to the next.	To trace the logic flow step-by-step.
c (continue)	Resume execution until the next breakpoint.	When you have finished inspecting the current state.
q (quit)	Immediately terminate the program execution.	When you have found the bug and need to stop further processing.

Refined Debugging Pattern

By combining these, you create a reliable pattern for investigating complex issues without cluttering your logic.

from typing import Any
import pdb 
from ai_system_design.logger import logger

def debug(arg_name: str, arg: Any) -> None:
    """
    A robust debugging utility that logs state and halts for inspection.
    """
    logger.debug("--- DEBUGGING START ---")
    logger.debug(f"{arg_name} = {arg}")
    logger.debug("--- DEBUGGING END ---")
    
    # Active pause: Execution stops here, waiting for your manual command
    pdb.set_trace()

Best Practices for Professional Debugging

• Don’t leave traps: Never ship code to production that contains pdb.set_trace(). Use environment-based toggles (e.g., if DEBUG: pdb.set_trace()).
• Use “Print-Debugging” sparingly: logger.debug is always superior to print() because it provides timestamps, log levels, and can be easily toggled off globally.
• Master the Stack: Use w (where) in pdb to see the full call stack if you aren’t sure how you reached a specific piece of code.

Connect with Amin Boulouma Official