From 49a253dfedbdf716a482fde281834e309d323ec7 Mon Sep 17 00:00:00 2001 From: "Moe Charm (CI)" Date: Sat, 29 Nov 2025 06:58:12 +0900 Subject: [PATCH] Doc: Add debug ENV consolidation plan and survey MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documented Phase 1 completion and future consolidation plan for 43+ debug environment variables surveyed during cleanup work. Content: - Phase 1 summary (4 vars consolidated) - Complete survey of 43+ debug/trace/log variables - Categorization (7 categories) - Phase 2-4 consolidation plan - Migration guide for users and developers Impact: - Clear roadmap for reducing 43+ vars to 10-15 - ~70% reduction in environment variable count - Better discoverability and usability 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/status/DEBUG_ENV_CONSOLIDATION.md | 245 +++++++++++++++++++++++++ 1 file changed, 245 insertions(+) create mode 100644 docs/status/DEBUG_ENV_CONSOLIDATION.md diff --git a/docs/status/DEBUG_ENV_CONSOLIDATION.md b/docs/status/DEBUG_ENV_CONSOLIDATION.md new file mode 100644 index 00000000..5412267f --- /dev/null +++ b/docs/status/DEBUG_ENV_CONSOLIDATION.md @@ -0,0 +1,245 @@ +# 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 + +```bash +# 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):** +```bash +HAKMEM_ALLOC_PATH_TRACE=1 ./larson_hakmem ... +HAKMEM_TINY_SLL_VALIDATE_HDR=1 ./larson_hakmem ... +``` + +**New way (recommended):** +```bash +HAKMEM_DEBUG_LEVEL=3 ./larson_hakmem ... +``` + +### For Developers + +**Old pattern:** +```c +static int dbg = -1; +if (dbg == -1) { + const char* e = getenv("HAKMEM_FOO_DEBUG"); + dbg = (e && *e && *e != '0') ? 1 : 0; +} +``` + +**New pattern:** +```c +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