cfme.utils.log module

Logging framework

This module creates the cfme logger, for use throughout the project. This logger only captures log messages explicitly sent to it, not logs emitted by other components (such as selenium). To capture those, consider using the pytest-capturelog plugin.

Example Usage

from utils.log import logger

logger.debug('debug log message')'info log message')
logger.warning('warning log message')
logger.error('error log message')
logger.critical('critical log message')

The above will result in the following output in cfme_tests/logs/cfme.log:

1970-01-01 00:00:00,000 [D] debug log message (
1970-01-01 00:00:00,000 [I] info log message (
1970-01-01 00:00:00,000 [W] warning log message (
1970-01-01 00:00:00,000 [E] error log message (
1970-01-01 00:00:00,000 [C] fatal log message (

Additionally, if log_error_to_console is True (see below), the following will be written to stderr:

[E] error (
[C] fatal (

Log Message Source

We have added a custom log record attribute that can be used in log messages: %(source)s This attribute is included in the default ‘cfme’ logger configuration.

This attribute will be generated by default and include the filename and line number from where the log message was emitted. It will attempt to convert file paths to be relative to cfme_tests, but use the absolute file path if a relative path can’t be determined.

When writting generic logging facilities, it is sometimes helpful to override those source locations to make the resultant log message more useful. To do so, pass the extra source_file (str) and source_lineno (int) to the log emission:'info log message', extra={'source_file': '', 'source_lineno': 7})

If source_lineno is None and source_file is included, the line number will be omitted. This is useful in cases where the line number can’t be determined or isn’t necessary.


# in env.yaml
    level: INFO
    # Maximum logfile size, in bytes, before starting a new logfile
    # Set to 0 to disable log rotation
    max_logfile_size: 0
    # Maximimum backup copies to make of rotated log files (e.g. cfme.log.1, cfme.log.2, ...)
    # Set to 0 to keep no backups
    max_logfile_backups: 0
    # If True, messages of level ERROR and CRITICAL are also written to stderr
    errors_to_console: False
    # Default file format
    file_format: "%(asctime)-15s [%(levelname).1s] %(message)s (%(source)s)"
    # Default format to console if errors_to_console is True
    stream_format: "[%(levelname)s] %(message)s (%(source)s)"

Additionally, individual logger configurations can be overridden by defining nested configuration values using the logger name as the configuration key. Note that the name of the logger objects exposed by this module don’t obviously line up with their key in cfme_data. The ‘name’ attribute of loggers can be inspected to get this value:


Here’s an example of those names being used in env.local.yaml to configure loggers individually:

        # set the cfme log level to debug
        level: DEBUG
        # make the perflog a little more "to the point"
        file_format: "%(message)s"


  • The cfme and perf loggers are guaranteed to exist when using this module.

  • The name of a logger is used to generate its filename, and will usually not have the word “log” in it.

    • perflog’s logger name is perf for this reason, resulting in log/perf.log instead of log/perflog.log.

    • Similarly, logger’s’ name is cfme, to prevent having log/logger.log.


Creating a logger with the same name as one of the default configuration keys, e.g. create_logger('level') will cause a rift in space-time (or a ValueError).

Do not attempt.

Message Format

year-month-day hour:minute:second,millisecond [Level] message text (file:linenumber)


One letter in square brackets, where [I] corresponds to INFO, [D] corresponds to DEBUG, and so on.


The relative location from which this log message was emitted. Paths outside


class cfme.utils.log.ArtifactorHandler(level=0)[source]

Bases: logging.Handler

Logger handler that hands messages off to the artifactor

artifactor = None

Acquire a thread lock for serializing access to the underlying I/O.


Do whatever it takes to actually log the specified logging record.

This version is intended to be implemented by subclasses and so raises a NotImplementedError.

slaveid = None
class cfme.utils.log.NamedLoggerAdapter(logger, extra)[source]

Bases: cfme.utils.log.TraceLoggerAdapter

An adapter that injects a name into log messages

process(message, kwargs)[source]

Process the logging message and keyword arguments passed in to a logging call to insert contextual information. You can either manipulate the message itself, the keyword args or both. Return the message and kwargs modified (or not) to suit your needs.

Normally, you’ll only need to override this one method in a LoggerAdapter subclass for your specific needs.

class cfme.utils.log.Perflog(perflog_name='perf')[source]

Bases: object

Performance logger, useful for timing arbitrary events by name

Logged events will be written to log/perf.log by default, unless a different log file name is passed to the Perflog initializer.


from cfme.utils.log import perflog
# do stuff
seconds_taken = perflog.stop('event_name')
# seconds_taken is also written to perf.log for later analysis

Start tracking the named event

Will reset the start time if the event is already being tracked


Stop tracking the named event


A float value of the time passed since start was last called, in seconds, or None if start was never called.

tracking_events = {}
class cfme.utils.log.PrefixAddingLoggerFilter(prefix=None)[source]

Bases: logging.Filter


Determine if the specified record is to be logged.

Is the specified record to be logged? Returns 0 for no, nonzero for yes. If deemed appropriate, the record may be modified in-place.

class cfme.utils.log.TraceLogger(name, level=0)[source]

Bases: logging.Logger

A trace-loglevel-aware Logger

trace(msg, *args, **kwargs)[source]

Log ‘msg % args’ with severity ‘TRACE’.

class cfme.utils.log.TraceLoggerAdapter(logger, extra)[source]

Bases: logging.LoggerAdapter

A trace-loglevel-aware LoggerAdapter

trace(msg, *args, **kwargs)[source]

Delegate a trace call to the underlying logger, after adding contextual information from this adapter instance.

class cfme.utils.log.WarningsDeduplicationFilter[source]

Bases: object

this filter is needed since something in the codebase causes the warnings once filter to be reset, so we need to deduplicate on our own

there is no indicative codepath that is clearly at fault so this low implementation cost solution was choosen to deduplicate off-band

class cfme.utils.log.WarningsRelpathFilter(name='')[source]

Bases: logging.Filter

filter to modify warnings messages, to use relative paths in the project


Determine if the specified record is to be logged.

Is the specified record to be logged? Returns 0 for no, nonzero for yes. If deemed appropriate, the record may be modified in-place.


Look for a stdout handler in the logger, add one if not present

cfme.utils.log.format_marker(mstring, mark='-')[source]

Creates a marker in log files using a string and leader mark.

This function uses the constant MARKER_LEN to determine the length of the marker, and then centers the message string between padding made up of leader_mark characters.

  • mstring – The message string to be placed in the marker.

  • leader_mark – The marker character to use for leading and trailing.

Returns: The formatted marker string.

Note: If the message string is too long to fit one character of leader/trailer and

a space, then the message is returned as is.

class cfme.utils.log.logger_wrap(*args, **kwargs)[source]

Bases: object

Sets up the logger by default, used as a decorator in utils.appliance

If the logger doesn’t exist, sets up a sensible alternative

cfme.utils.log.make_file_handler(filename, root='/home/docs/checkouts/', level=None, **kw)[source]

Inspect the stack to determine the filename and lineno of the code running at the “n”th frame


n – Number of the stack frame to inspect

Raises IndexError if the stack doesn’t contain the nth frame (the caller should know this)

Returns a frameinfo namedtuple as described in inspect

cfme.utils.log.setup_for_worker(workername, loggers=('cfme', 'py.warnings', 'wrapanapi'))[source]
cfme.utils.log.setup_logger(logger, file_handler=None)[source]

Given a logger with ‘name’, set up that logger with proper levels based on logging conf

If logging conf is not specified for the ‘name’, then _default_conf defined in this file is used.


-- FileHandler to attach to this logger. (file_handler) – If None, a new one is created with name “<logger_name>.log”


tuple of (<logger>, <file handler attached to this logger>)