PyXLL The Python Excel Add-In

Logging

PyXLL redirects all stdout and stderr to a log file. All logging is done using the standard logging python module.

The [LOG] section of the config file determines where logging information is redirected to, and the verbosity of the information logged.

The Configuration Variables are useful when configuring the log file as they allow including the current date, process id, and other variables in the log file name and/or path.

[LOG]
path = directory of where to write the log file
file = filename of the log file
verbosity = logging level (debug, info, warning, error or critical)
format = log format template
debug_format = optional format template (defaults to format)
info_format = optional format template (defaults to same as debug_format)
warning_format = optional format template (defaults to same as info_format)
error_format = optional format template (defaults to same as warning_format)
critical_format = optional format template (defaults to same as error_format)
max_size = maximum size the log file can get to before rolling to a new file.
roll_interval = period before the log file will be rolled and a new log will be started.
backup_count = number of old log files to keep.
encoding = encoding to use when writing the logfile (defaults to 'utf-8')
  • path

    Path where the log file will be written to.

    This may include substitution variables as in the section Configuration Variables, e.g.

    [LOG]
path = C:/Temp/pyxll-logs-%(date)s
  • file

    Filename of the log file.

    This may include substitution variables as in the section Configuration Variables, e.g.

    [LOG]
file = pyxll-log-%(pid)s-%(xlversion)s-%(date)s.log
  • verbosity

    The logging verbosity can be used to filter out or show warning and errors. It sets the log level for the root logger in the logging module, as well as setting PyXLL’s internal log level.

    It may be set to any of the following

    • debug (most verbose level, show all log messages including debugging messages)

    • info

    • warning

    • error

    • critical (least verbose level, only show the most critical errors)

    If you are having any problems with PyXLL it’s recommended to set the log verbosity to debug as that will give a lot more information about what PyXLL is doing.

  • format

    The format string is used by the logging module to format any log messages. An example format string is:

    [LOG]
format = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

    In addition to the standard LogRecord attrbitues provided by the logging module, the following may also be used:

    Attribute Name

    Format

    Description

    PyXLL Version

    address

    %(address)s

    Full address of the calling cell, if known.

    >= 5.10.0

    sheet

    %(sheet)s

    Sheet name of the calling cell, if known.

    >= 5.10.0

    cell

    %(sheet)s

    Cell reference of the calling cell, if known.

    >= 5.10.0

    For more information about log formatting, please see the logging module documentation from the Python standard library.

  • debug_format [3]

    Log format to use for log messages of level DEBUG.

    Defaults to the format option if not set (default).

  • info_format [3]

    Log format to use for log messages of level INFO.

    Defaults to the same as debug_format if not set (default).

  • warning_format [3]

    Log format to use for log messages of level WARNING.

    Defaults to the same as info_format if not set (default).

  • error_format [3]

    Log format to use for log messages of level ERROR.

    Defaults to the same as warning_format if not set (default).

  • critical_format [3]

    Log format to use for log messages of level CRITICAL.

    Defaults to the same as error_format if not set (default).

  • max_size [1]

    Maximum size the log file is allowed to grow to.

    Once the log file goes over this size it will be renamed to add a timestamp to the file and a new log file will be started.

    The size can be in Kb, Mb or Gb, for example to set it to 100Mb use max_size = 100Mb.

    If zero, the log file will be allowed to grow indefinitely.

  • roll_interval [1]

    If set the log file will be rolled periodically.

    This setting can be used alongside max_size and if both are set the log will be rolled either either the roll period is reached or the file size goes over the maximum allowed size.

    The interval can be any of:

    • a number of days, hours, minutes or seconds using the form Nd for days (eg 7d), Nm, and Ns respectively.

    • midnight to indicate the log should be rolled after midnight.

    • W0-6 to roll on a specific day of the week, eg W0 for Sunday and W6 for Saturday.

  • roll_backoff_interval [2]

    If rolling the log file fails a retry won’t be attempted for a short period of time. The default time between retries is 5 minutes.

    The interval can be number of days, hours, minutes or seconds using the form Nd for days (eg 7d), Nm, and Ns respectively.

  • backup_count [1]

    The number of backup log files to keep after rolling the log.

    If set, only the last N rolled log files will be kept.

    Instead of setting a fixed number a period can be specified, eg 7d to keep log files for 7 days.

  • encoding

    Encoding to use when writing the log file.

    Defaults to ‘utf-8’.

    New in PyXLL 4.2.0.

Footnotes

© Copyright PyXLL Ltd