Debugging, Logging & Writing Production-Ready Code

A demo that runs once is easy; code that survives weeks on a customer's flaky data needs debugging skill, logging, error handling, and production discipline. This tutorial covers all of it.

Table of Contents

• Debugging Applications
• Logging
• Error Handling
• What "Production-Ready" Means
• Config, Secrets, and Environment
• Robustness and Observability
• Documentation and Handoff

Debugging Applications

Debugging is the process of finding why code misbehaves. The fastest method: reproduce the problem, then isolate it by printing or stepping through values.

# instead of guessing, inspect the data
print(type(row), row)   # what is this really?

Why useful: FDE issues almost always come from unexpected customer data — logging the actual value reveals it fast.

Best Practice: Reproduce on a small sample before debugging the full dataset.

Common Mistake: "Fixing" by trial-and-error without understanding the root cause — it breaks again later.

Logging

Logging records what your program did, so you can diagnose issues after the fact without being there.

import logging
logging.basicConfig(level=logging.INFO)
logging.info("Fetched %d tickets", len(tickets))
logging.error("Failed to parse row: %s", row)

Explanation: info records normal steps; error records failures with context. Unlike print, logging can write to files and include timestamps.

Best Practice: Log the why and key values (counts, IDs), not just "done".

Note: FDEs rely on logs when a customer reports "it stopped working" three days ago.

Error Handling

Error handling lets your program fail gracefully instead of crashing. In Python you use try/except.

try:
    ticket = json.loads(raw)
except json.JSONDecodeError:
    logging.error("Bad JSON from customer API")
    ticket = {"subject": "unknown"}

Explanation: if parsing fails, the except block catches it, logs the issue, and provides a safe fallback — the script keeps running instead of dying.

Best Practice: Catch specific errors (not bare except:), and always log what went wrong.

Common Mistake: Swallowing errors silently (except: pass) — you'll never know why results are missing.

What "Production-Ready" Means

Production-ready code is reliable, observable, and maintainable by someone else. It handles bad input, fails safely, and tells you when something's wrong.

Why useful: FDEs hand code to customer teams — if it breaks obscurely, your credibility goes with it.

Config, Secrets, and Environment

Keep behavior configurable and secrets out of code. (The mechanics of environment variables and safe key handling are covered in the APIs & Integrations tutorial — here we focus on the production pattern.)

import os
API_URL = os.getenv("API_URL", "https://api.example.com")
API_KEY = os.getenv("API_KEY")   # never hard-code
assert API_KEY, "API_KEY missing from environment"

Explanation: defaults live in code, customer-specific values come from the environment, and a missing key fails fast with a clear message instead of a cryptic error later.

Best Practice: Fail fast and loudly when required config is absent.

Robustness and Observability

Combine error handling, logging, and validation:

import os, logging, requests

def fetch_tickets():
    API_URL = os.getenv("API_URL", "https://api.example.com")
    API_KEY = os.getenv("API_KEY")
    try:
        r = requests.get(API_URL, headers={"Authorization": f"Bearer {API_KEY}"})
        r.raise_for_status()              # error on 4xx/5xx
        return r.json()["tickets"]
    except requests.RequestException as e:
        logging.error("Ticket fetch failed: %s", e)
        return []

Explanation: raise_for_status() turns bad HTTP responses into caught errors; the fallback returns an empty list so the rest of the pipeline continues. Logs explain failures later.

Best Practice: Validate inputs, handle network failures, and log at the right level.

Documentation and Handoff

# summarize.py — summarizes customer tickets via the API
# ENV: API_URL, API_KEY
# Run: python summarize.py

Explanation: a short header tells the customer's team what the script does, what env vars it needs, and how to run it. Pair this with a README.

Best Practice: Write for the team that inherits the code — clear names, a README, and run instructions beat clever one-liners.