Using

Usings Servlets

Cougaar includes optional servlet components to display metrics data in a browser. These servlets can be used to:

  • View the real-time performance of the society, such as CPU load and message traffic,
  • Debug a running application, for example to find blocked messages, and
  • Illustrate more complex examples of the basic metrics service usage patterns.

The servlets are documented in more detail below. Here is a brief summary of the servlets, in order of most common use by developers:

The rest of this section describes each servlet in more detail:

/message/between-Any-agent-and-Local-Agent

This servlet displays status of communications from an agent on this node to ALL other agents in the society. The servlet is a dump of the RAW contents of the Agent Status Service and does not use the Metrics Service. Click here for a sample display.

/message/between-Node-and-Agent

This servlet displays status of communications from ALL agents on this node to a specified agent. The servlet is a dump of the RAW contents of the Agent Status Service and does not use the Metrics Service. Click here for a sample display.

/message/statistics

This servlet summarizes the Messages statistics for communications out of all agents on this node. This is a raw dump of the legacy MTS Message Statistics Service and does not use the Metrics service. Click here for a sample display.

/metrics/agent/load

This servlet shows the amount of resource consumption for each agent and service that is resident to this node. The resources include CPU, Communications, and Storage. This servlet is used to see which agents are resident on the node and their level of activity. The metrics are all average rates over the averaging interval. Click here for a sample display.

/metrics/host/resources

This servlet shows the status of Host resources for the Node. The most of basic values come from polling Linux /proc. MJIPS (Million Java Instructions per Second) comes from running benchmark. Click here for a sample display.

/metrics/query

This servlet allows the operator to query the MetricsService directly. The result can either be displayed as a web page as XML or returned to the invoker as serialized Java HashMap, depending on the value of the format uri argument. One or more query paths should be supplied as the value of the paths uri argument, with |as the separator.Usage:
http://localhost:8800/$nodename/metrics/query?format=xml&paths=Agent(3-69-ARBN):Jips|Agent(3-69-ARBN):CPULoadJips10SecAvg

The ‘format’ argument is optional, but if left out defaults to xml return of metric data to the browser.
An optional Java version of a metrics query client was written and resides in core/examples/org/cougaar/core/examples/metrics/ExampleMetricQueryClient, returning a hashmap of path values from the query-specified node.

/metrics/remote/agents

This servlet shows the status of resources along the path for communications from any agent on the node to a specific agent. This servlet is useful for debugging. For example, if the Queue length is greater than one, then messages are backed up waiting to be transmitted to the agent. Since messages are usually sent right away this indicates a problem along the path. Likewise, if he Node has not HeardFrom an agent recently, the agent or its node may have failed. Also, the table show the capacity of the network path to the agent and the agent’s host capacity. Click here for a sample display.

/metrics/writer

This servlet allows the operator to write values into the MetricsService directly. The key and valueshould be supplied with uri arguments of the same name. For now the value must be parseable as a double. The metric will be entered with USER_DEFAULT_CREDIBILITY (0.3) and with the client host as the provenance.

Usage: Specified by a prefix of protocol, host, port, nodename and path, followed by some key-value pair in the usual http::get parameter format.

Example: http://localhost:8800/$nodename/metrics/writer/?key=Site_Flow_10.200.2.0/24_10.200.4.0/16_Capacity_Max&value=5600

GUI Conventions

Several metrics servlets uses gui conventions to show three attributes of each metric. In addition, some are mouse sensitive: all the metric’s attributes are displayed on the browser’s documentation line.

The value of the metric is displayed as the base text.

The credibility of the metric is displayed as the color of the text: light gray to indicate that the metric value was only determined as a compile-time default; gray to indicate that the metric value was obtained from a configuration file; black to indicate that the metric value was obtained from a run-time measurement. A metric’s credibility metric is an approximate measure of how much to believe that the value is true. Credibility takes into account several factors, including when, how, by whom a measurement was made.

When the value of a metric crosses a threshold, its value may be interesting enough to warrant attention. This is shown by the color of the background. A green background indicates that the value is in the normal range. A yellow background indicates that the values is in a typical ground state, i.e nothing is happening. A red background indicates that the value has crossed a metric-specific threshold and may be interesting.

 

Color Key