UAT: `configure_structlog()` rejects `'TRACE'` log level — spec requires TRACE support #2863

New issue

Open

opened 2026-04-04 21:04:29 +00:00 by freemo · 0 comments

freemo commented

2026-04-04 21:04:29 +00:00

Owner

Metadata

Branch: fix/configure-structlog-trace-log-level
Commit Message: fix(config): register TRACE as a custom log level in configure_structlog()
Milestone: v3.7.0
Parent Epic: #362

Bug Description

The configure_structlog() function in src/cleveragents/config/logging.py rejects 'TRACE' as a log level with a ValueError, but the specification explicitly lists TRACE as a valid log level for core.log.level.

Expected Behavior (from spec)

The spec defines core.log.level description as:

"Logging verbosity: FATAL, ERROR, WARN, INFO, DEBUG, TRACE."

TRACE must be a supported log level accepted by configure_structlog().

Actual 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 validate the log level. Python's standard logging module does not define TRACE as a level, so the validation fails.

# src/cleveragents/config/logging.py
def configure_structlog(*, env: str = "development", log_level: str = "INFO") -> None:
    numeric_level = getattr(logging, log_level.upper(), None)
    if not isinstance(numeric_level, int):
        raise ValueError(f"Invalid log level: {log_level!r}")  # TRACE fails here

Additional Inconsistency

The server serve command's _normalize_log_level() correctly accepts 'trace' (lowercase), but configure_structlog() does not. This means the server can be started with --log-level trace but the structlog configuration will fail if CLEVERAGENTS_LOG_LEVEL=TRACE is set — a silent inconsistency between the CLI layer and the logging configuration layer.

Verified by Running

from cleveragents.config.logging import configure_structlog
configure_structlog(log_level='TRACE')  # ValueError: Invalid log level: 'TRACE'
configure_structlog(log_level='FATAL')  # Works fine
configure_structlog(log_level='WARN')   # Works fine (Python alias for WARNING)

Code Location

src/cleveragents/config/logging.py — configure_structlog() function

Subtasks

Register TRACE as a custom log level (e.g., logging.addLevelName(5, 'TRACE')) before the validation step in configure_structlog(), or add explicit handling for the 'TRACE' string
Ensure TRACE maps to numeric level 5 (below DEBUG = 10) consistent with structlog conventions
Write a failing Behave scenario first (TDD): configure_structlog(log_level='TRACE') must not raise
Write a Behave scenario confirming TRACE level is correctly passed through to structlog/stdlib
Verify CLEVERAGENTS_LOG_LEVEL=TRACE env var works end-to-end (Settings → configure_structlog)
Verify _normalize_log_level() in the server CLI and configure_structlog() are now consistent in their acceptance of 'trace'/'TRACE'
Run nox -e typecheck — confirm no type regressions
Run nox -e unit_tests — all Behave scenarios pass
Run nox -e coverage_report — coverage remains ≥ 97%

Definition of Done

configure_structlog(log_level='TRACE') no longer raises ValueError
TRACE is registered as a valid Python logging level with numeric value 5
CLEVERAGENTS_LOG_LEVEL=TRACE is accepted end-to-end without error
configure_structlog() and _normalize_log_level() are consistent in their accepted log levels
Behave scenarios added covering the TRACE log level acceptance
All nox stages pass
Coverage >= 97%

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

## Metadata - **Branch**: `fix/configure-structlog-trace-log-level` - **Commit Message**: `fix(config): register TRACE as a custom log level in configure_structlog()` - **Milestone**: v3.7.0 - **Parent Epic**: #362 ## Bug Description The `configure_structlog()` function in `src/cleveragents/config/logging.py` rejects `'TRACE'` as a log level with a `ValueError`, but the specification explicitly lists TRACE as a valid log level for `core.log.level`. ### Expected Behavior (from spec) The spec defines `core.log.level` description as: > "Logging verbosity: FATAL, ERROR, WARN, INFO, DEBUG, TRACE." TRACE must be a supported log level accepted by `configure_structlog()`. ### Actual 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 validate the log level. Python's standard `logging` module does not define `TRACE` as a level, so the validation fails. ```python # src/cleveragents/config/logging.py def configure_structlog(*, env: str = "development", log_level: str = "INFO") -> None: numeric_level = getattr(logging, log_level.upper(), None) if not isinstance(numeric_level, int): raise ValueError(f"Invalid log level: {log_level!r}") # TRACE fails here ``` ### Additional Inconsistency The `server serve` command's `_normalize_log_level()` correctly accepts `'trace'` (lowercase), but `configure_structlog()` does not. This means the server can be started with `--log-level trace` but the structlog configuration will fail if `CLEVERAGENTS_LOG_LEVEL=TRACE` is set — a silent inconsistency between the CLI layer and the logging configuration layer. ### Verified by Running ```python from cleveragents.config.logging import configure_structlog configure_structlog(log_level='TRACE') # ValueError: Invalid log level: 'TRACE' configure_structlog(log_level='FATAL') # Works fine configure_structlog(log_level='WARN') # Works fine (Python alias for WARNING) ``` ### Code Location `src/cleveragents/config/logging.py` — `configure_structlog()` function ## Subtasks - [ ] Register `TRACE` as a custom log level (e.g., `logging.addLevelName(5, 'TRACE')`) before the validation step in `configure_structlog()`, or add explicit handling for the `'TRACE'` string - [ ] Ensure `TRACE` maps to numeric level `5` (below `DEBUG = 10`) consistent with structlog conventions - [ ] Write a failing Behave scenario first (TDD): `configure_structlog(log_level='TRACE')` must not raise - [ ] Write a Behave scenario confirming `TRACE` level is correctly passed through to structlog/stdlib - [ ] Verify `CLEVERAGENTS_LOG_LEVEL=TRACE` env var works end-to-end (Settings → configure_structlog) - [ ] Verify `_normalize_log_level()` in the server CLI and `configure_structlog()` are now consistent in their acceptance of `'trace'`/`'TRACE'` - [ ] Run `nox -e typecheck` — confirm no type regressions - [ ] Run `nox -e unit_tests` — all Behave scenarios pass - [ ] Run `nox -e coverage_report` — coverage remains ≥ 97% ## Definition of Done - [ ] `configure_structlog(log_level='TRACE')` no longer raises `ValueError` - [ ] `TRACE` is registered as a valid Python logging level with numeric value `5` - [ ] `CLEVERAGENTS_LOG_LEVEL=TRACE` is accepted end-to-end without error - [ ] `configure_structlog()` and `_normalize_log_level()` are consistent in their accepted log levels - [ ] Behave scenarios added covering the TRACE log level acceptance - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.7.0 milestone

2026-04-04 21:04:39 +00:00

freemo added a new dependency

2026-04-04 21:04:43 +00:00

#362 Epic: Security & Safety Hardening

freemo referenced this issue

2026-04-04 21:08:24 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2803

freemo referenced this issue

2026-04-04 21:10:01 +00:00

[CA-AUTO] Backlog Groomer — groomer-1 — Session Tracker #2771

freemo referenced this issue