Part 5: Debug Configurations and Production Debugging

Introduction

You know how to debug with F5, but production systems need more: debugging specific modules, attaching to running processes, debugging tests, remote debugging, and configurations for different environments. I learned this debugging a microservice in production—couldn't reproduce the bug locally, had to attach the debugger to the live container.

This final article covers advanced debug configurations, debugging pytest tests, remote debugging, Docker container debugging, and techniques for investigating production issues.

Launch.json Configurations

The .vscode/launch.json file defines debug configurations for different scenarios.

Basic Structure

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal"
        }
    ]
}

Common Configuration Options

{
    "name": "Display name in debug dropdown",
    "type": "debugpy",
    "request": "launch",  // or "attach"
    "program": "${file}",  // File to debug
    "module": "module_name",  // Or module instead of file
    "args": ["--arg1", "value1"],  // Command-line arguments
    "cwd": "${workspaceFolder}",  // Working directory
    "env": {
        "ENV_VAR": "value"
    },
    "envFile": "${workspaceFolder}/.env",
    "console": "integratedTerminal",  // or "internalConsole"
    "justMyCode": true,  // Skip library code
    "stopOnEntry": false,  // Pause at first line
    "pythonPath": "${workspaceFolder}/venv/bin/python"
}

Real-World Configurations

Configuration 1: FastAPI Application

{
    "name": "FastAPI: Debug Server",
    "type": "debugpy",
    "request": "launch",
    "module": "uvicorn",
    "args": [
        "app.main:app",
        "--reload",
        "--host", "0.0.0.0",
        "--port", "8000",
        "--log-level", "debug"
    ],
    "jinja": true,
    "justMyCode": true,
    "env": {
        "DATABASE_URL": "postgresql://localhost/dev_db",
        "DEBUG": "1"
    },
    "envFile": "${workspaceFolder}/.env.development"
}

Use case: Debug FastAPI endpoints with hot reload

How to use:

1. Set breakpoints in your endpoint handlers

2. Select "FastAPI: Debug Server" from debug dropdown

3. Press F5

4. Send requests to http://localhost:8000

Configuration 2: Flask Application

{
    "name": "Flask: Debug Server",
    "type": "debugpy",
    "request": "launch",
    "module": "flask",
    "env": {
        "FLASK_APP": "app.py",
        "FLASK_DEBUG": "1",
        "FLASK_ENV": "development"
    },
    "args": [
        "run",
        "--host=0.0.0.0",
        "--port=5000",
        "--no-debugger",
        "--no-reload"
    ],
    "jinja": true
}

Configuration 3: Django Application

{
    "name": "Django: Debug Server",
    "type": "debugpy",
    "request": "launch",
    "program": "${workspaceFolder}/manage.py",
    "args": [
        "runserver",
        "0.0.0.0:8000",
        "--noreload"  // Important: Disable Django's reloader
    ],
    "django": true,
    "justMyCode": true
}

Configuration 4: Specific Script with Arguments

{
    "name": "Process Data Script",
    "type": "debugpy",
    "request": "launch",
    "program": "${workspaceFolder}/scripts/process_data.py",
    "args": [
        "--input", "data/raw/input.csv",
        "--output", "data/processed/output.json",
        "--batch-size", "1000",
        "--verbose"
    ],
    "cwd": "${workspaceFolder}",
    "env": {
        "LOG_LEVEL": "DEBUG"
    }
}

Configuration 5: Module with Entry Point

{
    "name": "Run Package Module",
    "type": "debugpy",
    "request": "launch",
    "module": "mypackage.cli",  // python -m mypackage.cli
    "args": ["--config", "config.yaml"],
    "justMyCode": true
}

Debugging Tests

Pytest Configuration

{
    "name": "Pytest: Current File",
    "type": "debugpy",
    "request": "launch",
    "module": "pytest",
    "args": [
        "${file}",
        "-v",
        "-s"  // Show print statements
    ],
    "console": "integratedTerminal",
    "justMyCode": false  // See into test framework
}

Real test file:

# tests/test_api.py
import pytest
from app.main import app
from fastapi.testclient import TestClient

client = TestClient(app)

def test_create_user():
    response = client.post(  # ← Breakpoint here
        "/users",
        json={"name": "Alice", "email": "[email protected]"}
    )
    
    assert response.status_code == 201  # ← Or here to see response
    data = response.json()
    assert data["name"] == "Alice"

Debug single test:

1. Open test file

2. Set breakpoint in test

3. Select "Pytest: Current File"

4. Press F5

Debug Specific Test Function

{
    "name": "Pytest: Specific Test",
    "type": "debugpy",
    "request": "launch",
    "module": "pytest",
    "args": [
        "${file}::test_create_user",  // Run only this test
        "-v",
        "-s"
    ],
    "console": "integratedTerminal"
}

Debug All Tests

{
    "name": "Pytest: All Tests",
    "type": "debugpy",
    "request": "launch",
    "module": "pytest",
    "args": [
        "tests/",
        "-v",
        "--tb=short",  // Short traceback
        "-x"  // Stop on first failure
    ],
    "console": "integratedTerminal"
}

Real Example: Debugging Failing Test

# app/services/payment.py
def calculate_total_with_tax(subtotal: float, tax_rate: float) -> float:
    return subtotal + (subtotal * tax_rate)

# tests/test_payment.py
def test_calculate_total():
    subtotal = 100.00
    tax_rate = 0.08
    
    total = calculate_total_with_tax(subtotal, tax_rate)  # ← Breakpoint
    
    assert total == 108.00  # Test failing!

Debug session:

>>> subtotal
100.0
>>> tax_rate
0.08
>>> total
108.0
>>> total == 108.00
False  # ← What?!
>>> type(total)
<class 'float'>
>>> total == 108.0
True
>>> 108.00 == 108.0
True  # ← Issue with float comparison

Found floating-point precision issue! Fix:

assert round(total, 2) == 108.00
# Or use pytest.approx
assert total == pytest.approx(108.00)

Attach to Running Process

Debug Python code that's already running.

Configuration for Attaching

{
    "name": "Python: Attach",
    "type": "debugpy",
    "request": "attach",
    "connect": {
        "host": "localhost",
        "port": 5678
    },
    "pathMappings": [
        {
            "localRoot": "${workspaceFolder}",
            "remoteRoot": "."
        }
    ]
}

Prepare Code for Attach

Add debugpy to your application:

# app.py
import debugpy

# Enable debugging on port 5678
debugpy.listen(("0.0.0.0", 5678))
print("Waiting for debugger attach...")
debugpy.wait_for_client()  # Optional: wait for debugger
print("Debugger attached!")

# Rest of your application
from fastapi import FastAPI
app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

Steps to debug:

1. Run application: python app.py

2. Application waits at wait_for_client()

3. In VS Code: Select "Python: Attach"

4. Press F5

5. Debugger connects, execution continues

Attach Without Waiting

import debugpy

# Don't wait - app starts immediately
debugpy.listen(("0.0.0.0", 5678))

# App runs normally, attach debugger when needed
app = FastAPI()

Remote Debugging

Debug code running on another machine or in a container.

Remote Machine Setup

On remote machine:

# remote_app.py
import debugpy

# Listen on all interfaces
debugpy.listen(("0.0.0.0", 5678))
print("Waiting for remote debugger...")
debugpy.wait_for_client()

# Application code
def process_data():
    # Your code here
    pass

process_data()

Run on remote:

python remote_app.py

VS Code configuration:

{
    "name": "Python: Remote Attach",
    "type": "debugpy",
    "request": "attach",
    "connect": {
        "host": "192.168.1.100",  // Remote machine IP
        "port": 5678
    },
    "pathMappings": [
        {
            "localRoot": "${workspaceFolder}/src",
            "remoteRoot": "/app/src"  // Path on remote machine
        }
    ]
}

Docker Container Debugging

Dockerfile:

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt debugpy

COPY . .

# Expose debugger port
EXPOSE 8000 5678

CMD ["python", "-m", "debugpy", "--listen", "0.0.0.0:5678", "--wait-for-client", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

docker-compose.yml:

version: '3.8'

services:
  app:
    build: .
    ports:
      - "8000:8000"
      - "5678:5678"  # Debugger port
    volumes:
      - ./app:/app/app  # Mount code for live debugging
    environment:
      - DEBUG=1

VS Code launch.json:

{
    "name": "Docker: Attach",
    "type": "debugpy",
    "request": "attach",
    "connect": {
        "host": "localhost",
        "port": 5678
    },
    "pathMappings": [
        {
            "localRoot": "${workspaceFolder}/app",
            "remoteRoot": "/app/app"
        }
    ]
}

Debug workflow:

# Start container
docker-compose up

# In VS Code:
# 1. Set breakpoints
# 2. Select "Docker: Attach"
# 3. Press F5
# 4. Send request to http://localhost:8000

Environment-Specific Configurations

Multiple Environments

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Development: FastAPI",
            "type": "debugpy",
            "request": "launch",
            "module": "uvicorn",
            "args": ["app.main:app", "--reload"],
            "envFile": "${workspaceFolder}/.env.development",
            "env": {
                "APP_ENV": "development"
            }
        },
        {
            "name": "Staging: FastAPI",
            "type": "debugpy",
            "request": "launch",
            "module": "uvicorn",
            "args": ["app.main:app", "--host", "0.0.0.0"],
            "envFile": "${workspaceFolder}/.env.staging",
            "env": {
                "APP_ENV": "staging"
            }
        }
    ]
}

Compound Configurations

Run multiple debug sessions simultaneously:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Backend: FastAPI",
            "type": "debugpy",
            "request": "launch",
            "module": "uvicorn",
            "args": ["backend.main:app", "--port", "8000"]
        },
        {
            "name": "Worker: Celery",
            "type": "debugpy",
            "request": "launch",
            "module": "celery",
            "args": ["-A", "worker.celery", "worker", "--loglevel=info"]
        }
    ],
    "compounds": [
        {
            "name": "Backend + Worker",
            "configurations": [
                "Backend: FastAPI",
                "Worker: Celery"
            ],
            "stopAll": true
        }
    ]
}

Select "Backend + Worker" to debug both simultaneously!

Production Debugging Strategies

Strategy 1: Structured Logging

Can't always attach debugger to production. Use structured logging:

import logging
import json
from datetime import datetime

# Configure structured logging
logging.basicConfig(
    level=logging.INFO,
    format='%(message)s'
)

logger = logging.getLogger(__name__)

def log_structured(level, event, **context):
    """Log with structured data"""
    log_entry = {
        "timestamp": datetime.utcnow().isoformat(),
        "level": level,
        "event": event,
        **context
    }
    logger.log(getattr(logging, level), json.dumps(log_entry))

# Usage
def process_payment(user_id, amount):
    log_structured("INFO", "payment.started", 
                   user_id=user_id, amount=amount)
    
    try:
        result = charge_card(user_id, amount)
        log_structured("INFO", "payment.success",
                       user_id=user_id, amount=amount, 
                       transaction_id=result.id)
        return result
        
    except Exception as e:
        log_structured("ERROR", "payment.failed",
                       user_id=user_id, amount=amount,
                       error=str(e), error_type=type(e).__name__)
        raise

Output:

{"timestamp": "2024-03-15T10:30:00", "level": "INFO", "event": "payment.started", "user_id": 123, "amount": 99.99}
{"timestamp": "2024-03-15T10:30:01", "level": "INFO", "event": "payment.success", "user_id": 123, "amount": 99.99, "transaction_id": "txn_12345"}

Strategy 2: Distributed Tracing

For microservices, use OpenTelemetry:

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor

# Setup tracer
trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)

span_processor = BatchSpanProcessor(ConsoleSpanExporter())
trace.get_tracer_provider().add_span_processor(span_processor)

@app.post("/order")
async def create_order(order: OrderRequest):
    with tracer.start_as_current_span("create_order") as span:
        span.set_attribute("order.user_id", order.user_id)
        span.set_attribute("order.items", len(order.items))
        
        with tracer.start_as_current_span("validate_order"):
            validated = validate_order(order)
        
        with tracer.start_as_current_span("process_payment"):
            payment = await process_payment(validated)
        
        with tracer.start_as_current_span("save_order"):
            result = save_order(payment)
        
        span.set_attribute("order.id", result.id)
        return result

Traces show full request flow across services.

Strategy 3: Debug Mode Flag

import os

DEBUG = os.getenv("DEBUG", "0") == "1"

def process_order(order):
    if DEBUG:
        # In debug mode, add extra checks
        import pdb; pdb.set_trace()
    
    result = complex_calculation(order)
    
    if DEBUG:
        # Validate result in debug mode
        validate_result(result)
    
    return result

Enable debug mode in production when investigating specific issues.

Strategy 4: Error Tracking

Use Sentry or similar:

import sentry_sdk
from sentry_sdk.integrations.fastapi import FastApiIntegration

sentry_sdk.init(
    dsn="your-sentry-dsn",
    integrations=[FastApiIntegration()],
    traces_sample_rate=1.0,
    environment="production"
)

@app.post("/payment")
def process_payment(amount):
    with sentry_sdk.push_scope() as scope:
        scope.set_context("payment", {
            "amount": amount,
            "user_id": current_user.id
        })
        
        try:
            return charge_card(amount)
        except Exception as e:
            sentry_sdk.capture_exception(e)
            raise

Sentry captures full context when errors occur.

Debugging Performance Issues

Configuration with Profiling

{
    "name": "Profile: Performance Test",
    "type": "debugpy",
    "request": "launch",
    "program": "${workspaceFolder}/tests/performance_test.py",
    "args": ["--iterations", "1000"],
    "console": "integratedTerminal",
    "profiling": true  // Enable profiling
}

Using cProfile

import cProfile
import pstats
from io import StringIO

def profile_function(func):
    """Decorator to profile function performance"""
    def wrapper(*args, **kwargs):
        pr = cProfile.Profile()
        pr.enable()
        
        result = func(*args, **kwargs)
        
        pr.disable()
        s = StringIO()
        ps = pstats.Stats(pr, stream=s).sort_stats('cumulative')
        ps.print_stats()
        print(s.getvalue())
        
        return result
    return wrapper

@profile_function
def slow_endpoint():
    # Your code here
    results = process_data()
    return results

Memory Profiling

from memory_profiler import profile

@profile
def memory_intensive_function():
    # Shows memory usage line by line
    data = [i for i in range(1000000)]
    processed = [x * 2 for x in data]
    return processed

Best Practices

1. Separate Configurations for Each Component

{
    "configurations": [
        {
            "name": "API Server",
            "program": "api/main.py"
        },
        {
            "name": "Background Worker",
            "program": "worker/tasks.py"
        },
        {
            "name": "Data Pipeline",
            "program": "pipeline/processor.py"
        }
    ]
}

2. Use Environment Files

{
    "envFile": "${workspaceFolder}/.env.${input:envChoice}"
}

With input variable:

{
    "inputs": [
        {
            "id": "envChoice",
            "type": "pickString",
            "description": "Choose environment",
            "options": ["development", "staging", "production"]
        }
    ]
}

3. Document Your Configurations

{
    "name": "FastAPI: Debug Server",
    // Starts FastAPI with hot reload for development
    // Use this for debugging API endpoints
    // Server runs on http://localhost:8000
    "type": "debugpy",
    "request": "launch"
}

4. Version Control launch.json

Include .vscode/launch.json in git so team members have consistent debug configurations.

Series Conclusion

You've completed the Code Debugging 101 series! You now know:

• Part 1: Setting up VS Code debugger, basic breakpoints, debug interface

• Part 2: Conditional breakpoints, logpoints, stepping through code

• Part 3: Variables inspection, watch expressions, call stacks, debug console

• Part 4: Debugging async code, exceptions, decorators, multi-threading

• Part 5: Launch configurations, debugging tests, remote debugging, production strategies

From Print Debugging to Professional Debugging

You started with print() statements. Now you can:

• Set strategic breakpoints that pause only when needed

• Inspect complex data structures interactively

• Debug async, threaded, and decorated code

• Test fixes in debug console before changing code

• Debug remote applications and containers

• Investigate production issues systematically

Next Steps

1. Practice daily: Use debugger instead of prints

2. Create configurations: Build launch.json for your projects

3. Share knowledge: Teach teammates debugging techniques

4. Explore extensions: Try debugging extensions for your frameworks

5. Read documentation: VS Code debugging docs have more advanced features

The Debugging Mindset

Debugging isn't just about fixing bugs—it's about understanding your code deeply. The debugger is a learning tool as much as a fixing tool. Use it to:

• Explore unfamiliar codebases

• Understand library behavior

• Verify your assumptions

• Learn how frameworks work internally

Happy debugging!

---

Based on debugging thousands of Python applications across local development, containers, remote servers, and production environments using VS Code.