Configuring Logging

To enable logging, add a Logging section to the configuration and specify a Target with a Protocol value, along with any other relevant options. You can configure multiple targets by including multiple Target definitions within the Logging tag.

For details on logging, including a cross reference to the types of messages and a breakdown of the format AMPS uses in log messages, see the other subsections of Logging.

Described below are the configuration elements that apply to all logging protocols. Expand each item for more details.

Protocol (required)

Defines the logging target protocol.

Valid values: stdout, stderr, file, gzip, syslog

Level

Defines a lower bound (inclusive) log level for logging. All log messages at the specified level and up are logged.

A production server should be configured to log at info level or more verbose.

Valid values: developer, trace, stats, info, warning, error, critical, emergency, none

There is no default for this option.

Levels

A comma separated list of specific log levels. Only log messages at the specified levels will be logged.

This element can be used with the Level element. In that case, AMPS will log all messages at Level and above, and in addition, will log errors at the levels specified by Levels.

Valid values: developer, trace, stats, info, warning, error, critical, emergency, none

There is no default for this option.

IncludeErrors

Additional errors that should be included when logging. If an error appears in this element, it will be logged regardless of the level of the error.

This element accepts a comma-delimited list of error numbers. You can also provide a regular expression that matches a set of errors, such as 12-.*

There is no default for this option.

ExcludeErrors

Errors that should be excluded when logging. If an error appears in this element, it will not be logged regardless of the level of the error.

If the same error appears in both IncludeErrors and ExcludeErrors, ExcludeErrors takes precedence, and the error will not be logged.

This element accepts a comma-delimited list of error numbers. You can also provide a regular expression that matches a set of errors, such as 12-.*

There is no default for this option.

info

AMPS logging is always opt-in. That is, no messages are logged to a target by default. Logging must be explicitly requested using the configuration elements above.

Logging to Files

Described below are the configuration items available for logging to a standard or compressed file. Expand each item for more details.

FileName(required)

The file to log to.

If the Protocol is file, then .log is added to the file name.

If the Protocol is gzip, then .gz is added to the file name.

Required for file and gzip protocols.

Default: ${PWD}/%Y-%m-%dT%H%M%S.log

RotationThreshold

Log size at which log rotation will occur.

See the information on Byte Units for details on specifying file size.

Standard File 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 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>

Compressed File Example

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-0.log.gz and would store up to 2GB of uncompressed log messages before creating the next log file named ./logs/201212240232-1.log.gz.

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

Logging to Syslog

Described below are the configuration items available for logging to syslog. Expand each item for more details.

Ident

The syslog identifier for the AMPS instance.

Default: AMPS Instance Name

Options

A comma separated list of syslog options.

If using syslog, 60East recommends using LOG_CONS, LOG_NDELAY, and LOG_PID.

AMPS uses the standard options to syslog, as described in the syslog man page.

Facility

The syslog facility to use.

Below is an example of a syslog logging target that logs all messages at the critical severity level or higher, as well as log messages matching 30-0000 to the syslog.

<AMPSConfig>
    ...
    <Logging>
        <Target>
            <Protocol>syslog</Protocol>
            <Level>critical</Level>
            <IncludeErrors>30-0000</IncludeErrors>
            <Ident>\amps dma</Ident>
            <Options>LOG_CONS,LOG_NDELAY,LOG_PID</Options>
            <Facility>LOG_USER</Facility>
        </Target>
    </Logging>
    ...
</AMPSConfig>

Below is an example that shows how to record messages to both syslog and file logging targets.

<Logging>
    <!-- Record trace messages to files in /var/tmp/. -->
    <Target>
        <Protocol>file</Protocol>
        <FileName>/var/tmp/amps/logs/%Y%m%d%H%M%S-%n.log</FileName>
        <RotationThreshold>2G</RotationThreshold>
        <Level>trace</Level>
        <Levels>critical</Levels>
    </Target>
  
    <!-- Record critical messages to the system logger. -->
    <Target>
        <Protocol>syslog</Protocol>
        <Level>critical</Level>
        <Ident>amps_dma</Ident>
        <Options>LOG_CONS,LOG_NDELAY,LOG_PID</Options>
        <Facility>LOG_USER</Facility>
    </Target>
  
    <!-- Record only the AMPS initialization message. -->
    <Target>
        <Protocol>file</Protocol>
        <FileName>/var/tmp/amps/logs/initMessage</FileName>
        <IncludeErrors>00-0015</IncludeErrors>
    </Target>
</Logging>

Logging to the Console

The console logging target instructs AMPS to log certain messages to the console. Both the standard output and standard error streams are supported.

Use a Protocol setting of stdout to select standard output, or stderr for standard error.

Below is an example of a console logger that logs all messages at the info or warning level to standard out and all messages at the error level or higher to standard error (which includes error, critical and emergency levels).

<AMPSConfig>
    ...
    <Logging>
        <Target>
            <Protocol>stdout</Protocol>
            <Levels>info,warning</Levels>
        </Target>
        <Target>
            <Protocol>stderr</Protocol>
            <Level>error</Level>
        </Target>
    </Logging>
    ...
</AMPSConfig>

Example: Development Instance Logging

This logging configuration may be useful for development instances.

This configuration is intended to meet the following considerations:

Warning, error, and critical messages are logged to standard output to make it easy for a developer to see if a command to AMPS produces an error.
Message traffic in and out of AMPS is logged to the trace.log file for debugging purposes. This file is rotated every 250MB. When the file hits the 250MB limit, it will be cleared and overwritten with new entries.
Static information about the instance -- including the configuration, detected hardware configuration, and so forth -- is logged to the instance-info.log. Logging this information to a separate file means it will still be available when the trace log is replaced.

<AMPSConfig>
  ...
  <Logging>
    <Target>
       <Protocol>file</Protocol>
       <Level>trace</Level>
       <FileName>./logs/trace.log</FileName>
       <RotationThreshold>250MB</RotationThreshold>
    </Target>
    <Target>
       <Protocol>stdout</Protocol>
       <Level>warning</Level>
       <IncludeErrors>00-0015</IncludeErrors>
   </Target>
   <Target>
       <Protocol>file</Protocol>
       <FileName>./logs/instance-info.log</FileName>
       <IncludeErrors>00-0001,00-0002,00-0004,00-0015,
                      00-0030,00-0033,00-0032,00-0054,
                      01-0019,2D-0005,2D-0006,2D-0008,2D-0011</IncludeErrors>
    </Target>
  </Logging>
  ...
</AMPSConfig> 

Logging to Files​

Standard File Examples​

Compressed File Example​

Logging to Syslog​

Logging to the Console​

Example: Development Instance Logging​

Logging to Files

Standard File Examples

Compressed File Example

Logging to Syslog

Logging to the Console

Example: Development Instance Logging