COUGAAR Metrics Service: Paths

Metric Paths

This section discusses the structure of the Metrics Paths and defines common Paths.

Metrics read from the MetricsService are the values from a real-time model of the status of the Cougaar Society and system resources. The MetricsService allow access to formulas in the model. Formulas are relative to a Resource Context, which define instances of modeled entries and there relationship between each other.

Containment is a major relationship which is modeled. Child context inherit all the formulas of its parent. The useful containment relationship in Cougaar are Host->Node->Agent. For example, Agents have all the formulas of their hosts, and when agents moves to a new host the metrics track new hosts values.

Path Syntax

A Path is a series of Contexts followed by a Formula. If there is more than one child Context of the same type in the parent Context, then the child Context is narrowed by Parameters. Each Context has a fixed number of parameters and parameter order is important. The Context type is used as the name of the context. Context and Formula names are case sensitive. For example:

IpFlow(128.33.15.114,128.33.15.113):CapacityMax

The separator between Contexts and formulas is the ":" and the separator between parameters is the ",". But your code you should use the constant PATH_SEPR defined in interface org.cougaar.core.qos.metrics.Constants:

"IpFlow(128.33.15.114,128.33.15.113)" +PATH_SEPR+ "CapacityMax"

The following sections will use the convention of writing variable parameter fields in brackets [] for variable parameters; using ":" as the Path Separator; and "," as the parameter separator. The syntax is as follows

ContextType1([parameter1],[parameter2]...):ContextType2([parameter]):Formula(parameter)

The Averaging Period are parameters for some Formulas. The Averaging Periods are: "10", "100", and "1000". This section will use the convention 1xxxSecAvg to represent the averaging period.

Also, please use the constants interface in core module org.cougaar.core.qos.metrics.Constants whenever possible. This will allow compile time detection of errors, when the Metrics Service interface inevitably changes in the future

Host Context

Host Contexts can be accessed at root level and take one parameter which is the Host address. The Host address can be IP V4 address or the domain name. Hosts contexts are not contained in other Contexts.

Host([host Addr]):EffectiveMJips: The expected per thread Millions of Java Instructions Per Second. The formula takes into account the base CPU JIPS, the number of CPUs, and the Load Average on the Host
Host([Host Addr]):Jips: CPU capacity in Java Instructions Per Second. JIPS is determined through a benchmark.
Host([Host Addr]):LoadAverage: CPU load average, i.e. the average number of processes that are ready to run.
Host([Host Addr]):Count: The number of CPUs in this host
Host([Host Addr]):Cache: Size of CPU level 2 cache
Host([Host Addr]):TotalMemory: Total Physical Memory
Host([Host Addr]):FreeMemory: Free Physical Memory
Host([Host Addr]):TcpInUse: TCP sockets in use
Host([Host Addr]):UdpInUse: UDP sockets in use

Node Context

Node Contexts can be accessed at root level and take one parameter which is the the Node's Message address. The Node is also contained within a Host Context and inherits all the Host Context's formulas.

Node([Node ID]):CPULoadAvg(1xxxSecAvg): The average number of threads working for all component on this Node during the Averaging Period.
Node([Node ID]):CPULoadMJips(1xxxSecAvg): The average MJIPS used by all the threads for all components on this Node during the Averaging Period.
Node([Node ID]):MsgIn(1xxxSecAvg): The average messages into all Agents on this Node during the Averaging Period.
Node([Node ID]):MsgOut(1xxxSecAvg): The average messages out of All Agents this Node during the Averaging Period.
Node([Node ID]):BytesIn(1xxxSecAvg): The average number of bytes (for all messages) into all Agents on this Node during the Averaging Period.
Node([Node ID]):BytesOut(1xxxSecAvg): The average number of bytes (for all messages) out of All Agents on this Node during the Averaging Period.
Node([Node ID]):VMSize: Size in Bytes of the Node's VM
Node([node Addr]):Destination([Agent ID]):MsgTo(1xxSecAvg): Message per second from all agents on the Node, to the destination Agent
Node([node Addr]):Destination([Agent ID]):MsgFrom(1xxSecAvg): Message per second to any agent on the Node, from the destination Agent
Node([node Addr]):Destination([Agent ID]):BytesTo(1xxSecAvg): Bytes per second from all agents on the Node, to the destination Agent
Node([node Addr]):Destination([Agent ID]):BytesFrom(1xxSecAvg): Bytes per second to any agent on the Node, from the destination Agent
Node([node Addr]):Destination([Agent ID]):AgentIpAddress: Ip address of destination Agent
Node([node Addr]):Destination([Agent ID]):CapacityMax: Maximum capacity of the network between Node and destination Agent.
Node([node Addr]):Destination([Agent ID]):OnSameSecureLAN: True if Node and Destination are on the same secure LAN. The current formula just checks if the network capacity between the Node and Agent is greater than or equal to 10 Mbps.

Agent Context

Agent Contexts can be accessed at root level and take one parameter which is the the Agent's Message address. The Agent Context is also contained within a Node Context and inherits all the Node Context's formulas. When an Agent moves to a new Node, the Agent Context will be moved the the corresponding Node, i.e. all the re-wiring is automatic, but may be slightly delayed due to discovery issues.

Agent([Agent ID]):LastHeard: Seconds since some component has heard from this agent. This can be from any source such as successful communication, acknowledgment, or gossip.
Agent([Agent ID]):LastSpoke: Seconds since some component attempted to Speak to the Agent. The attempt does not have to be successful. For example, if a failed message is retied, LastSpoke will be the time of last retry
Agent([Agent ID]):SpokeErrorTime: Seconds since last error in communications. This is a large number with 0.0 credibility, if no error has occurred.
Agent([Agent ID]):CPULoadAvg(1xxxSecAvg): The average number of threads working for this Agent during the Averaging Period.
Agent([Agent ID]):CPULoadMJips(1xxxSecAvg): The average MJIPS used by all the threads for this Agent during the Averaging Period.
Agent([Agent ID]):MsgIn(1xxxSecAvg): The average messages into this Agent during the Averaging Period.
Agent([Agent ID]):MsgOut(1xxxSecAvg): The average messages out of this Agent during the Averaging Period.
Agent([Agent ID]):BytesIn(1xxxSecAvg): The average number of bytes (for all messages) into this Agent during the Averaging Period.
Agent([Agent ID]):BytesOut(1xxxSecAvg): The average number of bytes (for all messages) out of this Agent during the
Agent([Agent ID]):PersistSizeLast: Size in Bytes of the last persistence file for this agent

IpFlow Context

IpFlow Context can be accessed at root level and takes two parameters which is the source and destination host addresses. The Host address can be the IP V4 address or the domain name.

IpFlow([SrcAddr],[DstAddr]):CapacityMax: Maximum Bandwidth between two hosts
IpFlow([SrcAddr],[DstAddr]):CapacityUnused: Unused Bandwidth between two hosts

AgentFlow Context

AgentFlow Context can be accessed at root level and takes two parameters which is the source and destination agent message address.

Since 11.2 the AgentFlow context is no longer used, because it added too many formulas to the metrics service when societies are large.

AgentFlow([SrcAddr],[DstAddr]):MsgRate(1xxxSecAvg): Messages per Second from Source Agent to Destination Agent."
AgentFlow([SrcAddr],[DstAddr]):ByteRate(1xxxSecAvg): Bytes per Second from Source Agent to Destination Agent.