Module debug_output 

Structured debug output infrastructure

This module provides a unified interface for debug/profiling output that can emit either human-readable text (default) or machine-parseable JSON.

Environment Variables

• VIBESQL_DEBUG_FORMAT=json - Output JSON to stderr (for agents/CI)
• VIBESQL_DEBUG_FORMAT=text - Output human-readable text (default)

JSON Schema

All JSON output follows this structure:

{
  "timestamp": "2024-01-15T10:30:00.123Z",
  "category": "optimizer",
  "event": "join_reorder",
  "data": { ... }
}

Categories

• optimizer - Query optimization decisions (join reorder, table elimination, etc.)
• execution - Execution timing and statistics
• index - Index selection and usage
• dml - DML operation timing (insert, update, delete)
• profile - General profiling output

Macros

debug_emit

Macro for creating debug events with both text and JSON output

Structs

DebugEvent

A builder for constructing debug output with optional JSON fields

Enums

Category

Debug output categories

DebugFormat

Output format for debug messages

JsonValue

JSON value types (simplified, no external dependency)

Functions

debug_event

Convenience function to create a debug event

get_format

Get the current debug output format

init

Initialize debug format from environment variable. Call this once at program start.

is_json

Check if JSON output is enabled