The pget.py Script

Usage: pget.py [options]
Options:
  -h, --help            show this help message and exit
  -u USER, --user=USER  name of user to authenticate as
  -p PASSWORD, --password=PASSWORD
                        password of user to authenticate as
  -s SERVER, --server=SERVER
                        hostname or IP address of the Pion server
  --port=PORT           port number on the Pion server to connect to
  --ssl                 use SSL encryption for the Pion server connection
  -r REACTOR, --reactor=REACTOR
                        identifier of reactor to perform an action upon
  --stats               retrieves statistics for one or all Pion reactors
  --start               starts a reactor if it is not already running
  --stop                stops a reactor if it is running
  --query=QUERY         calls a reactor's query service
  -l LIST, --list=LIST  list reactors of a specific type (or "all")
  --listkeys            lists all RSA private keys in keystore
  --addkey              add a new RSA private key to keystore
  --removekey=REMOVEKEY
                        removes specified RSA private key from keystore

The pget.py script is used to query particular web services available on the Pion server. For more information on the various web services accessible in Pion, see:
http://pion.org/projects/pion-platform/documentation/services

The -u, -p, -s, --port and --ssl options tell both scripts how to communicate with your Pion server. The following defaults are used, which correspond to the default settings for a Pion server:

-u pion
-p pion
-s localhost
--port 8888
(no --ssl)

pget.py examples

Get reactor config:
pget.py -r <id>

Get (ALL) reactor config:
pget.py /config/reactors

Start a reactor:
pget.py --start -r <id>

Stop a reactor:
pget.py --stop -r <id>

Get statistics for a reactor:
pget.py --stats -r <id>

Get statistics for all reactors:
pget.py --stats

Rotate log for LogOutputReactor:
pget.py -r <id> --query rotate

List all reactors:
pget.py --list all

List all SnifferReactors:
pget.py --l SnifferReactor

List all items in the SSL Key Store:
pget.py --listkeys

Remove an item from the SSL Key Store:
pget.py --removekey <key-id>

Add a new item to the SSL Key Store:
pget.py --addkey
(this will prompt you for additional input)

Retrieve platform.xml configuration:
pget.py /config
(Note that you can specify any web service URI stem supported by Pion)

The pmon.py Script

Usage: pmon.py [options]
Options:
  -h, --help            show this help message and exit
  -u USER, --user=USER  name of user to authenticate as
  -p PASSWORD, --password=PASSWORD
                        password of user to authenticate as
  -s SERVER, --server=SERVER
                        hostname or IP address of the Pion server
  --port=PORT           port number on the Pion server to connect to
  --ssl                 use SSL encryption for the Pion server connection
  -c COMMAND, --command=COMMAND
                        command to execute at the end of each interval
  -e EMAIL, --email=EMAIL
                        email address(es) to which alerts will be sent
  --restart=RESTART     command executed to restart Pion if connection is lost

The pmon.py script allows you to monitor the status of a Pion server. It can be used to watch for adverse conditions, generate detailed statistics logs, send email alert messages, and automatically restart the Pion server if necessary.

Running pmon.py without any arguments will retrieve and display all the “key metrics” for a Pion instance:

------------------------------------------ 
| PION STATISTICS AT 2009-09-11 07:01:36 | 
------------------------------------------ 
ClickstreamReactor(Sessionize Traffic).OpenSessions = 433 / 100000 
ClickstreamReactor(Sessionize Traffic).OpenPages = 85 / 10000 
ClickstreamReactor(Sessionize Traffic).OpenEvents = 290 / 100000 
ClickstreamReactor(Sessionize Traffic).OpenOrphans = 19 / 100000 
DatabaseOutputReactor(Debug Table).EventsQueued = 0 / 7500 
DatabaseOutputReactor(Debug Table).KeyCacheSize = 0 / 100000 
...

You can include a numeric argument to pmon.py, which represents an interval of time in seconds. When run in this fashion, pmon.py will repeatedly monitor the “key metrics” pausing for the given number of seconds in between each check (similar to the Unix “iostat” command).

You can use the “-c” option to have pmon.py run an additional command for each check it performs to include the results of that command in its ouput. For example, you may way to use “iostat” or “df” to log disk usage over time (i.e. “-c iostat”).

Using the “--restart” option, you can have pmon.py automatically restart Pion if it is no longer responding (i.e. “--restart '/etc/init.d/pion restart'”).

You can also use the “-e” option to have pmon.py send an email message whenever key metrics exceed pre-defined boundaries or if the Pion server is no longer responding and when it is restarted (i.e. “-e alerts@mydomain.com”).

For example, the following command will monitor a Pion instance running on the same server with default configuration by checking the key metrics every 10 seconds. It will write IO statistics and key metrics to a log file (“/var/log/pion/stats.log”), automatically restart Pion if necessary, and will send an email message if anything goes wrong:

pmon.py -c 'iostat' -e 'alerts@mydomain.com' --restart '/etc/init.d/pion restart' 10 > /var/log/pion/stats.log &

Customizing pmon.py

In some circumstances, it may be necessary to customize your pmon.py script. There are several variables at the top of the script that start with “SMTP_” which are used to configure the SMTP server that is used to send email alerts:

# these parameters control how email alert messages are sent
SMTP_SENDER = 'pion@localhost'
SMTP_SERVER = 'localhost'
SMTP_PORT = 25
SMTP_USER = ''
SMTP_PASSWORD = ''

To add, remove or change the thresholds for the key metrics that pmon.py monitors, just modify the KEY_METRICS map located below the SMTP variables:

# defines a mapping of reactor statistics to maximum threshold values

KEY_METRICS = {
        'DatabaseOutputReactor' : {
                'EventsQueued' : 7500,        # events queued for db inserts
                'KeyCacheSize' : 100000,      # recent index keys cached
                },
...

Extending pget.py

The pget.py script is designed so that it can also be easily used as a module for other Python scripts. This makes it easy to write your own scripts that make use of Pion's web services.

To use pget.py as a module within your own script, include the statement “import pget” and make sure that it is located in your Python modules path or the same directory as your script. The following is a simple example that displays the results of querying the “/config” web service:

# import the pget module
import pget

# parse command line arguments
parser = pget.get_arg_parser() 
options, arguments = parser.parse_args()

# open connection to the Pion server	 
con = pget.get_con(options)

# send a request and display response
r = pget.send_request(con, '/config', headers=options.headers) 
print r.read()