UAT: `configure_structlog()` rejects `TRACE` log level — spec-required verbosity level not supported #1934

New issue

Open

opened 2026-04-03 00:17:28 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 00:17:28 +00:00

Owner

Metadata

Branch: bugfix/m36-trace-log-level
Commit Message: fix(logging): register TRACE log level and accept it in configure_structlog()
Milestone: v3.6.0

Background and Context

The specification defines TRACE as a valid log level — the most granular verbosity tier, activated by the -vvvvv CLI flag (§Global Configuration Keys). However, configure_structlog() in src/cleveragents/config/logging.py raises a ValueError when called with log_level='TRACE', making the spec-required verbosity level completely unusable.

Current Behavior

from cleveragents.config.logging import configure_structlog

configure_structlog(log_level='TRACE')
# Raises: ValueError: Invalid log level: 'TRACE'

Root Cause:
configure_structlog() uses getattr(logging, log_level.upper(), None) to resolve the log level to a numeric value. Python's standard logging module does not define a TRACE level (it only defines DEBUG, INFO, WARNING, ERROR, CRITICAL/FATAL). Since logging.TRACE does not exist, the isinstance(numeric_level, int) guard raises ValueError.

Code Location: src/cleveragents/config/logging.py, lines 44–46:

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

Expected Behavior

Per spec §Global Configuration Keys, the following log levels are defined (least to most verbose):
FATAL, ERROR, WARN, INFO, DEBUG, TRACE

The -vvvvv flag must activate TRACE level. configure_structlog() must accept TRACE as a valid level without raising an exception.

Acceptance Criteria

configure_structlog(log_level='TRACE') completes without raising ValueError or any other exception.
TRACE is registered as a custom level with Python's logging module at numeric value 5 (below DEBUG=10).
Settings.log_level validator accepts 'TRACE' as a valid value.
The -vvvvv CLI flag correctly maps to TRACE level end-to-end.
All existing log level tests continue to pass.

Supporting Information

Spec reference: §Global Configuration Keys (line 30509) — defines TRACE as the most verbose log level.
Python logging module only defines levels: CRITICAL=50, ERROR=40, WARNING=30, INFO=20, DEBUG=10, NOTSET=0. TRACE must be added via logging.addLevelName(5, 'TRACE').
Fix approach: register the custom level before the getattr lookup, or map 'TRACE' to 5 explicitly prior to resolution.

Subtasks

Register TRACE as a custom logging level (logging.addLevelName(5, 'TRACE')) at module import time
Update configure_structlog() to accept 'TRACE' without raising ValueError
Update Settings.log_level validator to include 'TRACE' in the set of accepted values
Verify -vvvvv CLI flag maps correctly to TRACE level end-to-end
Tests (Behave): Add scenario for configure_structlog(log_level='TRACE') succeeding
Tests (Behave): Add scenario for Settings accepting log_level='TRACE'
Verify coverage >=97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
configure_structlog(log_level='TRACE') succeeds without raising ValueError.
TRACE level is properly registered with Python's logging module at numeric value 5.
Settings.log_level accepts 'TRACE' as a valid value.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass.
Coverage >= 97%.

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

## Metadata - **Branch**: `bugfix/m36-trace-log-level` - **Commit Message**: `fix(logging): register TRACE log level and accept it in configure_structlog()` - **Milestone**: v3.6.0 ## Background and Context The specification defines `TRACE` as a valid log level — the most granular verbosity tier, activated by the `-vvvvv` CLI flag (§Global Configuration Keys). However, `configure_structlog()` in `src/cleveragents/config/logging.py` raises a `ValueError` when called with `log_level='TRACE'`, making the spec-required verbosity level completely unusable. ## Current Behavior ```python from cleveragents.config.logging import configure_structlog configure_structlog(log_level='TRACE') # Raises: ValueError: Invalid log level: 'TRACE' ``` **Root Cause:** `configure_structlog()` uses `getattr(logging, log_level.upper(), None)` to resolve the log level to a numeric value. Python's standard `logging` module does not define a `TRACE` level (it only defines `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`/`FATAL`). Since `logging.TRACE` does not exist, the `isinstance(numeric_level, int)` guard raises `ValueError`. **Code Location:** `src/cleveragents/config/logging.py`, lines 44–46: ```python numeric_level = getattr(logging, log_level.upper(), None) if not isinstance(numeric_level, int): raise ValueError(f"Invalid log level: {log_level!r}") ``` ## Expected Behavior Per spec §Global Configuration Keys, the following log levels are defined (least to most verbose): `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE` The `-vvvvv` flag must activate `TRACE` level. `configure_structlog()` must accept `TRACE` as a valid level without raising an exception. ## Acceptance Criteria - `configure_structlog(log_level='TRACE')` completes without raising `ValueError` or any other exception. - `TRACE` is registered as a custom level with Python's `logging` module at numeric value `5` (below `DEBUG=10`). - `Settings.log_level` validator accepts `'TRACE'` as a valid value. - The `-vvvvv` CLI flag correctly maps to `TRACE` level end-to-end. - All existing log level tests continue to pass. ## Supporting Information - Spec reference: §Global Configuration Keys (line 30509) — defines `TRACE` as the most verbose log level. - Python `logging` module only defines levels: `CRITICAL=50`, `ERROR=40`, `WARNING=30`, `INFO=20`, `DEBUG=10`, `NOTSET=0`. `TRACE` must be added via `logging.addLevelName(5, 'TRACE')`. - Fix approach: register the custom level before the `getattr` lookup, or map `'TRACE'` to `5` explicitly prior to resolution. ## Subtasks - [ ] Register `TRACE` as a custom logging level (`logging.addLevelName(5, 'TRACE')`) at module import time - [ ] Update `configure_structlog()` to accept `'TRACE'` without raising `ValueError` - [ ] Update `Settings.log_level` validator to include `'TRACE'` in the set of accepted values - [ ] Verify `-vvvvv` CLI flag maps correctly to `TRACE` level end-to-end - [ ] Tests (Behave): Add scenario for `configure_structlog(log_level='TRACE')` succeeding - [ ] Tests (Behave): Add scenario for `Settings` accepting `log_level='TRACE'` - [ ] Verify coverage >=97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - `configure_structlog(log_level='TRACE')` succeeds without raising `ValueError`. - `TRACE` level is properly registered with Python's `logging` module at numeric value `5`. - `Settings.log_level` accepts `'TRACE'` as a valid value. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage >= 97%. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.6.0 milestone

2026-04-03 00:17:53 +00:00

freemo referenced this issue

2026-04-03 00:18:37 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 481 — v3.7.0 #1938

freemo commented

2026-04-03 00:19:47 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: MoSCoW/Should Have — bug or error handling improvement.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: MoSCoW/Should Have — bug or error handling improvement. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added a new dependency

2026-04-03 00:23:02 +00:00

#945 Legendary: Specification Alignment — Close All Gaps Between Implementation and Specification

freemo referenced this issue

2026-04-03 00:25:33 +00:00

UAT: Settings.log_level default is 'INFO' instead of spec-required 'FATAL' — inconsistent with ConfigService and spec #1967

freemo referenced this issue

2026-04-03 00:28:56 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 491 — v3.7.0 #1976