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.