UAT: `configure_structlog` raises ValueError for TRACE log level — spec-required level unsupported #3925

New issue

Open

opened 2026-04-06 07:28:55 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 07:28:55 +00:00

Owner

Summary

The configure_structlog() function in src/cleveragents/config/logging.py raises a ValueError when called with log_level="TRACE", even though the specification explicitly defines TRACE as the most granular log level (-vvvvv).

Expected Behavior (from spec)

Per docs/specification.md §Observability and the global configuration table:

core.log.level accepted values: FATAL, ERROR, WARN, INFO, DEBUG, TRACE
The -v CLI flag repeated 5 times (-vvvvv) should set the level to TRACE
configure_structlog(log_level="TRACE") must succeed

Actual Behavior

from cleveragents.config.logging import configure_structlog
configure_structlog(log_level="TRACE")
# Raises: ValueError: Invalid log level: 'TRACE'

The function uses getattr(logging, log_level.upper(), None) to resolve the level. Python's standard logging module does not define a TRACE level, so getattr(logging, "TRACE", None) returns None, which fails the isinstance(numeric_level, int) check.

Root Cause

src/cleveragents/config/logging.py lines 45-47:

numeric_level = getattr(logging, log_level.upper(), None)
if not isinstance(numeric_level, int):
    raise ValueError(f"Invalid log level: {log_level!r}")

Python's logging module has no TRACE level. The fix requires registering a custom TRACE level (e.g., logging.addLevelName(5, "TRACE")) before attempting to resolve it.

Steps to Reproduce

from cleveragents.config.logging import configure_structlog
configure_structlog(log_level="TRACE")

Impact

The -vvvvv CLI flag (TRACE level) is completely broken
Any code path that reads core.log.level = "TRACE" from config and passes it to configure_structlog will crash
The spec-required TRACE level is unusable

Metadata

Branch: fix/configure-structlog-trace-level
Commit Message: fix(config): register custom TRACE log level so configure_structlog accepts spec-required -vvvvv verbosity
Milestone: None (backlog — non-critical, discovered during autonomous UAT)
Parent Epic: #940

Backlog note: This issue was discovered during autonomous operation
on milestone v3.6.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Subtasks

Register TRACE as a custom logging level (value 5) in configure_structlog or at module import time via logging.addLevelName(5, "TRACE")
Add structlog support for TRACE level (custom bound method on BoundLogger)
Write TDD issue-capture Behave scenario tagged @tdd_expected_fail to prove the bug exists before fixing
Update unit tests in features/ to cover TRACE level configuration
Verify -vvvvv CLI flag correctly sets TRACE level end-to-end
Run nox (all default sessions) and fix any errors

Definition of Done

configure_structlog(log_level="TRACE") succeeds without error
TRACE-level log messages are emitted when level is set to TRACE
TDD issue-capture scenario (@tdd_expected_fail) committed before fix
Unit tests (Behave) cover TRACE level configuration
All nox stages pass
Coverage >= 97%
PR merged and issue closed

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Summary The `configure_structlog()` function in `src/cleveragents/config/logging.py` raises a `ValueError` when called with `log_level="TRACE"`, even though the specification explicitly defines TRACE as the most granular log level (`-vvvvv`). ## Expected Behavior (from spec) Per `docs/specification.md` §Observability and the global configuration table: - `core.log.level` accepted values: `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE` - The `-v` CLI flag repeated 5 times (`-vvvvv`) should set the level to TRACE - `configure_structlog(log_level="TRACE")` must succeed ## Actual Behavior ```python from cleveragents.config.logging import configure_structlog configure_structlog(log_level="TRACE") # Raises: ValueError: Invalid log level: 'TRACE' ``` The function uses `getattr(logging, log_level.upper(), None)` to resolve the level. Python's standard `logging` module does not define a `TRACE` level, so `getattr(logging, "TRACE", None)` returns `None`, which fails the `isinstance(numeric_level, int)` check. ## Root Cause `src/cleveragents/config/logging.py` lines 45-47: ```python numeric_level = getattr(logging, log_level.upper(), None) if not isinstance(numeric_level, int): raise ValueError(f"Invalid log level: {log_level!r}") ``` Python's `logging` module has no `TRACE` level. The fix requires registering a custom TRACE level (e.g., `logging.addLevelName(5, "TRACE")`) before attempting to resolve it. ## Steps to Reproduce ```python from cleveragents.config.logging import configure_structlog configure_structlog(log_level="TRACE") ``` ## Impact - The `-vvvvv` CLI flag (TRACE level) is completely broken - Any code path that reads `core.log.level = "TRACE"` from config and passes it to `configure_structlog` will crash - The spec-required TRACE level is unusable ## Metadata - **Branch**: `fix/configure-structlog-trace-level` - **Commit Message**: `fix(config): register custom TRACE log level so configure_structlog accepts spec-required -vvvvv verbosity` - **Milestone**: None (backlog — non-critical, discovered during autonomous UAT) - **Parent Epic**: #940 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.6.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Subtasks - [ ] Register TRACE as a custom logging level (value 5) in `configure_structlog` or at module import time via `logging.addLevelName(5, "TRACE")` - [ ] Add structlog support for TRACE level (custom bound method on BoundLogger) - [ ] Write TDD issue-capture Behave scenario tagged `@tdd_expected_fail` to prove the bug exists before fixing - [ ] Update unit tests in `features/` to cover TRACE level configuration - [ ] Verify `-vvvvv` CLI flag correctly sets TRACE level end-to-end - [ ] Run `nox` (all default sessions) and fix any errors ## Definition of Done - [ ] `configure_structlog(log_level="TRACE")` succeeds without error - [ ] TRACE-level log messages are emitted when level is set to TRACE - [ ] TDD issue-capture scenario (`@tdd_expected_fail`) committed before fix - [ ] Unit tests (Behave) cover TRACE level configuration - [ ] All nox stages pass - [ ] Coverage >= 97% - [ ] PR merged and issue closed --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-06 07:29:17 +00:00

#940 feat(observability): implement Prometheus metrics export and event-to-audit bridge

freemo referenced this issue

2026-04-06 07:39:13 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 07:49:16 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 10:35:53 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775