Getting Started With AMPS Configuration

This section describes one typical process for developing an AMPS configuration file.

1. Add mandatory information

   An AMPS configuration starts with an AMPSConfig element at the outermost level of the configuration. Every AMPS instance must have a Name. This name identifies the instance, and must be unique within a set of instances.

   In this case, we can define the name test-AMPS-1 for the instance.

     <AMPSConfig>
        <Name>test-AMPS-1</Name>
     </AMPSConfig>

   With this configuration AMPS will start but will not allow any incoming connections to process messages. This instance also does not provide any monitoring or logging.

2. Describe how AMPS will receive connections from applications

   AMPS has no default settings for receiving commands from applications or for delivering messages to applications.

   To enable applications to connect to AMPS, specify a Transports element that defines one or more incoming Transport definitions. These are described in detail in the Transports section of this guide.

   For example, it's common to define one transport for application connections, and one transport for the use of web applications (JavaScript / TypeScript) and data queries or subscriptions from the Galvanometer admin tool.

   In this case we'll allow browser-based applications (such as Galvanometer) to connect to port 9008, and applications that use the other client libraries to connect to port 9007.

   After this step, the configuration might look something like this:

     <AMPSConfig>
       <Name>test-AMPS-1</Name>
   
       <Transports>
         <Transport>
             <Name>any-tcp</Name>
             <Type>tcp</Type>
             <InetAddr>9007</InetAddr>
             <MessageType>json</MessageType>
             <Protocol>amps</Protocol>
         </Transport>
   
         <Transport>
             <Name>any-websocket</Name>
             <Type>tcp</Type>
             <InetAddr>9008</InetAddr>
             <MessageType>json</MessageType>
             <Protocol>websocket</Protocol>
         </Transport>
       </Transports>
   
     </AMPSConfig>

3. Enable administrative monitoring.

   AMPS does not enable administrative monitoring by default. However, all instances of AMPS should enable this, as described in the Admin Server and Statistics section.

   For sample purposes, we will use port 8085 to host the administrative interface and Galvanometer. This configuration also tells Galvanometer to use the any-ws transport for the embedded JavaScript client.

     <AMPSConfig>
       <Name>test-AMPS-1</Name>
   
       <Transports>
         <Transport>
             <Name>any-tcp</Name>
             <Type>tcp</Type>
             <InetAddr>9007</InetAddr>
             <MessageType>json</MessageType>
             <Protocol>amps</Protocol>
         </Transport>
   
         <Transport>
             <Name>any-websocket</Name>
             <Type>tcp</Type>
             <InetAddr>9008</InetAddr>
             <MessageType>json</MessageType>
             <Protocol>websocket</Protocol>
         </Transport>
       </Transports>
   
       <Admin>
         <InetAddr>8085</InetAddr>
         <SQLTransport>any-ws</SQLTransport>
       </Admin> 
     </AMPSConfig>
   

4. Enable error and event logging

   Last, but not least, it's important to be notified of any errors or important events in AMPS. AMPS does not enforce any default for this logging, but instead requires this logging to be explicitly configured.

   For a production instance, AMPS would typically log messages to a file. For a quick sample, though, we can just log anything at warning level or above to stdout.

     <AMPSConfig>
       <Name>test-AMPS-1</Name>
   
       <Transports>
         <Transport>
             <Name>any-tcp</Name>
             <Type>tcp</Type>
             <InetAddr>9007</InetAddr>
             <MessageType>json</MessageType>
             <Protocol>amps</Protocol>
         </Transport>
   
         <Transport>
             <Name>any-websocket</Name>
             <Type>tcp</Type>
             <InetAddr>9008</InetAddr>
             <MessageType>json</MessageType>
             <Protocol>websocket</Protocol>
         </Transport>
       </Transports>
   
       <Admin>
         <InetAddr>8085</InetAddr>
         <SQLTransport>any-ws</SQLTransport>
       </Admin> 
   
       <Logging>
         <Target>
           <Protocol>stdout</Protocol>
           <Level>warning</Level>
         </Target>
       </Logging>
   
     </AMPSConfig>

5. Define advanced messaging behavior

   The configuration in the four sections above is all you need for basic subscribe and publish functionality.

   For more advanced functionality, you configure AMPS to provide that functionality. For example, to configure a last-value-cache for a topic, you would define a Topic in the State of the World. To enable full, message-by-message replay for a topic or set of topics, you would define a Transaction Log.

All instances of AMPS, regardless of the application they support, should follow this minimum outline: define the instance Name, the instance Transports, define monitoring through the Admin console, and specify the Logging for the instance.

Most applications also take advantage of the advanced messaging capabilities of AMPS, as described in detail in the AMPS User Guide. The Scenario and Feature Reference of the Introduction to AMPS can help to suggest starting points for different scenarios.