Cougaar "Ping" Demos

NOTE: This file and all referenced files are included in the demo-ping.zip of the latest Cougaar release.

This module contains the Cougaar "ping" demos.

There are six demos:

1. A basic "ping" test, where agent "A" sends a ping message to agent "B" once every 5 seconds.
2. A two-node "ping" test, which is identical to the above test, except the agents run in different JVMs.
3. A two-host "ping" test, which simply distributes the above JVMs (and their agents) across two hosts.
4. A single-node "ping" benchmark, where the the agents send ping messages as fast as possible. The "messages-per-second" throughput can be viewed by accessing a browser page.
5. A two-node "ping" profiled benchmark, where detailed performance metrics are logged every 10 seconds. Logged metrics include the throughput, inter-agent traffic matrix, and cpu load
6. A two-node "ping" where agent "A" sends to 11 other agents (i.e. a "fan-out" pattern)

For additional information, please see the Cougaar Overview Slides:
  http://cougaar.org/docman/view.php/17/196/CougaarOverview.ppt.

Index:

• Contents
• Installation
• Usage
• Support

Contents:

1. configs/*.xml:
   The society files.
2. run/*.xml:
   The runtime files.
3. run/logging.props:
   The Log4j logging configuration file.
4. src/org/cougaar/demo/ping/*.java:
   The Java source code consists of:
   • A "ping sender" (javadoc, code)
   • A "ping receiver" (javadoc, code)
   • A "ping servlet" (javadoc, code)

Installation:

The "Hello World" README is available online at:
   http://cougaar.org/cgi-bin/viewcvs.cgi/*checkout*/hello/doc/README.html?rev=1.1.1.1&cvsroot=tutorials#installation
and in the "cougaar-hello.zip" produced by the nightly build:
   http://build.cougaar.org/auto/HEAD/latest_success/

Usage:

1. A basic "ping" test:
   1. Run:
        cd $COUGAAR_RUNTIME_PATH
  cougaar $COUGAAR_SOCIETY_PATH/configs/PingBasicSociety.xml PingBasicRuntime.xml
      This should print:
        [PingSender] - A: Sending ping 0 to B
  [DOTS] - +-
  [PingReceiver] - B: Responding to ping 0 from A
  [DOTS] - +-
  [PingSender] - A: Received response 0 from B
  [PingSender] - A: Will send ping 1 to B in 5 seconds
  [DOTS] - .
        ...
      
   2. Optionally view the servlet at
        http://localhost:8800/$A/ping
   3. Press CTRL-C to stop the run.

2. A two-node "ping" test:
   1. In one console window, run:
        cd $COUGAAR_RUNTIME_PATH
  cougaar $COUGAAR_SOCIETY_PATH/configs/PingTwoNodesSociety.xml PingTwoNodesRuntime.xml Node1
   2. In a second console window, run:
        cd $COUGAAR_RUNTIME_PATH
  cougaar $COUGAAR_SOCIETY_PATH/configs/PingTwoNodesSociety.xml PingTwoNodesRuntime.xml Node2
   3. The output should match the output of the single-node ping test. There may be a startup delay of up to a minute, due to the naming service.
   4. Press CTRL-C to stop the run.

3. A two-host "ping" test:
   1. Modify the $COUGAAR_SOCIETY_PATH/configs/PingTwoNodesRuntime.xml to change the host name from "localhost" to the host that will run "Node1".
   2. Perform the same steps as in the two-node test.

      If the agents are unable to communicate with one another, verify that both hosts can `/bin/ping` one another, that ports 8888 and 8800 are not blocked, and that `/bin/hostname -iv` prints the correct host names and IP addresses. If all else fails, please contact us for additional support.

4. A single-node "ping" benchmark:
   1. Run:
        cd $COUGAAR_RUNTIME_PATH
  cougaar $COUGAAR_SOCIETY_PATH/configs/PingBenchmarkSociety.xml PingBenchmarkRuntime.xml
      Note that the above runtime XML file has been modified to disable the logging output.
   2. Optionally view the servlet at
        http://localhost:8800/$A/ping
      Note the high "pings-per-second" throughput, due to the below "delayMillis=0" setting.
   3. Optionally view the metrics servlets, e.g.:
        http://localhost:8800/metrics/agent/load
      For a full listing of included metrics servlets, see:
        doc/OnlineManual/MetricsService/operation.html
   4. Press CTRL-C to stop the run.

5. A two-node "ping" profiled benchmark:
   1. In one console window, run:
        cd $COUGAAR_RUNTIME_PATH
  cougaar $COUGAAR_SOCIETY_PATH/configs/PingProfileSociety.xml PingProfileRuntime.xml Node1
   2. In a second console window, run:
        cd $COUGAAR_RUNTIME_PATH
  cougaar $COUGAAR_SOCIETY_PATH/configs/PingProfileSociety.xml PingProfileRuntime.xml Node2
   3. As in the single-node "ping" benchmark, the standard ping logging has been disabled.

      However, Node1 is configured to log detailed profiling output every 10 seconds.

      The logged metrics include various Cougaar-internal metrics:

      • inter-agent messaging traffic matrix
      • aggregate messaging throughput
      • blackboard sizes and number of add/change/remove operations
      • thread pool load
      • JVM heap size
      and system metrics:
      • cpu load (from /proc/loadavg)
      • memory load (from /proc/meminfo)
      • network stats (from /proc/net/dev)
      • overall system stats (from /usr/bin/vmstat)
   4. Let both nodes run for a couple minutes, then examine the logs for the following interesting metrics:
      • "[tl_A]" is the number of messages sent by agent A to any target
      • "[tr_B]" is the number of messages received from agent B to any agent on Node1
      • "[tm_A__to__B]" is the number of messages sent between agents A and B
      • "[throughput]" is the number of message sent and received
      • "[bb_A__Relay]" is the number of relay add/change/removes
      • "[load_node_Node1]" is the cpu load average

      The "[throughput]" is a good overall performance metric. Here is example output:
        [throughput] - #agent_send_count_per_second, total_send_count_per_second, agent_send_count, total_send_count,
  [throughput] - 257.90, 258.10, 8190, 8205
      The above throughput rates should be twice the "/ping" servlet rate, since each ping iteration consists of a ping message and an "ack" message.

      For documentation on the other profiled metrics, please see the "profile" module code and javadoc.

   5. Press CTRL-C in both console windows to stop the run.

6. A two-node "ping" fan:
   1. Run the PingFanSociety.xml and PingFanRuntime.xml files, as noted in the above two-node tests. Examine the "/$A/ping" servlet to view the society progress.

Support:

1. Subscribe to the cougaar-developers mailing list:
     http://cougaar.org/mailman/listinfo/cougaar-developers
2. Then send email to:
     cougaar-developers@cougaar.org