Debug Logging

Debug Logging

Overview

Debug logging creates an exhaustive diagnostic log for troubleshooting prototype sessions. It captures full AI call payloads, state mutations, decision branches, slash commands, and error tracebacks.

The log is designed to be read by anyone -- developers, testers, or end-users -- without needing to reproduce the issue.

Enabling Debug Logging

Set the DEBUG_PROTOTYPE environment variable to true before running any prototype command:

# Windows (PowerShell)
$env:DEBUG_PROTOTYPE = "true"
az prototype design --artifacts ../artifacts/

# Windows (cmd)
set DEBUG_PROTOTYPE=true
az prototype design --artifacts ../artifacts/

# Linux / macOS
DEBUG_PROTOTYPE=true az prototype design --artifacts ../artifacts/

Log File Location

The log file is created in the project directory with the name:

debug_YYYYMMDDHHMMSS.log

Where YYYYMMDDHHMMSS is the timestamp when the session started. Example: debug_20260325143045.log.

Log Categories

SESSION_START

Logged once at the beginning of a session with environment and configuration context:

2026-03-25 14:30:45 | SESSION_START
  Python: 3.12.10
  OS: Windows 10.0.26100 (AMD64)
  Extension: 0.2.1b6
  Project: C:\Users\joshua\projects\testing
  AI Provider: copilot (claude-sonnet-4.5)
  Timeout: 480s
  IaC Tool: terraform

AI_CALL / AI_RESPONSE

Every AI call is logged with full payload details:

2026-03-25 14:30:52 | AI_CALL DiscoverySession._chat
  System messages: 5 msgs, 69,234 chars
  History messages: 4 msgs, 12,891 chars
  User message: 2,340 chars
  Total payload: 84,465 chars
  Model: claude-sonnet-4.5, Temperature: 0.5, Max tokens: 8192
  --- USER MESSAGE ---
  The user answered about **Authentication**: Use Stytch for...
  --- END USER MESSAGE ---

2026-03-25 14:31:18 | AI_RESPONSE DiscoverySession._chat
  Elapsed: 26.3s
  Response: 1,847 chars
  Tokens: prompt=21450 completion=892 total=22342
  --- RESPONSE ---
  Yes
  --- END RESPONSE ---

STATE

State mutations are logged with the operation and details:

2026-03-25 14:31:18 | STATE mark_item
  heading=Authentication & Identity
  status=answered
  exchange=4

2026-03-25 14:31:18 | STATE save
  path=.prototype/state/discovery.yaml
  items=16
  exchanges=4
  inventory_files=8

FLOW

Decision branches and control flow transitions:

2026-03-25 14:30:49 | FLOW DiscoverySession.run
  Entry
  has_items=True
  item_count=16
  pending=13
  seed_context_len=35
  artifacts_len=0
  context_only=True

COMMAND

Slash commands (not counted as AI exchanges):

2026-03-25 14:32:10 | COMMAND
  command=/status
  topic=Authentication & Identity
  real_answers=0

ERROR

Errors with full Python tracebacks:

2026-03-25 14:35:00 | ERROR CopilotProvider.chat
  exception=CLIError: Copilot API timed out after 480s.
  elapsed_s=480.1
  timeout=480
  --- TRACEBACK ---
  Traceback (most recent call last):
    ...
  --- END TRACEBACK ---

Privacy Notes

The debug log may contain:

• Project configuration details (provider, model, IaC tool)
• Discovery conversation content (user input and AI responses)
• File paths and artifact names
• Token counts and timing information

It does not contain:

• API keys or secrets (these are in prototype.secrets.yaml, not logged)
• Full governance policy content (only sizes are logged)
• Azure subscription IDs or credentials

When sharing log files for support, review the content and redact any sensitive project information if needed.

Related

• Troubleshooting -- common issues and diagnostic commands
• AI Providers -- provider configuration and timeout settings