Logging to Files

To log to a file, declare a logging target with a protocol value of file. Beyond the standard Level, Levels, IncludeErrors, and ExcludeErrors settings available on every logging target, file targets also permit the selection of a FileName mask and RotationThreshold.

Compressed Files

AMPS supports logging to compressed files as well. This is useful when trying to maintain a smaller logging footprint. Compressed file logging targets are the same as regular file targets except for the following:

• The Protocol value is gzip instead of file.

• The log file is written with gzip compression.

• The RotationThreshold is metered off of the uncompressed log messages.

• Makes a trade off between a small increase in CPU utilization for a potentially large savings in logging footprint.

Selecting a Filename

The FileName attribute is a mask which is used to construct a directory and file name location for the log file. AMPS will resolve the file name mask using the symbols in the table below. For example, if a file name is masked as:

%Y-%m-%dT%H:%M:%S.log

AMPS would create a log file in the current working directory with a timestamp of the form: 2012-02-23T12:59:59.log.

If a RotationThreshold is specified in the configuration of the same log file, the next log file created will be named based on the current system time, not on the time that the previous log file was generated. Using the previous log file as an example, if the first rotation was to occur 10 minutes after the creation of the log file, then that file would be named 2012-02-23T13:09:59.log.

Log files which need a monotonically increasing counter when log rotation is enabled can use the %n mask to provide this functionality. If a file is masked as:

localhost-amps-%n.log

Then the first instance of that file would be created in the current working directory with a name of localhost-amps-00000.log. After the first log rotation, a log file would be created in the same directory named localhost-amps-00001.log.

Log file rotation is discussed in greater detail in the Log File Rotation section.

Mask	Definition
%Y	Year
%m	Month
%d	Day
%H	Hour
%M	Minute
%S	Second
%n	Iterator which starts at 00000 when AMPS is first started and increments each time a RotationThreshold size is reached on the log file.

Log File Rotation

Log files can be “rotated” by specifying a valid threshold in the RotationThreshold attribute. Values for this attribute have units of bytes unless another unit is specified as a suffix to the number. The valid unit suffixes are:

Unit Suffix	Base Unit	Examples
no suffix	bytes	“1000000” is 1 million bytes
k or K	thousands of bytes	“50k” is 50 thousand bytes
m or M	millions of bytes	“10M” is 10 million bytes
g or G	billions of bytes	“2G” is 2 billion bytes
t or T	trillions of bytes	“0.5T” is 500 billion bytes

When using log rotation, if the next filename is the same as an existing file, the file will be truncated before logging continues. For example, if amps.log is used as the FileName mask and a RotationThreshold is specified, then the second rotation of the file will overwrite the first rotation.

If it is desirable to keep all logging history, then it is recommended that either a timestamp or the %n rotation count be used within the FileName mask when enabling log rotation.