mellea-logging

name: mellea-logging description: > Best-practices guide for adding or reviewing logging in the Mellea codebase. Covers when to use log_context() vs a dedicated logger call, canonical field names, reserved attribute constraints, async/thread safety, and what events deserve dedicated log lines. Use when: adding a new log call; reviewing a PR that touches MelleaLogger; deciding where to inject context fields; debugging why a field is missing from a log record; or ensuring consistency with the project logging conventions. argument-hint: "[file-or-directory]" compatibility: "Claude Code, IBM Bob" metadata: version: "2026-04-15" capabilities: [read_file, grep, glob]

Mellea Logging Best Practices

All logging in Mellea flows through MelleaLogger.get_logger(), defined in mellea/core/utils.py. This skill documents the conventions for adding and reviewing log instrumentation.

Quick reference

from mellea.core import MelleaLogger, log_context, set_log_context, clear_log_context

logger = MelleaLogger.get_logger()

# Dedicated log call — for a discrete event
logger.info("SUCCESS")

# Context injection — attach fields to every record in a scope
with log_context(request_id="req-abc", trace_id="t-1"):
    logger.info("Starting generation")  # includes request_id, trace_id
    # ... all nested calls inherit these fields automatically

When to add a dedicated log call

Use logger.info/warning/error(...) for discrete, named events:

Do not add log calls for:

• Values already captured in a log_context field (redundant noise)
• Internal helper functions where the calling function already logs the event
• State that is already reflected in telemetry spans

When to use log_context

Use log_context (or set_log_context) to attach identifiers and metadata that should appear on every log record within a scope — without threading them through every call.

Typical injection points:

Canonical field names

Use these names consistently. Do not invent synonyms.

Reserved attribute names — do not use as context fields

The following names are standard logging.LogRecord attributes. Passing them to log_context() or set_log_context() raises ValueError. See RESERVED_LOG_RECORD_ATTRS in mellea/core/utils.py for the full set.

args, created, exc_info, exc_text, filename, funcName, levelname, levelno, lineno, message, module, msecs, msg, name, pathname, process, processName, relativeCreated, stack_info, thread, threadName

Prefer the context manager over set/clear

# Preferred — guaranteed cleanup even on exceptions
with log_context(trace_id="abc"):
    do_work()

# Acceptable only when lifetime equals __enter__/__exit__
# (e.g. MelleaSession, where the CM already guarantees cleanup)
set_log_context(session_id=self.id)
# ... later in __exit__ ...
clear_log_context()

The context manager uses a ContextVar token to restore the previous state on exit. This means nesting works correctly — inner calls can add fields without clobbering the outer scope's values.

Async and thread safety

log_context uses contextvars.ContextVar, which is safe for concurrent asyncio tasks:

• Each asyncio.Task gets its own copy of the context.
• Fields set in one task do not bleed into sibling tasks.

Plugin hooks: Mellea hooks (AUDIT, SEQUENTIAL, CONCURRENT) are awaited in the same asyncio task as the call site. ContextVar state IS inherited — fields set around a strategy.sample() call will appear on records emitted inside hook handlers automatically.

Checklist before committing

1. New log calls use MelleaLogger.get_logger(), not logging.getLogger(...).
2. Context fields use canonical names from the table above.
3. No reserved attribute names passed to log_context.
4. Scoped fields use with log_context(...), not set_log_context (unless managing an __enter__/__exit__ pair).
5. Hook handlers that need context set it internally — they do not inherit the caller's context.
6. New events that span multiple log records inject fields via context, not by repeating them on every logger.info(...) call.