OpenParable
Skip to content
← Back to skills

Mellea Logging

Development
mellea-logging

Mellea Logging is an Agent Skill for development published in the generative-computing/mellea repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/generative-computing/mellea/blob/HEAD/.agents/skills/mellea-logging/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/mellea-logging, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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:

Event typeLevelExample
Phase transitionINFO"SUCCESS", "FAILED", "Starting session"
Loop progressINFO"Running loop 2 of 3"
Recoverable issueWARNING"Warmup failed for model: ..."
Unexpected failureERRORexception tracebacks, hard failures
Verbose diagnosticsDEBUGtoken counts, prompt previews

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:

ScopeWhere to injectFields
Session lifetimeMelleaSession.__enter__session_id, backend, model_id
Sampling loopBaseSamplingStrategy.sample()strategy, loop_budget
HTTP request handlerentry point of the handlerrequest_id, trace_id
Background tasktop of the task coroutinetask_id, job_name

Canonical field names

Use these names consistently. Do not invent synonyms.

FieldTypeDescription
session_idstr (UUID)Unique ID for a MelleaSession
backendstrBackend class name, e.g. "OllamaModelBackend"
model_idstrModel identifier string
strategystrSampling strategy class name
loop_budgetintMax generate/validate cycles for this sampling call
request_idstrCaller-supplied request identifier
trace_idstrDistributed trace ID (from OpenTelemetry or caller)
span_idstrSpan ID within a trace
user_idstrEnd-user identifier (when applicable)

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.