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 = format string
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 listed above, e.g.

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

• file

  Filename of the log file.

  This may include substitution variables as listed above, 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"
  

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

• 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