Built-in Logging

These settings apply to the BaseModel Python App, through either its Python API or command-line interface.

By default BaseModel streams logs to the console at INFO level. For production runs or debugging you can redirect output to files, adjust verbosity, or separate error logs — all by pointing to a custom config file.

Custom Logging Config

Create a YAML file using Python's logging dict schema and set the MONAD_LOGGING_CONFIG_PATH environment variable before starting BaseModel:

export MONAD_LOGGING_CONFIG_PATH=/path/to/logging_config.yaml

Or pass it when launching the container:

docker run -it \
  -e MONAD_LOGGING_CONFIG_PATH=/workspace/logging_config.yaml \
  --gpus all --shm-size 64gb \
  -v /your/workspace:/workspace:z \
  REGISTRY_URL/monad:VERSION

Log Output Directory

The default file locations (including an aggregate full.log) come from the image's logging configuration; they are not necessarily inside your mounted workspace. When the container runs under an arbitrary or non-root UID — or the default location is read-only — file logging can fail with LoggingSetupError: Cannot create or write the log directory.

To use a different location, choose a directory on a writable mount and make sure the container user can write to it; see Setup. Set MONAD_LOGGING_DIRECTORY before importing the Python API or running a CLI command. For example, after preparing /your/workspace/logs on the host:

docker run -it \
  -e MONAD_LOGGING_DIRECTORY=/workspace/logs \
  --gpus all --shm-size 64gb \
  -v /your/workspace:/workspace:z \
  REGISTRY_URL/monad:VERSION

Leaving it unset (or blank) keeps the default filenames from the logging config. Setting the variable does not grant filesystem permissions.

For a running container that was created without this environment setting:

docker exec -w /workspace \
  -e MONAD_LOGGING_DIRECTORY=/workspace/logs \
  basemodel python -m monad.run --help

The setting on docker exec applies only to that process. To keep using the chosen directory, pass it to subsequent commands or configure it when creating the container. File logging can initialize before a command runs, including when displaying --help. If a command fails with LoggingSetupError, correct the log directory and its permissions before retrying.

Example Config

The config below keeps the default console output and adds two file handlers — one for general logs and one for errors only:

version: 1
formatters:
  default:
    format: "%(asctime)s - %(levelname)8s - %(name)s: %(message)s"
    datefmt: "%Y-%m-%d %H:%M:%S"

handlers:
  console:
    class: logging.StreamHandler
    level: INFO
    formatter: default
    stream: ext://sys.stdout
  mainFile:
    class: logging.FileHandler
    level: INFO
    formatter: default
    filename: logs/main.log
    mode: a
  errorFile:
    class: logging.FileHandler
    level: ERROR
    formatter: default
    filename: logs/error.log
    mode: a

loggers:
  monad:
    level: INFO
    handlers: [console, mainFile, errorFile]
    propagate: False

root:
  level: WARNING
  handlers: []

Key points:

• monad logger — captures all BaseModel output. Set its level to DEBUG for verbose diagnostics or WARNING to silence routine messages.
• root logger — catches everything else (third-party libraries). Keep at WARNING or higher to avoid noise.
• File handlers — mainFile records the full run log; errorFile isolates errors for quick scanning. Create the logs/ directory before training starts, or use absolute paths.