Doc: Add debug ENV consolidation plan and survey
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 <noreply@anthropic.com>
This commit is contained in:
Moe Charm (CI)
245
docs/status/DEBUG_ENV_CONSOLIDATION.md
Normal file
245
docs/status/DEBUG_ENV_CONSOLIDATION.md
Normal file
@ -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
|
||||||
Reference in New Issue
Block a user