Log channel sending logs to a set of (possibly) rotating local files.
Class LogChannelFiles( path, [level],[format],[maxCount],[maxSize],[maxDays],[overwrite],[flushAll] )
| path | The complete filename were the logs are to be sent. |
| level | Minimum severity level logged by this channel. |
| format | Message formatting used by this channel. |
| maxCount | Number of maximum log files generated by this channel. |
| maxSize | Maximum size of each file. |
| maxDays | Maximum days of lifetime for each file. |
| overwrite | If true, overwrite the base log file on open, if found. |
| flushAll | If false, do NOT flush at every log entry. |
This log channel is meant to write to one local file, and to possibly swap it into spare files when some criterion are met.
In its basic default configuration, this stream channel works as a LogChannelStream provided with a stream open on a local file via InputOutput stream (appending at bottom, or eventually creating the file).
If the maxSize parameter is given, the file is rotated (closed and renamed) when it grows beyond the given dimension (in bytes).
If the maxDays parameter is given, the file is rotated after a maximum number of days since its creation.
If both maxSize and maxDays parameters are given, the file is rotated when the first boundary is met.
The action performed when rotating a file is determined by the maxCount parameter. If it's zero (the default), the log file is simply truncated to 0, that is to say, the writing starts anew. Any other value indicates the maximum number of back-rotated files created by this channel. Files are rotated by adding a numeric suffix to them; the currently active log file is unnumbered, the most recent log file is renumbered as 1, the second last most recent is numbered 2 up to the value of maxCount parameter. When all the positions are occupied and a new rotation takes place, the oldest file is deleted.
The rotated file names are composed of the path parameter and a zero padded number wide enough to accommodate all the numbers up to maxCount; the number is generally appended to the path through a "." separator, but it is possible to override this by passing a path containing a "%" (percent) character, which gets substituted by the padded number. In this case, the main file is numbered 0.
For example, files generated through the path "logs/my_app.%.log" with a maxCount of 10 will be numbered as (oldest to newest): @code logs/my_app.10.log logs/my_app.09.log logs/my_app.08.log ... logs/my_app.01.log logs/my_app.00.log @endcode
while files created through the path "logs/my_app.log" would be numbered:
logs/my_app.log.10 logs/my_app.log.09 logs/my_app.log.08 ... logs/my_app.log.01 logs/my_app.log
If the overwrite parameter is true, then the the main file will be overwritten in case it exists when opening the log.
Finally, if the flushAll parameter is false, then the stream buffer won't be flushed after each log operation.
This log channel doesn't try to create immediately the main file; this is done the first time a log request is processed, or explicitly through the LogChannelFiles.open method. In the first case, a log request advanced by a log area may raise an IoError when
Note: All the parameters can be hot-changed in any moment, except for the path parameter that is read-only.
| Properties | |
| flushAll | When true, all the log operations cause an immediate flush of the underlying stream. |
| maxCount | Maximum number of rolled back log files before starting deleting them. |
| maxDays | Number of days to keep logging on the master file before rolling it. |
| maxSize | Maximum size of the main log file before being automatically rolled. |
| overwrite | If true, opening a non-empty log will delete it. |
| path | Contains the path to the master log file. |
| Methods | |
| open | Opens the stream to the given main log file. |
| reset | Clears the current log file. |
| rotate | Rotates the current log file. |
When true, all the log operations cause an immediate flush of the underlying stream.
Maximum number of rolled back log files before starting deleting them.
Zero means that the file is never rolled back; eventually, when hitting a limit, it is truncated from the beginning and the log starts all over.
Number of days to keep logging on the master file before rolling it.
Zero means disabled.
Maximum size of the main log file before being automatically rolled.
Zero means disabled; that is, the size of the log file is unlimited.
If true, opening a non-empty log will delete it.
The default for this property is false. This means that the default behavior is that to append log entries to the previously existing ones.
Contains the path to the master log file.
This property is read-only.
Opens the stream to the given main log file.
LogChannelFiles.open()
| Raise |
|
Clears the current log file.
LogChannelFiles.reset()
| Raise |
|
This operation clears the log file without rotating it. Some applications, in certain moments, know that the previous log is useless and to be discarded, for example because they want to debug the operations from that point on.
This method also forces do discard all the pending messages that was queued for logging but still unwritten.
Rotates the current log file.
LogChannelFiles.rotate()
This operation perform a rotation operation, respecting the default behavior specified through the LogChannelFiles.maxCount property, as if one of the limits were hit.
The operation is actually queued after all pending messages; new messages posted after this operation will go to the new main file after the rotation, while the pending messages will be written to the new log stream.
Note: A failure in the rotate operation will cause the operation to silently fail and the log to keep being sent to the current log file.