Metric Definitions

This section contains the metrics that are currently standardized.

Host metrics

The name of every host metric must start with the string host. Every metric in this category must have the following parameters:

string host

The host name where the metric should be measured. A local host sensor must refuse to serve the metric if the value of this parameter does not resolve to an address belonging to a local network interface. If the specified host name resolves to more than one network addresses, at least one of them must be local.

Host sensors should try to provide as many information as possible. If some information could not be determined exactly but a reasonable estimate can be made, this estimate should be published.

CPU-related information

Most CPU-related metrics have the following optional parameter:

uint32 cpu (optional)

The identifier of the CPU the consumer is interested in. The range of valid CPU identifiers is host specific (it may not start from 0 and it may not be continuous).

host.cpu.number.
Parameters:

string host
The host name

Data type: uint32 cpus

Measurement unit: pieces

Description: total number of CPUs installed on the system including ones that are not active at the moment. Note that if there are multiple logical CPUs implemented by the same piece of hardware, the returned value is the number of logical CPUs.
host.cpu.online.
Parameters:

string host
The host name

Data type: uint32 cpus

Measurement unit: pieces

Description: number of CPUs that the operating system utilizes currently. Note that the operating system might reserve CPUs for special purposes so not all the reported CPUs might be available for running user processes.
host.cpu.available.
Parameters:

string host
The host name

Data type: uint32 cpus

Measurement unit: pieces

Description: number of CPUs that are available for running general user processes.
host.cpu.indexes.
Parameters:

string host
The host name

Data type: uint32 indexes[];

Description: array of valid CPU indexes. These indexes can be used as values to the "cpu" argument of various CPU metrics.
host.cpu.clocktick.
Parameters:

string host
The host name

Data type: uint32 freq

Measurement unit: Hz

Description: resolution of the time values returned by CPU usage metrics (host.cpu.user, host.cpu.system etc.). This value usually has nothing to do with the speed of the CPU.
host.cpu.frequency.
Parameters:

string host
The host name
uint32 cpu (optional)
The CPU's id

Data type: uint32 freq

Measurement unit: MHz

Description: operating frequency of a CPU. If the system supports mutliple processors running with different speeds, the cpu parameter selects which CPUs frequency will be reported. If the cpu parameter is omitted and there are CPUs running with different frequencies, the returned value will be the frequency of the first online CPU.
host.cpu.type.
Parameters:

string host
The host name
uint32 cpu (optional)
The CPU's id

Data type: string cpu_type

Description: a string describing the CPU type. The exact contents and format is architecture specific.
host.cpu.state.
Parameters:

string host
The host name
uint32 cpu
The CPU's id

Data type: int32 cpu_state (enum: "Normal", "Offline", "Error", "PowerOff", "OS only", "User only", "Restricted");

Description: the current CPU state.
host.cpu.state_begin.
Parameters:

string host
The host name
uint32 cpu
The CPU's id

Data type: uint32 timestamp

Description: timestamp when the CPU entered its current state.
host.cpu.user.
Parameters:

string host
The host name
uint32 cpu (optional)
The CPU's id

Data type: uint32 ticks

Measurement unit: clockticks (see host.cpu.clocktick)

Description: time spent by the processor in user context. If the cpu parameter is omitted, the sum for all CPUs is returned.
host.cpu.system.
Parameters:

string host
The host name
uint32 cpu (optional)
The CPU's id

Data type: uint32 ticks

Measurement unit: clockticks (see host.cpu.clocktick)

Description: time spent by the processor servicing system calls. If the cpu parameter is omitted, the sum for all CPUs is returned.
host.cpu.iowait.
Parameters:

string host
The host name
uint32 cpu (optional)
The CPU's id

Data type: uint32 ticks

Measurement unit: clockticks (see host.cpu.clocktick)

Description: time spent by the processor waiting for external I/O to complete. If the cpu parameter is omitted, the sum for all CPUs is returned.
host.cpu.idle.
Parameters:

string host
The host name
uint32 cpu (optional)
The CPU's id

Data type: uint32 ticks

Measurement unit: clockticks (see host.cpu.clocktick)

Description: time spent by the processor doing nothing. If the cpu parameter is omitted, the sum for all CPUs is returned.
host.cpu.irq.
Parameters:

string host
The host name
uint32 cpu (optional)
The CPU's id

Data type: uint32 ticks

Measurement unit: clockticks (see host.cpu.clocktick)

Description: time spent by the processor servicing hardware interrupts. If the cpu parameter is omitted, the sum for all CPUs is returned.
host.cpu.nice.
Parameters:

string host
The host name
uint32 cpu (optional)
The CPU's id

Data type: uint32 ticks

Measurement unit: clockticks (see host.cpu.clocktick)

Description: time spent by the processor running niced processes. If the cpu parameter is omitted, the sum for all CPUs is returned.
host.cpu.softirq.
Parameters:

string host
The host name
uint32 cpu (optional)
The CPU's id

Data type: uint32 ticks

Measurement unit: clockticks (see host.cpu.clocktick)

Description: time spent by the processor servicing soft interrupts. If the cpu parameter is omitted, the sum for all CPUs is returned.
host.cpu.usage.
Parameters:

string host
The host name
uint32 cpu (optional)
The CPU's id

Data type: rec { uint32 user; uint32 system; uint32 iowait; uint32 idle }

Measurement unit: clockticks (see host.cpu.clocktick)

Description: Compound metrics for CPU usage. If the host supports the host.cpu.irq and/or host.cpu.softirq metrics, they are included in the system time. If the cpu parameter is omitted, the sum for all CPUs is returned.
host.cpu.l1dcache.
Parameters:

string host
The host name
uint32 cpu (optional)
The CPU's id

Data type: uint32 size

Measurement unit: Byte

Description: size of the 1st level data cache of the CPU.
host.cpu.l1icache.
Parameters:

string host
The host name
uint32 cpu (optional)
The CPU's id

Data type: uint32 size

Measurement unit: Byte

Description: size of the 1st level instruction cache of the CPU.
host.cpu.l2cache.
Parameters:

string host
The host name
uint32 cpu (optional)
The CPU's id

Data type: uint32 size

Measurement unit: Byte

Description: size of the 2nd level cache. If multiple processors share the same L2 cache the full cache size will be reported for each processor.
host.cpu.l3cache.
Parameters:

string host
The host name
uint32 cpu (optional)
The CPU's id

Data type: uint32 size

Measurement unit: Byte

Description: size of the 3rd level cache. If multiple processors share the same L3 cache the full cache size will be reported for each processor.

File system information

host.fs.mounted.
Parameters:

string host
The host name

Data type: rec { string dev; string mountpoint; } filesystems;

Description: list of the mounted filesystems.
host.fs.space.
Parameters:

string host
The host name
string fs
Mount point

Data type: rec { uint64 size (unit: "KiB"); uint64 avail (unit: "KiB"); uint64 reserved (unit: "KiB"); } space;

Description: size of the total/available/reserved space in a filesystem. Reserved means that only the superuser is allowed to use this space.
host.fs.inodes.
Parameters:

string host
The host name
string fs
Mount point

Data type: rec { uint64 total; uint64 avail; uint64 reserved; } inodes;

Description: number of total/available/reserved inodes in a filesystem. Reserved means that only files created by the superuser may use these inodes.

Memory information

host.mem.size.
Parameters:

string host
The host name

Data type: uint64 (unit: KiB)

Description: size of the host's total physical memory usable by the operating system, in kilobytes. On some systems this may be smaller than the total amount of physical memory installed if there are reserved memory areas (like AGP aperture, hardware I/O buffers, firmware configuration information or the kernel's code itself).
host.mem.free.
Parameters:

string host
The host name

Data type: uint64 (unit: KiB)

Description: size of the host's free physical memory, in kilobytes. On many systems this metric is rather meaningless because the operationg system uses memory not allocated to running processes for caching and buffering purposes. On those systems (e.g. Linux), "free memory" means "wasted memory that you could remove from the system without performance degradation".
host.mem.shared.
Parameters:

string host
The host name

Data type: uint64 (unit: KiB)

Description: size of memory that is shared between at least two processes on the system.
host.mem.buffers.
Parameters:

string host
The host name

Data type: uint64 (unit: KiB)

Description: size of memory that is currently being used for raw I/O buffers.
host.mem.cached.
Parameters:

string host
The host name

Data type: uint64 (unit: KiB)

Description: size of memory that is currently being used for cached files.

Network interface information

Most network-interface metrics have the following parameter:

string interface

The name of the network interface.

host.net.interfaces.
Parameters:

string host
The host name

Data type: string name[];

Description: name of all the defined network interfaces (including ones that are not running currently).
host.net.recv.byte.
Parameters:

string host
The host name
string interface (optional)
The network interface name

Data type: uint64 amount (unit: Bytes)

Description: amount of data received on a network interface since it is defined. If the interface parameter is omitted, the sum over all up, running, non-loopback interfaces is returned.
host.net.recv.packet.
Parameters:

string host
The host name
string interface (optional)
The network interface name

Data type: uint64 count

Description: number of packets received on a network interface since it is defined. If the interface parameter is omitted, the sum over all up, running, non-loopback interfaces is returned.
host.net.recv.error.
Parameters:

string host
The host name
string interface (optional)
The network interface name

Data type: uint32 count

Description: number of bad packets received on a network interface since it is defined. If the interface parameter is omitted, the sum over all up, running, non-loopback interfaces is returned.
host.net.recv.drop.
Parameters:

string host
The host name
string interface (optional)
The network interface name

Data type: uint32 count

Description: number of received packets dropped (usually due to resource shortage). If the interface parameter is omitted, the sum over all up, running, non-loopback interfaces is returned.
host.net.send.byte.
Parameters:

string host
The host name
string interface (optional)
The network interface name

Data type: uint64 amount (unit: Bytes)

Description: amount of data sent out on a network interface since it is defined. If the interface parameter is omitted, the sum over all up, running, non-loopback interfaces is returned.
host.net.send.packet.
Parameters:

string host
The host name
string interface (optional)
The network interface name

Data type: uint64 count

Description: number of packets sent out on a network interface since it is defined. If the interface parameter is omitted, the sum over all up, running, non-loopback interfaces is returned.
host.net.send.error.
Parameters:

string host
The host name
string interface (optional)
The network interface name

Data type: uint32 count

Description: number of transmission problems on a network interface since it is defined. If the interface parameter is omitted, the sum over all up, running, non-loopback interfaces is returned.
host.net.send.drop.
Parameters:

string host
The host name
string interface (optional)
The network interface name

Data type: uint32 count

Description: number of to-be-sent packets dropped (usually due to resource shortage). If the interface parameter is omitted, the sum over all up, running, non-loopback interfaces is returned.
host.net.send.carrier.
Parameters:

string host
The host name
string interface (optional)
The network interface name

Data type: uint32 count

Description: number of carrier failures on a network interface. If the interface parameter is omitted, the sum over all up, running, non-loopback interfaces is returned.
host.net.collision.
Parameters:

string host
The host name
string interface (optional)
The network interface name

Data type: uint32 count

Description: number of collisions detected by the interface. If the interface parameter is omitted, the sum over all up, running, non-loopback interfaces is returned.
host.net.total.byte.
Parameters:

string host
The host name
string interface (optional)
The network interface name

Data type: uint64 amount (unit: Bytes)

Description: amount of data sent or received on a network interface since it is defined. If the interface parameter is omitted, the sum over all up, running, non-loopback interfaces is returned.
host.net.total.packet.
Parameters:

string host
The host name
string interface (optional)
The network interface name

Data type: uint64 count

Description: number of packets sent or received on a network interface since it is defined. If the interface parameter is omitted, the sum over all up, running, non-loopback interfaces is returned.
host.net.total.error.
Parameters:

string host
The host name
string interface (optional)
The network interface name

Data type: uint32 count

Description: number of bad packets sent or received on a network interface since it is defined. If the interface parameter is omitted, the sum over all up, running, non-loopback interfaces is returned.
host.net.mtu.
Parameters:

string host
The host name
string interface (optional)
The network interface name

Data type: uint32 mtu

Description: MTU size of the interface. If the interface parameter is omitted, the value for the first up, running, non-loopback interface is returned.
host.net.ifflags.
Parameters:

string host
The host name
string interface
The network interface name

Data type: uint32 flags (flags: "Up", "Broadcast", "PoinToPoint", "Loopback", "Running", "Promisc", "Multicast")

Description: interface flags.
host.net.ifindex.
Parameters:

string host
The host name
string interface
The network interface name

Data type: uint32 index

Description: the internal index of an interface. Some systems allow renaming network interfaces on the fly, but the interface index remains constant while the interface is defined.
host.net.addr.ipv4.
Parameters:

string host
The host name
string interface (optional)
The network interface name

Data type: rec { uint32 addr (format: ipv4); uint32 netmask (format: ipv4); uint32 broadcast (format: ipv4); uint32 dest (format: ipv4); string label; } addresses[];

Description: the IPv4 address(es) the interface has. If the address is attached to the interface directly, the label field will be empty. If the address is attached as an interface alias, the label field will contain the name of the interface alias. If the interface parameter is omitted, the value for the first up, running, non-loopback interface is returned.
host.net.addr.ipv6.
Parameters:

string host
The host name
string interface (optional)
The network interface name

Data type: rec { opaque addr (format: ipv6); uint32 prefixlen; opaque dest (format: ipv6); string label; } addresses[];

Description: the IPv6 address(es) the interface has. If the address is attached to the interface directly, the label field will be empty. If the address is attached as an interface alias, the label field will contain the name of the interface alias. If the interface parameter is omitted, the value for the first up, running, non-loopback interface is returned.
host.net.addr.hwaddr.
Parameters:

string host
The host name
string interface (optional)
The network interface name

Data type: opaque hwaddr (format: hwaddr);

Description: the hardware address of the interface. If the interface parameter is omitted, the value for the first up, running, non-loopback interface is returned.
host.net.hwtype.
Parameters:

string host
The host name
string interface (optional)
The network interface name

Data type: string hwtype;

Description: the hardware type of the interface. If the interface parameter is omitted, the value for the first up, running, non-loopback interface is returned.

Information about the operating system

host.os.name.
Parameters:

string host
The host name

Data type: string osname;

Description: name of the operating system.
host.os.release.
Parameters:

string host
The host name

Data type: string release;

Description: the release identifier of the operating system. The exact contents and meaning is operating system dependent.
host.os.version.
Parameters:

string host
The host name

Data type: string version;

Description: version of the operating system. The format of the version string is operating system dependent.
host.os.machine.
Parameters:

string host
The host name

Data type: string machine;

Description: system architecture identifier.
host.os.boottime.
Parameters:

string host
The host name

Data type: uint32 timestamp (format: unixtime);

Description: time when the currently running operating system instance booted.

Swap information

host.swap.size.
Parameters:

string host
The host name

Data type: uint64 (unit: KiB)

Description: total size of the available swap area(s). This includes any active swap files and/or swap partitions.
host.swap.free.
Parameters:

string host
The host name

Data type: uint64 (unit: KiB)

Description: size of the swap area that is currently unused.
host.swap.in.
Parameters:

string host
The host name

Data type: uint64 (unit: KiB)

Description: amount of memory that was read in from the swap area(s) since boot.
host.swap.out.
Parameters:

string host
The host name

Data type: uint64 (unit: KiB)

Description: amount of memory that was written to the swap area(s) since boot.

Virtual memory management information

host.vm.page.in.
Parameters:

string host
The host name

Data type: uint64 (unit: KiB)

Description: amount of memory that was read since boot.
host.vm.page.out.
Parameters:

string host
The host name

Data type: uint64 (unit: KiB)

Description: amount of memory that was written since boot.
host.vm.page.fault.
Parameters:

string host
The host name

Data type: uint64 count

Description: number of page faults since boot.
host.vm.page.majorfault.
Parameters:

string host
The host name

Data type: uint64 count

Description: number of major page faults since boot.

Disk information

host.disk.disks.
Parameters:

string host
The host name

Data type: rec { string device; uint64 size (unit: "KiB"); } disks[];

Description: name and size of disk devices connected to the system
host.disk.partitions.
Parameters:

string host
The host name
string disk (optional)
The host name

Data type: rec { string device; uint64 size (unit: "KiB"); } disks[];

Description: name and size of disk partitions. If disk is not given, partitions on all known disks are returned.
host.disk.iostat.
Parameters:

string host
The host name
string disk (optional)
The host name

Data type: rec { uint32 reads; uint32 writes; uint64 read_kb (unit: "KiB"); uint64 write_kb (unit: "KiB"); uint32 in_progress; uint64 time (unit: "ms"); uint64 weighted_time (unit: "ms") } stats;

Description: I/O statistics. If disk is missing, the totals over all disks are returned.

Misc. information

host.loadavg.
Parameters:

string host
The host name

Data type: double load[3]

Description: array of 1 minute, 5 minute and 15 minute load averages.
host.users.
Parameters:

string host
The host name

Data type: uint32 count

Description: number of users logged in interactively.

Application metrics

app.message.
Parameters:

string jobid
The job ID
string progname (optional)
The process name
int32 tid (optional)
The thread ID

Data type: string

Description: generic application-generated message.
app.event.
Parameters:

string jobid
The job ID
string progname (optional)
The process name
int32 tid (optional)
The thread ID

Data type: rec { string progname; int32 tid; string event; } event;

Description: information about processes starting, quitting or crashing.

app.getvar.int32.

Parameters:

string `jobid`	The job ID
string `progname` (optional)	The process name
int32 `tid` (optional)	The thread ID
string `name`	The name of the variable
int32 `start` (optional)	The index of the first array element to return (default: 0)
int32 `length` (optional)	The number of array elements to return (default: all)

Data type: rec { string progname; int32 tid; int32 value[]; } event;

Description: get the value of an application-defined array of 32-bit integers.

app.getvar.int64.

Parameters:

string `jobid`	The job ID
string `progname` (optional)	The process name
int32 `tid` (optional)	The thread ID
string `name`	The name of the variable
int32 `start` (optional)	The index of the first array element to return (default: 0)
int32 `length` (optional)	The number of array elements to return (default: all)

Data type: rec { string progname; int32 tid; int64 value[]; } value;

Description: get the value of an application-defined array of 64-bit integers.

app.getvar.double.

Parameters:

string `jobid`	The job ID
string `progname` (optional)	The process name
int32 `tid` (optional)	The thread ID
string `name`	The name of the variable
int32 `start` (optional)	The index of the first array element to return (default: 0)
int32 `length` (optional)	The number of array elements to return (default: all)

Data type: rec { string progname; int32 tid; double value[]; } value;

Description: get the value of an application-defined array of 64-bit double precision floating point numbers.

app.getvar.string.

Parameters:

string `jobid`	The job ID
string `progname` (optional)	The process name
int32 `tid` (optional)	The thread ID
string `name`	The name of the variable
int32 `start` (optional)	The index of the first character of the string to return (default: 0)
int32 `length` (optional)	The number of characters to return (default: all)

Data type: rec { string progname; int32 tid; string value; } value;

Description: get the value of an application-defined string (or part of it).

app.getvar.bytes.

Parameters:

string `jobid`	The job ID
string `progname` (optional)	The process name
int32 `tid` (optional)	The thread ID
string `name`	The name of the variable
int32 `start` (optional)	The index of the first byte of the variable to return (default: 0)
int32 `length` (optional)	The number of bytes to return (default: all)

Data type: rec { string progname; int32 tid; opaque value; } value;

Description: get the value of an application-defined opaque variable (or part of it).

app.getvar.info.
Parameters:

string jobid
The job ID
string progname (optional)
The process name
int32 tid (optional)
The thread ID
string name
The name of the variable

Data type: rec { string progname; int32 tid; string type; int32 length; boolean readonly; } info;

Description: get information about an application-defined variable

Internal metrics

monitor.ctrl.def.
Parameters:

string name
The name of the control

Data type: rec { int32 domain; string name; string type; rec { string name; string type; uint32 flags; } params[]; int32 measurement; } definition;

Description: definition of the specified control.
monitor.metric.def.
Parameters:

string name
The name of the metric

Data type: rec { int32 domain; string name; string type; rec { string name; string type; uint32 flags; } params[]; int32 measurement; } definition;

Description: definition of the specified metric.
monitor.metric.killed.
Data type: uint32 metric;

Description: this special metric is sent when a metric instance is destroyed inside the producer.
monitor.dropped.
Data type: rec { uint32 metric; uint32 count (unit: "messages"); } value;

Description: this special metric is sent when the producer had to drop some messages due to the length of the message queue exceeding the allowed limit.

string `host`	The host name
uint32 `cpu` (optional)	The CPU's id

string `host`	The host name
string `interface` (optional)	The network interface name

string `host`	The host name
string `interface (optional)`	The network interface name

string `host`	The host name
string `disk` (optional)	The host name