Logging

Jinx redirects all stdout and stderr to a log file. This includes logging from the Jinx addin and from user code. All logging from Java is done using the standard logging package java.util.logging.

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

[LOG]
path = directory of where to write the log file
file = filename of the log file
format = format string
level = logging level (severe, warning, info, config, fine, finer or finest)
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')

Jinx creates some configuration substitution variables that are useful when setting up logging.

Substitution Variable Description
pid process id
date current date
xl_version1 Excel version
jinx_version2 Jinx version

path

Path where the log file will be written to.

This may include substitution variables as listed above, e.g.

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

file

Filename of the log file.

This may include substitution variables as listed above, e.g.

[LOG]
file = jinx-log-%(pid)s-%(xlversion)s-%(date)s.log

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 - %(level)s - %(message)s"

The format string may include the following substitutions variables:

Format Variable Description
message Log record message
name Name of logger
asctime Log record time in YYYY-mm-dd:HH:MM:SS,millis format
filename Filename of the source file that generated the log record
lineno Line number where the log record was created
method Method name that created the log record
level Logging level
levelno Logging level as a number
process Process id of the process that created the log record
processName Name of process that created the log record
thread Thread id that created the log record

level

The log level can be used to filter out or show warning and errors. It sets the log level for the root java.util.logging.Logger, as well as setting Jinx’s internal log level.

It may be set to any of the following

  • severe
  • warning
  • info
  • config
  • fine
  • finer
  • finest

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

max_size3

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_interval3

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.

backup_count3

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.

encoding3

Encoding to use when writing the log file.

Defaults to utf-8.

Footnotes

  1. xlversion was renamed xl_version in Jinx 2.4.0, but both forms will continue to work. ↩

  2. jinx_version is new in Jinx 2.4.0. ↩

  3. max_size, roll_interval, backup_count and encoding options are new in Jinx 2.4.0. ↩ ↩2 ↩3 ↩4

© Copyright PyXLL Ltd.