Logging to a File

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.

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.

Examples

The following logging target definition would place a log file with a name constructed from the timestamp and current log rotation number in the ./logs subdirectory. The first log would have a name similar to ./logs/20121223125959-00000.log and would store up to 2GB before creating the next log file named ./logs/201212240232-00001.log.

<AMPSConfig>
    ...
    <Logging>
        <Target>
            <Protocol>file</Protocol>
            <Level>info</Level>
            <FileName>./logs/%Y%m%d%H%M%S-%n.log</FileName>
            <RotationThreshold>2G</RotationThreshold>
        </Target>
    </Logging>
    ...
</AMPSConfig>

This next example will create a single log named amps.log which will be appended to during each logging event. If amps.log contains data when AMPS starts, that data will be preserved and new log messages will be appended to the file.

<AMPSConfig>
    ...
    <Logging>
        <Target>
        <Protocol>file</Protocol>
        <Level>info</Level>
        <FileName>amps.log</FileName>
        </Target>
    </Logging>
    ...
</AMPSConfig>