# evennia.utils.logger

Logging facilities

These are thin wrappers on top of Twisted’s logging facilities; logs are all directed either to stdout (if Evennia is running in interactive mode) or to $GAME_DIR/server/logs.

The log_file() function uses its own threading system to log to arbitrary files in $GAME_DIR/server/logs.

Note: All logging functions have two aliases, log_type() and log_typemsg(). This is for historical, back-compatible reasons.

`evennia.utils.logger.``log_info`(msg, **kwargs)

  Logs any generic debugging/informative info that should appear in the log.

  Parameters

    - msg – (string) The message to be logged.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``info`(msg, **kwargs)

  Logs any generic debugging/informative info that should appear in the log.

  Parameters

    - msg – (string) The message to be logged.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``log_infomsg`(msg, **kwargs)

  Logs any generic debugging/informative info that should appear in the log.

  Parameters

    - msg – (string) The message to be logged.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``log_msg`(msg, **kwargs)

  Logs any generic debugging/informative info that should appear in the log.

  Parameters

    - msg – (string) The message to be logged.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``log_warn`(msg, **kwargs)

  Logs warnings that aren’t critical but should be noted.

  Parameters

    - msg (str) – The message to be logged.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``warn`(msg, **kwargs)

  Logs warnings that aren’t critical but should be noted.

  Parameters

    - msg (str) – The message to be logged.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``warning`(msg, **kwargs)

  Logs warnings that aren’t critical but should be noted.

  Parameters

    - msg (str) – The message to be logged.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``log_warnmsg`(msg, **kwargs)

  Logs warnings that aren’t critical but should be noted.

  Parameters

    - msg (str) – The message to be logged.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``log_err`(msg, **kwargs)

  Logs an error message to the server log.

  Parameters

    - msg (str) – The message to be logged.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``error`(msg, **kwargs)

  Logs an error message to the server log.

  Parameters

    - msg (str) – The message to be logged.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``err`(msg, **kwargs)

  Logs an error message to the server log.

  Parameters

    - msg (str) – The message to be logged.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``log_errmsg`(msg, **kwargs)

  Logs an error message to the server log.

  Parameters

    - msg (str) – The message to be logged.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``log_trace`(msg=None, **kwargs)

  Log a traceback to the log. This should be called from within an exception.

  Parameters

    - msg (str, optional) – Adds an extra line with added info at the end of the traceback in the log.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``log_tracemsg`(msg=None, **kwargs)

  Log a traceback to the log. This should be called from within an exception.

  Parameters

    - msg (str, optional) – Adds an extra line with added info at the end of the traceback in the log.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``exception`(msg=None, **kwargs)

  Log a traceback to the log. This should be called from within an exception.

  Parameters

    - msg (str, optional) – Adds an extra line with added info at the end of the traceback in the log.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``critical`(msg=None, **kwargs)

  Log a traceback to the log. This should be called from within an exception.

  Parameters

    - msg (str, optional) – Adds an extra line with added info at the end of the traceback in the log.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``trace`(msg=None, **kwargs)

  Log a traceback to the log. This should be called from within an exception.

  Parameters

    - msg (str, optional) – Adds an extra line with added info at the end of the traceback in the log.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``log_dep`(msg, **kwargs)

  Prints a deprecation message.

  Parameters

    - msg (str) – The deprecation message to log.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``dep`(msg, **kwargs)

  Prints a deprecation message.

  Parameters

    - msg (str) – The deprecation message to log.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``deprecated`(msg, **kwargs)

  Prints a deprecation message.

  Parameters

    - msg (str) – The deprecation message to log.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``log_depmsg`(msg, **kwargs)

  Prints a deprecation message.

  Parameters

    - msg (str) – The deprecation message to log.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``log_sec`(msg, **kwargs)

  Prints a security-related message.

  Parameters

    - msg (str) – The security message to log.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``sec`(msg, **kwargs)

  Prints a security-related message.

  Parameters

    - msg (str) – The security message to log.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``security`(msg, **kwargs)

  Prints a security-related message.

  Parameters

    - msg (str) – The security message to log.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``log_secmsg`(msg, **kwargs)

  Prints a security-related message.

  Parameters

    - msg (str) – The security message to log.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

`evennia.utils.logger.``log_server`(msg, **kwargs)

  This is for the Portal to log captured Server stdout messages (it’s usually only used during startup, before Server log is open)

  Parameters

    - msg (str) – The message to be logged.

    - **kwargs – If given, The msg is parsed as a format string with {..} formatting markers that should match the keywords.

class `evennia.utils.logger.``GetLogObserver`

  Bases: `object`

  Sets up how the system logs are formatted.

  `component_prefix` = ''
  `event_levels` = {<LogLevel=debug>: '??', <LogLevel=info>: '..', <LogLevel=warn>: 'WW', <LogLevel=error>: 'EE', <LogLevel=critical>: '!!'}
  `format_log_event`(event)

    By assigning log_system here, we skip the spammy display of namespace/level in the default log output.

    [component_prefix] [date] [system/lvl] [msg]

class `evennia.utils.logger.``GetPortalLogObserver`

  Bases: `evennia.utils.logger.GetLogObserver`

  `component_prefix` = '|Portal| '

class `evennia.utils.logger.``GetServerLogObserver`

  Bases: `evennia.utils.logger.GetLogObserver`

  `component_prefix` = ''

`evennia.utils.logger.``timeformat`(when=None)

  This helper function will format the current time in the same way as the twisted logger does, including time zone info. Only difference from official logger is that we only use two digits for the year and don’t show timezone for GMT times.

  Parameters

    when (int, optional) – This is a time in POSIX seconds on the form given by time.time(). If not given, this function will use the current time.

  Returns

    timestring (str) – A formatted string of the given time.

class `evennia.utils.logger.``WeeklyLogFile`(name, directory, defaultMode=None, day_rotation=7, max_size=1000000)

  Bases: `twisted.python.logfile.DailyLogFile`

  Log file that rotates once per week by default. Overrides key methods to change format.

  `__init__`(name, directory, defaultMode=None, day_rotation=7, max_size=1000000)
    Parameters

      - name (str) – Name of log file.

      - directory (str) – Directory holding the file.

      - defaultMode (str) – Permissions used to create file. Defaults to current permissions of this file if it exists.

      - day_rotation (int) – How often to rotate the file.

      - max_size (int) – Max size of log file before rotation (regardless of time). Defaults to 1M.

  `shouldRotate`()

    Rotate when the date has changed since last write

  `suffix`(tupledate)

    Return the suffix given a (year, month, day) tuple or unixtime. Format changed to have 03 for march instead of 3 etc (retaining unix file order)

    If we get duplicate suffixes in location (due to hitting size limit), we append __1, __2 etc.

    Examples

    server.log.2020_01_29 server.log.2020_01_29__1 server.log.2020_01_29__2

  `rotate`()

    Rotate the file and create a new one.

    If it’s not possible to open new logfile, this will fail silently, and continue logging to old logfile.

  `write`(data)

    Write data to log file

class `evennia.utils.logger.``EvenniaLogFile`(name, directory, rotateLength=1000000, defaultMode=None, maxRotatedFiles=None)

  Bases: `twisted.python.logfile.LogFile`

  A rotating logfile based off Twisted’s LogFile. It overrides the LogFile’s rotate method in order to append some of the last lines of the previous log to the start of the new log, in order to preserve a continuous chat history for channel log files.

  `settings` = <LazySettings "evennia.settings_default">
  `num_lines_to_append` = 20
  `rotate`(num_lines_to_append=None)

    Rotates our log file and appends some number of lines from the previous log to the start of the new one.

  `seek`(*args, **kwargs)

    Convenience method for accessing our _file attribute’s seek method, which is used in tail_log_function.

    Parameters

      - *args – Same args as file.seek

      - **kwargs – Same kwargs as file.seek

  `readlines`(*args, **kwargs)

    Convenience method for accessing our _file attribute’s readlines method, which is used in tail_log_function.

    Parameters

      - *args – same args as file.readlines

      - **kwargs – same kwargs as file.readlines

    Returns

      lines (list) – lines from our _file attribute.

`evennia.utils.logger.``log_file`(msg, filename='game.log')

  Arbitrary file logger using threads.

  Parameters

    - msg (str) – String to append to logfile.

    - filename (str, optional) – Defaults to ‘game.log’. All logs will appear in the logs directory and log entries will start on new lines following datetime info.

`evennia.utils.logger.``log_file_exists`(filename='game.log')

  Determine if a log-file already exists.

  Parameters

    filename (str) – The filename (within the log-dir).

  Returns

    bool – If the log file exists or not.

`evennia.utils.logger.``rotate_log_file`(filename='game.log', num_lines_to_append=None)

  Force-rotate a log-file, without

  Parameters

    - filename (str) – The log file, located in settings.LOG_DIR.

    - num_lines_to_append (int, optional) – Include N number of lines from previous file in new one. If None, use default. Set to 0 to include no lines.

`evennia.utils.logger.``tail_log_file`(filename, offset, nlines, callback=None)

  Return the tail of the log file.

  Parameters

    - filename (str) – The name of the log file, presumed to be in the Evennia log dir.

    - offset (int) – The line offset from the end of the file to start reading from. 0 means to start at the latest entry.

    - nlines (int) – How many lines to return, counting backwards from the offset. If file is shorter, will get all lines.

    - callback (callable, optional) – A function to manage the result of the asynchronous file access. This will get a list of lines. If unset, the tail will happen synchronously.

  Returns

    lines (deferred or list) –

    This will be a deferred if callable is given,

      otherwise it will be a list with The nline entries from the end of the file, or all if the file is shorter than nlines.