31. Configuration File Shortcuts¶

This appendix describes features that AMPS provides for simplifying configuration

AMPS Configuration File Special Characters¶

In AMPS there are a few special characters that you should be aware of when creating your configuration file. These characters can provide some handy short cuts and make configuration creation easier, but you should also be aware of them so as not to introduce errors.

State of the World File Name¶

When specifying the file for a State of the World database, using the %n string in the file name specifies that the AMPS server will use the message type and topic name in that position to create a unique filename. Example 31.1 shows how to use this in the AMPS configuration file.

 <SOW>
    <Topic>
        <Topic>Customers</Topic>
        <FileName>./sow/%n.sow</FileName>
        <MessageType>json</MessageType>
        <Key>/customerId</Key>
    </Topic>
</SOW>

Example 31.1: SOW file name tokens used in configuration file

Log Rotation Name¶

When specifying an AMPS log file which has RotationThreshold specified, using the %n string in the log file name is a useful mechanism for ensuring the name of the log file is unique and sequential. Example 31.2 shows a file name token replacement in the AMPS configuration file.

<Logging>
    <Target>
        <Protocol>file</Protocol>
        <Level>info</Level>
        <FileName>log/log-%n.log</FileName>
        <RotationThreshold>2G</RotationThreshold>
    </Target>
</Logging>

Example 31.2: Log file name used in configuration file

In the above example, a log file will be created in the AMPSDIR/log/ directory. The first time this file is created, it will be named log-1.log. Once the log file reaches the RotationThreshold limit of 2G, the previous log file will be saved, and the new log file name will be incremented by one. Thus, the next log file will be named AMPSDIR/log/log-2.log.

Dates¶

AMPS allows administrators to use date-based file names when specifying the file name in the configuration, as demonstrated in Example 31.3.

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

Example 31.3: Date tokens used in configuration file

In the above example, a log file will be created in the $AMPSDIR/log named 2011-01-01-120000.log if the log was created at noon on January 1, 2011.

AMPS provides full support for the date tokens provided by the standard strftime function, with the exception of %n, as described above. The following table shows some of the most commonly used tokens:

Token	Provides	Example
%a	Short weekday name	Fri
%A	Full weekday name	Friday
%b	Short month name	Feb
%B	Full month name	February
%c	Simple date and time	Fri Feb 14 17:25:00 2014
%C	Century	20
%d	Day of the month (leading zero if necessary)	05
%D	Short date format (MM/DD/YY)	02/20/14
%e	Day of the month (leading space if necessary)	5
%F	Short date format (YYYY-MM-DD)	2014-02-20
%H	Hour (00-23)	17
%I	Hour (00-12)	05
%j	Day of the year (001-366)	051
%m	Month (01-12)	02
%p	AM or PM	PM
%r	Current time, 12 hour format	05:25:00 pm
%R	Current time, 24 hour format	17:25
%T	ISO 8601 Time format	17:25:00
%u	ISO 8601 day of the week (1-7, Monday = 1)	5
%V	ISO 8601 week number (00-53)	07
%y	Year, last two digits	14
%Y	Year, four digits	2014
%Z	Timezone name or abbreviation (blank if undetermined)	PST

Table 31.1: Commonly Used Date and Time Tokens

Using Units in the Configuration¶

To make configuration easy, AMPS permits the use of units to expand values. For example, if a time interval is measured in seconds, then the letter s can be appended to the value. For example, the following SOW topic definition used the Expiration tag to set the record expiration to 86400 seconds (one day).

<SOW>
    <Topic>
        ...

        <Expiration>86400s </Expiration>

        ...
    </Topic>
</SOW>

Example 31.4: Expiration using seconds

An even easier way to specify an expiration of one day is to use the following Expiration:

<SOW>
    <Topic>
        ...

        <Expiration>1d</Expiration>

        ...
    </Topic>
</SOW>

Example 31.5: Expiration using days

Table 31.2 shows a listing of the time units AMPS supports in the configuration file.

Units	Description
`ns`	nanoseconds
`us`	microseconds
`ms`	milliseconds
`s`	seconds
`m`	minutes
`h`	hours
`d`	days
`w`	weeks

Table 31.2: AMPS Configuration - Time Units

AMPS configuration supports a similar mechanism for byte-based units when specifying sizes in the configuration file. Table 31.3 shows a listing of the byte units AMPS supports in the configuration file.

Units	Description
`kb`	kilobytes
`mb`	megabytes
`gb`	gigabytes
`tb`	terabytes

Table 31.3: AMPS Configuration - Byte Units

Dealing with large numbers in AMPS configuration can also be simplified by using common exponent values to handle raw values. This means that instead of having to input 10000000 to represent ten million, a user can input 10M. Table 31.4 contains a list of the exponents supported.

Units	Description
k	10³ - thousand
M	10⁶ - million

Table 31.4: AMPS Configuration - Numeric Units

Tip

To make it easier for users to remember the units, AMPS interval and byte units are not case sensitive.

Environment Variables in AMPS Configuration¶

AMPS configuration also allows for environment variables to be used as part of the data when specifying a configuration file. These variables can be set in the environment when AMPS starts, or passed to AMPS using the -D option on the command line.

If a global system variable is commonly used in an organization, then it may be useful to define this in one location and re-use it across multiple AMPS installations or applications. AMPS will replace any token wrapped in ${} with the environment variable defined in the current user operating system environment. Example 31.6 demonstrates how the environment variable ENV_LOG is used to define a global environment variable for the location of the host logging.

<Logging>
    <Target>
        <Protocol>file</Protocol>
        <FileName>${ENV_LOG}</FileName>
        <Level>info</Level>
        <RotationThreshold>2G</RotationThreshold>
    </Target>
</Logging>

Example 31.6: Environment variables in AMPS configuration

Internal Environment Variables¶

In addition to supporting custom environment variables, AMPS includes a set of environment variables automatically populated by the server.

These variables are listed below:

Variable Name	Contains
`AMPS_CONFIG_DIRECTORY`	Directory in which the configuration file used to start AMPS is located.
`AMPS_CONFIG_PATH`	Full path to the configuration file used to start AMPS, including the file name.
`AMPS_VERSION`	Full version number of the AMPS server.

When AMPS processes the configuration file, AMPS expands these variables just as though they were set in the environment. For example, assume that AMPS was started with the following command at the command prompt:

%>./ampServer ../amps/config/config.xml

Given this command, the log file configuration option shown in Example 31.7 can be used to instruct AMPS to create the log files in the same parent directory as the configuration file — in this case ../amps/config/logs/infoLog.log.

<Logging>
    <Target>
        <Protocol>file</Protocol>
        <FileName>${AMPS_CONFIG_DIRECTORY}/logs/infoLog.log</FileName>
        <Level>info</Level>
        <RotationThreshold>2G</RotationThreshold>
    </Target>
</Logging>

Example 31.7: AMPS_CONFIG_DIRECTORY environment variable example

Table Of Contents

Related Topics