Log Class

A Log is used to record information on disk. Carapace logs are designed to use with communications modules so that the data transferred or interesting comms events can be recorded.

Each Log has a maximum size so that the log does not become arbitrarily large and so fill up disk space. If the threshold is exceeded, the log clears itself and starts again.

Each record in the Log also has a standard header -- showing the date etc. This is so the log holds a history of the comms session.

Logs can be safely shared between threads since all access to the log is protected via a lock. This allows multiple concurrent threads to write to the log while ensuring the log records get interleaved properly rather than overwriting each other.

Log Severity

Information can be logged at the following severity settings - these simply mark the log records accordingly:

`info`	the informational severity is the lowest severity
`warn`	an intermediate severity - it results in a `!` mark against the log record within the log file
`error`	the highest severity - it results in a `*` against the log record within the log file

Log Levels

Information can be logged at various levels -- so that it is only recorded when the log is opened using the appropriate level. In this way, logged information can be made more verbose if problems are encountered, or less verbose when in a normal production environment. A log can have any, or none, of the following levels switched on:

`debug`	diagnostic information
`trace`	tracing information (eg. for logging the entering/exiting of functions)
`com`	information about COM usage
`db`	database information
`pdus`	log transferred data: PDU stands for Protocol Data Unit
`script`	log level most commonly used within Carapace scripts
`production`	logging required even in a production level

The production level is the only one intended to be switched on in a normal production environment. All other levels may generate large amounts of logged information and affect performance of the system.

The value all can be used to set all log levels in one go!

Log Configuration

Click here to read about log configuration.

Log Creation

The create function can be used to create a Log object eg.

    (create CommsStack "session.log")

This creates a log which will write to the file called session.log. The location of this file etc. is defined by the properties of the log.

Log Properties

A Log object supports the following properties:

property name	property type	description
`name`	String	(read-only) the name of the log file
`directory`	String	(read-only) the directory where the log file is kept
`path`	String	(read-only) the full path of the log file
`maxSize`	Integer	the threshold size after which a log file starts again
`levels`	List	the list of levels currently in place on the log

Log Methods

A Log object supports the following methods:

method name	description
`print`	print information to the log - at the `info` severity and the `script` level
`info`	print information to the log - at the `info` severity and the supplied level
`warn`	print information to the log - at the `warn` severity and the supplied level
`error`	print information to the log - at the `error` severity and the supplied level
`addLevel`	add the supplied log level to the log
`removeLevel`	remove the supplied log level from the log
`setLevels`	set all the log levels from the supplied string which contains a comma-separated list of valid log levels