Home/ Part III — Beginner Track: Learn to Communicate Like a Builder/8. A Gentle Intro to Debugging With AI/8.4 Prompting for logging and observability

8.4 Prompting for logging and observability

Overview and links for this section of the guide.

On this page

Why logging is a vibe-coding accelerator

Good logs shorten the loop because they turn “it didn’t work” into “it failed at step 3 with error X after 1200ms.” That’s actionable.

With AI-assisted development, logs are even more important because:

  • generated code may have hidden assumptions,
  • LLM calls have variable latency and failure modes,
  • issues often involve boundary conditions (inputs, parsing, serialization).
Logs are debugging context you don’t have to paste

If your logs already contain the key facts, you can paste a small excerpt and get a high-quality diagnosis.

What to log (high signal, low risk)

Start minimal. The best early logs answer: “what happened, where, how long, and why did it fail?”

  • Request/operation ID: a correlation id you can follow through the flow.
  • Stage: which step you’re in (parse, validate, call model, render output).
  • Latency: how long each stage took.
  • Outcome category: ok / validation_error / rate_limit / timeout / blocked / unknown.
  • Sizes: input length, token estimates, result length (counts, not raw content).
  • Error code/message: categorized and safe to share.
Prefer metadata over raw content

For debugging, “input_length=12000” is often as useful as the full input—and far safer.

What not to log (privacy + secrets)

Common logging mistakes create long-term risk:

  • API keys, tokens, auth headers, cookies.
  • full prompts or full user inputs (often contain sensitive info).
  • PII (emails, addresses, phone numbers) unless you have a policy and redaction.
  • full model outputs if they include user data.
Logs become permanent

Logs are copied, shipped, retained, and searched. Treat them like production data even in prototypes.

Where to add logs (the best choke points)

You don’t need logs everywhere. Add logs at choke points:

  • Entry points: CLI handler, HTTP handler, job worker start.
  • Boundary transitions: raw input → parsed structure; validated → processed.
  • External calls: model request start/end; retries; timeouts.
  • Error boundaries: where exceptions are caught and mapped to user-visible outcomes.

Choke points give you a high-level trace with very few log lines.

Log levels and structure (keep it readable)

Even for small projects, separate log intent:

  • INFO: start/end of an operation, success summary.
  • WARN: recoverable issues (retry, partial output, validation failures).
  • ERROR: failures that stop the operation.
  • DEBUG: detailed internals (enable temporarily).

If you can, prefer structured fields (JSON logs) over unstructured text so you can filter and search reliably.

For AI apps, log “prompt version” not “prompt content”

Prompts are behavior. Version them and log the version id. That gives you reproducibility without leaking text.

Copy-paste prompt templates

Template: add minimal logs safely

Add minimal logging to this code to make debugging easier.

Requirements:
- Do NOT log secrets or raw user content
- Prefer metadata: sizes, durations, outcome categories
- Add a request/operation id and include it in all logs for that operation
- Keep the diff small and localized

Output:
- Diff-only changes
- After the diff, list the log lines/fields and where they occur

Template: standardize error categories

Standardize error handling into these categories:
- validation_error
- auth_error
- rate_limit
- timeout
- blocked
- invalid_output
- unknown

Requirements:
- Map current exceptions/errors into these categories
- Ensure user-facing messages are clear
- Do not leak sensitive details

Output:
- Plan first, then diff-only changes

Where to go next