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 Config 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')
redirect_stdout = 1 or 0 to enable or disable redirection of native (C) stdout to log file.
redirect_stderr = 1 or 0 to enable or disable redirection of native (C) stderr to log file.

• path

  Path where the log file will be written to.

  This may include substitution variables as in the section Config 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 Config 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	%(cell)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.

• redirect_stdout

  Enables or disabled redirecting the native (C runtime) stdout to the PyXLL log file.

  Some Python extensions, and the Python interpreter itself, sometimes log to the native C stdout instead of to the redirected Python stdout or to a log file.

  When this option is set the native stdout is redirected to the PyXLL log file.

  Defaults to 1.

  New in PyXLL 5.11.0.

• redirect_stderr

  Enables or disabled redirecting the native (C runtime) stderr to the PyXLL log file.

  Some Python extensions, and the Python interpreter itself, sometimes log to the native C stderr instead of to the redirected Python stderr or to a log file.

  When this option is set the native stderr is redirected to the PyXLL log file.

  Defaults to 1.

  New in PyXLL 5.11.0.

Footnotes