Product SiteDocumentation Site

3.2. Performance Metric Instances

When performance metric values are returned across the PMAPI to a requesting application, there may be more than one value for a particular metric; for example, independent counts for each CPU, or each process, or each disk, or each system call type, and so on. This multiplicity of values is not enumerated in the Name Space, but rather when performance metrics are delivered across the PMAPI.
The notion of metric instances is really a number of related concepts, as follows:
  • A particular performance metric may have a set of associated values or instances.
  • The instances are differentiated by an instance identifier.
  • An instance identifier has an internal encoding (an integer value) and an external encoding (a corresponding external name or label).
  • The set of all possible instance identifiers associated with a performance metric on a particular host constitutes an instance domain.
  • Several performance metrics may share the same instance domain.

Example 3.1. Metrics Sharing the Same Instance Domain

 $ pminfo -f
    inst [1 or “/dev/disk0”] value 1803
    inst [2 or “/dev/disk1”] value 22140
    inst [3 or “/dev/disk2”] value 157938
The metric has three values, currently 1803, 22140, and 157938. These values are respectively associated with the instances identified by the internal identifiers 1, 2 and 3, and the external identifiers /dev/disk0, /dev/disk1, and /dev/disk2. These instances form an instance domain that is shared by the performance metrics filesys.capacity, filesys.used,, filesys.mountdir, and so on.
Each performance metric is associated with an instance domain, while each instance domain may be associated with many performance metrics. Each instance domain is identified by a unique value, as defined by the following typedef declaration:
        typedef unsigned long pmInDom;
The special instance domain PM_INDOM_NULL is reserved to indicate that the metric has a single value (a singular instance domain). For example, the performance metric mem.freemem always has exactly one value. Note that this is semantically different to a performance metric like kernel.percpu.cpu.sys that has a non-singular instance domain, but may have only one value available; for example, on a system with a single processor.
In the results returned above the PMAPI, each individual instance within an instance domain is identified by an internal integer instance identifier. The special instance identifier PM_IN_NULL is reserved for the single value in a singular instance domain. Performance metric values are delivered across the PMAPI as a set of instance identifier and value pairs.
The instance domain of a metric may change with time. For example, a machine may be shut down, have several disks added, and be rebooted. All performance metrics associated with the instance domain of disk devices would contain additional values after the reboot. The difficult issue of transient performance metrics means that repeated requests for the same PMID may return different numbers of values, or some changes in the particular instance identifiers returned. This means applications need to be aware that metric instantiation is guaranteed to be valid only at the time of collection.


Some instance domains are more dynamic than others. For example, consider the instance domains behind the performance metrics proc.memory.rss (one instance per process), (one instance per swap partition) and kernel.percpu.cpu.intr (one instance per CPU).