hakmem/docs/status/DEBUG_ENV_CONSOLIDATION.md

Debug Environment Variables Consolidation

Date: 2025-11-29 Status: Phase 1 Complete (4 vars consolidated) Total Survey: 43+ debug/trace/log environment variables

---

Summary

Successfully consolidated 4 new debug environment variables added during bug fixes into the existing HAKMEM_DEBUG_LEVEL system (expanded to 0-5 levels).

Impact

• Before: 43+ individual debug environment variables
• After (Phase 1): 4 consolidated to HAKMEM_DEBUG_LEVEL
• Target (Future): Consolidate 30+ more variables

---

Unified Debug Level System

Level Definitions

HAKMEM_DEBUG_LEVEL=<0-5>

0 = OFF       Production mode (all debug disabled)
1 = ERROR     Critical errors only
2 = WARN      Warnings + errors
3 = INFO      Allocation paths, header validation, stats
4 = DEBUG     Guard instrumentation, failfast
5 = TRACE     Verbose tracing (all debug output)

Usage Examples

# Production (default)
HAKMEM_DEBUG_LEVEL=0 ./larson_hakmem ...

# Enable allocation path tracking + header validation
HAKMEM_DEBUG_LEVEL=3 ./larson_hakmem ...

# Enable all debug features including guard/failfast
HAKMEM_DEBUG_LEVEL=4 ./larson_hakmem ...

# Full verbose tracing
HAKMEM_DEBUG_LEVEL=5 ./larson_hakmem ...

---

Phase 1: Completed (2025-11-29)

Consolidated Variables

Old ENV Variable	New Control	Level	Commit
HAKMEM_ALLOC_PATH_TRACE	HAKMEM_DEBUG_LEVEL >= 3	INFO	3f461ba25
HAKMEM_TINY_SLL_VALIDATE_HDR	HAKMEM_DEBUG_LEVEL >= 3	INFO	3f461ba25
HAKMEM_TINY_REFILL_FAILFAST	HAKMEM_DEBUG_LEVEL >= 4	DEBUG	3f461ba25
HAKMEM_TINY_GUARD	HAKMEM_DEBUG_LEVEL >= 4	DEBUG	3f461ba25

Kept for Special Purposes

ENV Variable	Purpose	Reason
HAKMEM_TINY_GUARD_CLASS	Target class for guard (0-7)	Fine-grained control
HAKMEM_TINY_GUARD_MAX	Max guard events (default: 8)	Fine-grained control

Backward Compatibility

✅ All legacy environment variables still work

• Uses hak_debug_check_level() for compatibility
• Old code continues to function
• Graceful migration path

---

Remaining Variables (Future Work)

Category A: General Debug Control (4 vars)

• HAKMEM_DEBUG_ALL → Consolidate to LEVEL=5
• HAKMEM_TRACE_LEVEL → Consolidate to LEVEL
• HAKMEM_TRACE → Consolidate to LEVEL=5

Category B: Component Debug (4 vars)

• HAKMEM_ACE_DEBUG → Consolidate to LEVEL>=2
• HAKMEM_ACE_LOG_LEVEL → Consolidate to LEVEL
• HAKMEM_ADAPTIVE_LOG → Consolidate to LEVEL>=3
• HAKMEM_SFC_DEBUG → Consolidate to LEVEL>=3

Category C: Pointer Tracing (5 vars)

• HAKMEM_PTR_TRACE → Consolidate to LEVEL>=4
• HAKMEM_PTR_TRACE_ALL → Consolidate to LEVEL=5
• HAKMEM_PTR_TRACE_CLASS → Keep (special purpose)
• HAKMEM_PTR_TRACE_DUMP → Consolidate to LEVEL=5
• HAKMEM_PTR_TRACE_VERBOSE → Consolidate to LEVEL=5

Category D: SuperSlab Debug (7 vars)

• HAKMEM_SS_ACQUIRE_DEBUG → Consolidate to LEVEL>=3
• HAKMEM_SS_FREE_DEBUG → Consolidate to LEVEL>=3
• HAKMEM_SS_LRU_DEBUG → Consolidate to LEVEL>=4
• HAKMEM_SS_PREWARM_DEBUG → Consolidate to LEVEL>=3
• HAKMEM_SUPER_LOOKUP_DEBUG → Consolidate to LEVEL>=3
• HAKMEM_SUPER_REG_DEBUG → Consolidate to LEVEL>=3
• HAKMEM_SUPER_REG_REQTRACE → Consolidate to LEVEL>=4

Category E: Tiny Allocator Debug (15+ vars)

• HAKMEM_TINY_ALLOC_DEBUG → Consolidate to LEVEL>=3
• HAKMEM_TINY_DEBUG_FAST → Consolidate to LEVEL>=3
• HAKMEM_TINY_DEBUG_REMOTE_GUARD → Consolidate to LEVEL>=4
• HAKMEM_TINY_FAST_DEBUG → Consolidate to LEVEL>=3
• HAKMEM_TINY_FAST_DEBUG_MAX → Keep (special purpose)
• HAKMEM_TINY_HEAP_V → Consolidate to LEVEL>=3
• HAKMEM_TINY_MAILBOX_TRACE_LIMIT → Keep (special purpose)
• HAKMEM_TINY_PATH_DEBUG → Consolidate to LEVEL>=3
• HAKMEM_TINY_REFILL_OPT_DEBUG → Consolidate to LEVEL>=3
• HAKMEM_TINY_RF_TRACE → Consolidate to LEVEL>=4
• HAKMEM_TINY_SLL_DRAIN_DEBUG → Consolidate to LEVEL>=3
• HAKMEM_TINY_SUPERSLAB_TRACE → Consolidate to LEVEL>=4
• HAKMEM_TINY_TRACE_RING → Consolidate to LEVEL>=4
• HAKMEM_TINY_ULTRA_DEBUG → Consolidate to LEVEL=5

Category F: Free Path Tracing (3 vars)

• HAKMEM_FREE_ROUTE_TRACE → Consolidate to LEVEL>=3
• HAKMEM_FREE_WRAP_TRACE → Consolidate to LEVEL>=3
• HAKMEM_INVALID_FREE_LOG → Consolidate to LEVEL>=2

Category G: Misc Debug (5 vars)

• HAKMEM_DEBUG_SEGV → Consolidate to LEVEL>=1
• HAKMEM_EXTERNAL_GUARD_LOG → Consolidate to LEVEL>=3
• HAKMEM_FOO_DEBUG → Remove (unused test var)
• HAKMEM_FOO_TRACE → Remove (unused test var)
• HAKMEM_LOG_FILE → Keep (special purpose)

---

Consolidation Plan (Phase 2-4)

Phase 2: High-Priority Consolidation (10-15 vars)

Target: SuperSlab + Tiny Allocator debug variables Effort: 4-6 hours Impact: Most frequently used debug variables

Candidates:

• Category D: SuperSlab Debug (7 vars)
• Category E: High-frequency Tiny debug (5 vars)

Phase 3: Component Debug Consolidation (10-15 vars)

Target: Component-specific debug variables Effort: 3-4 hours Impact: Cleaner component debugging

Candidates:

• Category B: Component Debug (4 vars)
• Category C: Pointer Tracing (consolidate 3/5)
• Category F: Free Path Tracing (3 vars)

Phase 4: Cleanup & Documentation (5-10 vars)

Target: Remaining + unused variables Effort: 2-3 hours Impact: Final cleanup

Tasks:

• Remove unused test variables (FOO_DEBUG, etc.)
• Document special-purpose variables
• Update ENV_VARS.md with consolidated list

---

Estimated Final State

After Full Consolidation

Environment Variables:

• HAKMEM_DEBUG_LEVEL=<0-5> - Main debug control
• HAKMEM_QUIET=1 - Suppress all debug (override)
• HAKMEM_DEBUG_ALL=1 - Enable all debug (legacy)

Special-Purpose (5-10 vars):

• HAKMEM_TINY_GUARD_CLASS - Guard target class
• HAKMEM_TINY_GUARD_MAX - Guard event limit
• HAKMEM_PTR_TRACE_CLASS - Pointer trace class
• HAKMEM_TINY_FAST_DEBUG_MAX - Fast debug limit
• HAKMEM_LOG_FILE - Log file path
• ...

Total: 10-15 variables (down from 43+)

Reduction: ~70% fewer environment variables

---

References

• Master debug header: core/hakmem_debug_master.h
• Consolidated variables: commits 20f8d6f17, 3f461ba25
• Full survey: 43+ debug/trace/log variables identified (2025-11-29)
• Implementation: hak_debug_check_level() API

---

Migration Guide

For Users

Old way (still works):

HAKMEM_ALLOC_PATH_TRACE=1 ./larson_hakmem ...
HAKMEM_TINY_SLL_VALIDATE_HDR=1 ./larson_hakmem ...

New way (recommended):

HAKMEM_DEBUG_LEVEL=3 ./larson_hakmem ...

For Developers

Old pattern:

static int dbg = -1;
if (dbg == -1) {
    const char* e = getenv("HAKMEM_FOO_DEBUG");
    dbg = (e && *e && *e != '0') ? 1 : 0;
}

New pattern:

static int dbg = -1;
if (dbg == -1) {
    dbg = hak_debug_check_level("HAKMEM_FOO_DEBUG", 3);  // INFO level
}

---

Acknowledgments

• Initial consolidation: Claude Code (ultrathink) + Task agent
• Survey and planning: 2025-11-29
• Implementation: commits 20f8d6f17, 3f461ba25