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