Skip to content
Docs

Documentation navigation

Logging

SDK logging hooks, file output, and diagnostics patterns.

#Logging

The public helpers use Python's standard logging module and return the process-wide logger named maivn.

#Import

Python 
from maivn import configure_logging, get_logger

#configure_logging()

Python 
from pathlib import Path
from maivn import configure_logging

logger = configure_logging(Path('logs/sdk.log'))
logger.info('Application initialized')

configure_logging(log_file_path=None) returns a logging.Logger. When a path is supplied, it creates missing parent directories and attaches a UTF-8 file handler at DEBUG level. The first configured file path wins; subsequent paths do not redirect the handler. Calling without a path does not prevent a later call from attaching the first file handler.

The file formatter is:

Plain text 
%(asctime)s %(levelname)s %(name)s %(message)s

File errors can propagate from Python's logging and filesystem APIs.

#get_logger()

get_logger(log_file_path=None) returns the same logger. It sets the logger's level to DEBUG and adds a NullHandler if no handlers exist. An optional first file path attaches a handler, but this helper does not create parent directories; use configure_logging(path) for that setup.

Python 
from maivn import get_logger

logger = get_logger()
logger.debug('Starting local preparation')

Without a file handler or application logging configuration, the helper does not add console output. Records can propagate to root handlers your application has configured.

#Console configuration

Configure standard logging in your application:

Python 
import logging
from maivn import get_logger

logging.basicConfig(
    level=logging.INFO,
    format='%(levelname)s %(name)s %(message)s',
)
logger = get_logger()
logger.setLevel(logging.INFO)
logger.info('Application ready')

The public helpers do not read MAIVN_LOG_LEVEL, MAIVN_LOG_FORMAT, or MAIVN_ENABLE_TIMING_LOGS. Setting those variables does not configure this logger. Use standard handlers, formatters, and levels instead.

For module-scoped application logging, use logging.getLogger(__name__). The SDK helper's string argument is a file path, not a logger name.

#Events and terminal output

Invocation progress is separate from Python logging. Use verbose=True or an event callback:

Python 
response = agent.events(on_event=handle_event).invoke('Check the order')

See Frontend Events for event handling and the Agent reference for plain/Rich terminal output. For metadata-only instrumentation, see Run Telemetry.

#Keep sensitive values out of logs

Log operation names and safe identifiers. Do not log API keys, private values, or full invocation payloads. Tool-result redaction does not scrub arbitrary application log records or external log collectors.

#See Also