Metric Keys

This section discusses the structure of the Metrics keys name-space and defines common keys.

Metrics are written into the MetricsUpdateService as key-value pairs. While the key itself is just a string, we impose a structure to help organize the information, loosely modeled after SNMP MIBs. The value is a Metric, a structured object with slots for value, credibility, time-stamp, units, etc.

At runtime, each Node has a store of Key-Value pairs. When the MetricsUpdaterService receives a new Key-Value pair, it looks up the Key in the store. If the value has changed, all the Metrics Formulas that have subscribed to this Key will be called-back with the new Value. The Metrics Service in each Node has one and only one effective Value for each Key, which is derived through a complicated set of integration rules based on credibility and timestamps.

Normally, Key-Value pairs are not read from the Metrics Service, but are only processed by internal formulas. One debugging trick to view the effective value of a key is to the Path Integrater, which takes a Key as a parameter and returns the effective metric. Currently, there is no way to list all the Keys available to a Node.

Key Syntax

A Metrics Key is a string divided into fields using the Key Separator, e.g.

Host_128.33.15.114_CPU_Jips

The current Key Separators is “_”. But your code you should use the string constant KEY_SEPR defined in org.cougaar.core.qos.metrics.Constants:

"Host" +KEY_SEPR+ "128.33.15.114" +KEY_SEPR+ "CPU" +KEY_SEPR+ "Jips"

Notice that some of the fields are types (e.g. Host, CPU, Jips) and others are identifiers (e.g. 128.33.15.114). The types are fixed and case sensitive. Identifiers are variable and define branches in naming hierarchy.

In the following section we will use the convention of writing identifier fields in brackets [], and using “_” as the Key Separator

Host_[Host IP]_CPU_Jips

Host

Host Keys start with identifying the host and then have several optional field for different host characteristics. Host identifiers are raw IP V4 addresses, not domain names.

Host_[Host IP]_CPU_Jips

CPU capacity in Java Instructions Per Second. JIPS is determined through a benchmark.

Host_[Host IP]_CPU_loadavg

CPU load average, i.e. the average number of processes that are ready to run.

Host_[Host IP]_CPU_count

The number of CPUs in this host

Host_[Host IP]_CPU_cache

Size of CPU level 2 cache

Host_[Host IP]_Memory_Physical_Total

Total Physical Memory

Host_[Host IP]_Memory_Physical_Free

Free Physical Memory

Host_[Host IP]_Network_TCP_sockets_inuse

TCP sockets in use

Host_[Host IP]_Network_UDP_sockets_inuse

UDP sockets in use.

IP Flow

Network Keys start with identifying the IP Flow and then have several optional field for different network characteristics. End-point addresses are raw IP V4 addresses and not domain names.

Ip_Flow_[src IP]_[dst IP]_Capacity_Max

The maximum bandwidth (kbps)for path across the network, i.e. with no competing traffic. 

Ip_Flow_[src IP]_[dst IP]_Capacity_Unused

The expected available bandwidth (kbps) for a path across the network, i.e. the max minus the competing traffic.

Site Flow

Sites are an IP subnetwork which can be represented with a simple mask (number of bits with leading 1′s). Site_Flows between sites can be used as defaults, instead of specify specific Ip_Flows. For example,

Site_Flow_128.89.0.0/16_128.33.15.0/28_Capacity_Max

Site_Flow_[src IP/mask]_[dst IP/mask]_Capacity_Max

Maximum bandwidth (kbps) between Sites. The current formulas can model asymmetric bandwidth between Sites, by publishing Site_Flows for both direction. If only one direction is published, the formulas will assume the bandwidth is the same in both directions.

Agent

Agents are identified by their message Id.

Agent_[Message ID]_HeardTime

System.currentTimeMillis() time-stamp for the last time some component has heard from this agent.

Agent_[Message ID]_SpokeTime

System.currentTimeMillis() time-stamp for the last time some component has attempted to speak to this agent.

Node

Nodes are identified by their message Id. Currently, there are no Node specific Keys