2. Getting Started¶

This chapter is for users who are new to AMPS and want to get up and running on a simple instance of AMPS. This chapter will walk new users through the file structure of an AMPS installation, configuring a simple AMPS instance and running the demonstration tools provided as part of the distribution to show how a simple publisher can send messages to AMPS.

Installing AMPS¶

To install AMPS, unpack the distribution for your platform where you want the binaries and libraries to be stored. For the remainder of this guide, the installation directory will be referred to as $AMPSDIR as if an environment variable with that name was set to the correct path.

Within $AMPSDIR the following sub-directories listed in Table 2.1.

Directory	Description
bin	AMPS engine binaries and utilities
docs	Documentation
lib	Library dependencies
sdk	Include files for the AMPS extension API

Table 2.1: AMPS Distribution Directories

Tip

AMPS client libraries are available as a separate download from the AMPS web site. See the AMPS developer page at http://www.crankuptheamps.com/developer to download the latest libraries.

Starting AMPS¶

The AMPS Engine binary is named ampServer and is found in $AMPSDIR/bin. Start the AMPS engine with a single command line argument that includes a valid path to an AMPS configuration file. You use the configuration file to enable and configure the AMPS features that your application will use. This guide discusses the most commonly-used configuration options for each feature, and the full set of options is described in the AMPS Configuration Reference.

The AMPS server can generate a minimal sample configuration file with the --sample-config option. For example, you can save the sample configuration file to $AMPSDIR/amps_config.xml with the following command line:

$AMPSDIR/bin/ampServer --sample-config > $AMPSDIR/amps_config.xml

Tip

The sample configuration file generated by the server shows a minimal AMPS configuration. The client language distributions include an AMPS configuration file designed to work with the examples included with that client.

The server sample configuration only provides configuration for subscribe/publish use of AMPS, and does not include any persistence for AMPS messages.

The file enables the instance administrative interface (the “Galvanometer”), including the ability to subscribe to topics using a websocket connection from the instance administrative interface.

A production configuration would likely provide persistent event and error logging to a file to allow an operations team to troubleshoot the instance. A production configuration would typically persist monitoring statistics to a file. Such a configuraiton would likely enable additional message delivery features for certain topics, and would also include configuration for high-availability and disaster recovery. The configuration would typically configure AMPS actions to perform routine maintenance.

Once you have a configuration file saved to $AMPSDIR/amps_config.xml you can start AMPS with that file as follows:

$AMPSDIR/bin/ampServer $AMPSDIR/amps_config.xml

The sample configuration file generated by AMPS includes a very minimal configuration. The client language distributions include a sample configuration file that sets up AMPS to work with the samples provided with that client, and the AMPS Configuration Reference contains a full description of the configuration items with sample configuration snippets.

Tip

AMPS uses the current working directory for storing files (logs and persistence) for any relative paths specified in the configuration. While this is important for real deployments, the demo configuration used in this chapter does not persist anything, so you can safely start AMPS from any working directory using this configuration.

Tip

On older processor architectures, ampServer will start the ampServer-compat binary. The ampServer-compat binary avoids using hardware instructions that are not available on these systems.

You can also set the AMPS_PLATFORM_COMPAT environment variable to force ampServer to start the ampServer-compat binary. 60East recommends using this option only on systems that do not support the hardware instructions used in the standard binary. The ampServer-compat binary will not perform as well as ampServer, since it uses fewer hardware optimizations.

If your first start-up is successful, you should see AMPS display a simple message similar to the following to let you know that your instance has started correctly.

AMPS A.B.C.D.973814.e1a57f7 - Copyright (c) 2006-202X 60East Technologies Inc.
(Built: XXXX-YY-ZZT00:26:45Z)
For all support questions: support@crankuptheamps.com

The version numbers and dates will be appropriate for the version that you’ve started.

If you see this, congratulations! You have successfully cranked up the AMPS!

Command Line Options¶

The AMPS server binary supports the following command line options:

Option	Effect
`--verify-config`	Parse and verify the specified configuration file, then exit.
`--sample-config`	Produce a minimal AMPS config.xml file to standard output, then exit.
`--dump-config`	Process the specified configuration file, resolving any Include directives and expanding environment variables. Dump the resulting file to standard output.
`--version`	Print the AMPS version string, then exit.
`--help`	Print usage information for the commandline options accepted by the ampServer program, then exit.
`--daemon`	Run AMPS as a daemon process.
`-D<variable>=<value>`	Set the specified environment variable to the specified value when running the AMPS process. AMPS accepts any number of `-D` options. For example, to set the variable `AMPS_PATH` to `/mnt/fast/AMPS` use the command line option `-DAMPS_PATH=/mnt/fast/AMPS`

Table 2.2: ampServer command line options

Admin View of the AMPS Server¶

When the admin server is enabled in the configuration, you can get an indication as to whether AMPS is running or not by connecting to its admin port with a browser at http://<host>:<port>/amps where <host> is the host the AMPS instance is running on and <port> is the administration port configured in the configuration file.

When successful, a hierarchy of information regarding the instance will be displayed. If you’ve started AMPS using the sample configuration file, try connecting to http://localhost:8085/amps. For more information on the monitoring capabilities, please see the AMPS Monitoring Reference Guide, available from the 60East documentation site at http://docs.crankuptheamps.com/.

Interacting with AMPS Using Spark¶

AMPS provides the spark utility as a command line interface to interacting with an AMPS server. spark provides many of the capabilities of the AMPS client libraries through this interface. The utility lets you execute commands like 'subscribe', 'publish', 'sow', 'sow_and_subscribe' and 'sow_delete', described elsewhere in this Guide.

spark is a Java application, and requires a JRE version 1.7 or later to run.

Applications that use AMPS use one of the client libraries, available from http://www.crankuptheamps.com/develop. The spark utility supports a subset of AMPS functionality, and is most often used for troubleshooting, ad hoc testing, or light scripting.

For example, to simply test connectivity to an AMPS server, spark provides a ping command. This command simply makes a connection to the server using the specified parameters, and reports whether that connection succeeded or failed. You can run the command as follows, where the server parameter is the address and port of the AMPS server, and the type parameter is the message type to use for this connection:

$ ./spark ping -server localhost:9007 -type json
Successfully connected to tcp://user@localhost:9007/amps/json

If spark encounters an error while connecting to AMPS, spark reports that error on the command line.

You can read more about spark in the Spark Section of the AMPS User Guide appendix. Other useful tools for troubleshooting AMPS are described in the AMPS Utilities Guide.

JSON Messages - A Quick Primer¶

AMPS includes support for a wide variety of message types, as well as the ability to develop custom message types and to send binary payloads. This section focuses on JSON as the main message type used for samples in this guide. We use JSON for the guide because the format is simple, easily readable, and already in use in many environments.

JSON format is a simple, standardized message format. JSON has two basic constructs:

objects that consist of key / value pairs
arrays of values

JSON supports hierarchical construction: the value for a key can be a single value, an array of values, or another set of key/value pairs. For example, the following JSON message includes two nested sets of key value pairs. Notice that a key only needs to be unique within each set of values – the name value for the ship does not conflict with the name value for the character.

{
    "id" : 73,
    "character" : {
        "name" : "Han Solo",
        "occupation" : "smuggler",
        "ship" : {
            "name"  : "Millennium Falcon",
            "speed" : ".5 past light speed",
            "cargo" : [ "widgets", "baskets", "spice"]
        }
    }
}

Many AMPS applications use JSON as the payload. In addition, the amps protocol used by most AMPS applications represents commands to AMPS in a JSON-format header. For example, a publish command might look like:

{"c":"publish","t":"test-topic"}{ "id" : 1, "message" : "Hello, World!" }

The command to AMPS, using the amps protocol, is a JSON document which contains the header information for AMPS – in this case, a publish to the topic test-topic. The header is followed by the message body, the payload of the command.

While the amps protocol is implemented as JSON, you can use any message type with the amps protocol: the header for the command will still be JSON, while the body can be in the message type of your choice, as in the sample below, which publishes to an XML topic:

{ "c":"publish","t":"xml-topic"}<example><id>1</id><message>Hello, world!</message></example>

The AMPS client libraries create and parse AMPS headers. For example, the publish method in the AMPS client libraries creates the appropriate header for a publish command based on the provided parameters.

Your applications use the Message and Command interfaces of the AMPS client libraries to work with the AMPS headers. There is no need for your application to parse or serialize the AMPS headers directly.

Tip

The AMPS client libraries handle creating and parsing AMPS headers. They do not parse or interpret the payload data on received Message, instead returning the payload as a sequence of bytes (or as a string).

Table Of Contents

Related Topics