B.2. Agent check types

 B.2.1. agent.filesystem

 Summary

The agent.filesystem check exposes file system related metrics (free space, used space, etc.)

Table B.22. Attributes
FieldDescriptionValidation
target The mount point to check (eg '/var' or 'C:')
  • String between 1 and 512 characters long

Table B.23. Metrics
MetricDescriptionType
availAvailable space on the filesystem in kilobytes, not including reserved space.Int64
freeFree space available on the filesystem in kilobytes, including reserved space.Int64
optionsNo description is available at the moment.String
totalTotal space on the filesystem, in kilobytes.Int64
usedUsed space on the filesystem, in kilobytes.Int64
filesNumber of inodes on the filesystem. Note: this metric is not available on Windows.Int64
free_filesNumber of free inodes on the filesystem. Note: this metric is not available on Windows.Int64

 B.2.2. agent.memory

Table B.24. Attributes
FieldDescriptionValidation
No fields are present for this particular check type.
Table B.25. Metrics
MetricDescriptionType
actual_freeThe actual amount of free memory.Int64
actual_usedThe actual amount of used memory.Int64
freeFree space available on the filesystem in kilobytes, including reserved space.Int64
ramNo description is available at the moment.Int64
swap_freeNo description is available at the moment.Int64
swap_page_inNo description is available at the moment.Int64
swap_page_outNo description is available at the moment.Int64
swap_totalNo description is available at the moment.Int64
swap_usedNo description is available at the moment.Int64
totalTotal space on the filesystem, in kilobytes.Int64
usedUsed space on the filesystem, in kilobytes.Int64

 B.2.3. agent.load_average

 Summary

The agent.load_average check will attempt to measure the Unix-style Load Average on a host.

Table B.26. Attributes
FieldDescriptionValidation
No fields are present for this particular check type.
Table B.27. Metrics
MetricDescriptionType
1m One minute load average. Double
5m Five minute load average. Double
15m Fifteen minute load average. Double

 B.2.4. agent.cpu

 Summary

The agent.cpu check will attempt to measure the usage of the CPU on a host.

Table B.28. Attributes
FieldDescriptionValidation
No fields are present for this particular check type.
Table B.29. Metrics
MetricDescriptionType
idle_percent_averageRecent percentage of CPU time spent idle.Double
irq_percent_averageRecent percentage of CPU time spent handling hardware interrupts.Double
max_cpu_usageRecent percentage utilization of the most-utilized CPU. This is useful to detect when some CPUs are "pegged" while others are idle.Double
min_cpu_usageRecent percentage utilization of the least-utilized CPU. This is useful to detect when some CPUs are "pegged" while others are idle.Double
stolen_percent_averageRecent percentage of CPU time spent waiting for the CPU to service other virtual CPUs.Double
sys_percent_averageRecent percentage of CPU time utilized by kernel mode processes.Double
usage_averageRecent percentage of CPU time utilized by all processes.Double
user_percent_averageRecent percentage of CPU time utilized by user mode processes.Double
wait_percent_averageRecent percentage of CPU time utilized by processes in a "wait" state.Double

 B.2.5. agent.disk

 Summary

The agent.disk check exposes disk related metrics (service time, wait time, etc.).

Table B.30. Attributes
FieldDescriptionValidation
target The disk to check (eg '/dev/xvda1')
  • String between 1 and 512 characters long

Table B.31. Metrics
MetricDescriptionType
queueDisk utilization time, the prefix / will change dependending on the mount points discovered.Int64
read_bytesThe number of physical disk bytes read, the prefix / will change dependending on the mount points discovered.Int64
readsThe number of physical disk reads, the prefix / will change dependending on the mount points discovered.Int64
rtimeThe amount of time spent reading, the prefix / will change dependending on the mount points discovered.Int64
service_timeREMOVEInt64
timeREMOVEInt64
write_bytesThe number of physical disk bytes written, the prefix / will change dependending on the mount points discovered.Int64
writesThe number of physical disk writes, the prefix / will change dependending on the mount points discovered.Int64
wtimeThe amount of time spent writing, the prefix / will change dependending on the mount points discovered.Int64

 B.2.6. agent.network

 Summary

The agent.network check will attempt to measure the usage of network devices on a host.

Table B.32. Attributes
FieldDescriptionValidation
target The network device to check (eg 'eth0')
  • String between 1 and 512 characters long

Table B.33. Metrics
MetricDescriptionType
rx_bytesThe number of bytes received over the interface.Int64
rx_droppedThe number of packets received and subsequently dropped over the interface.Int64
rx_errorsThe number of errors received over the interface.Int64
rx_packetsThe number of packets received over the interface.Int64
speedNo description is available at the moment.Int64
tx_bytesThe number of bytes transmitted over the interface.Int64
tx_droppedThe number of packets ateempted transmitting and subsequently dropped over the interface.Int64
tx_errorsThe number of errors while transmitting over the interface.Int64
tx_packetsThe number of packets transmitted over the interface.Int64

 B.2.7. agent.windows_perfos

 Summary

The agent.windows_perfos check will return metrics regarding windows performance data.

Table B.34. Attributes
FieldDescriptionValidation
No fields are present for this particular check type.
Table B.35. Metrics
MetricDescriptionType
AlignmentFixupsPersecAlignment Fixups/sec - Shows the rate, in incidents per second, at which alignment faults were fixed by the system.Uint32
ContextSwitchesPersecContext Switches/sec - Shows the combined rate, in incidents per second, at which all processors on the computer were switched from one thread to another. It is the sum of the values of Thread Context Switches/sec for each thread running on all processors on the computer, and is measured in numbers of switches. Context switches occur when a running thread voluntarily relinquishes the processor, or is preempted by a higher priority, ready thread.Uint32
ExceptionDispatchesPersecException Dispatches/sec - Shows the rate, in incidents per second, at which exceptions were dispatched by the system.Uint32
FileControlBytesPersecFile Control Bytes/sec - Shows the overall rate, in incidents per second, at which bytes were transferred for all file system operations that were neither read nor write operations, such as file system control requests and requests for information about device characteristics or status.Uint64
FileControlOperationsPersecFile Control Operations/sec - Shows the combined rate, in incidents per second, of file system operations that were neither read nor write operations, such as file system control requests and requests for information about device characteristics or status. This is the inverse of File Data Operations/sec.Uint32
FileDataOperationsPersecFile Data Operations/sec - Shows the combined rate, in incidents per second, of read and write operations on disks, serial, or parallel devices. This is the inverse of File Control Operations/sec.Uint32
FileReadBytesPersecFile Read Bytes/sec - Shows the overall rate, in incidents per second, at which bytes were read to satisfy file system read requests to all devices on the computer, including read operations from the file system cache.Uint64
FileReadOperationsPersecFile Read Operations/sec - Shows the combined rate, in incidents per second, of file system read requests to all devices on the computer, including requests to read from the file system cache.Uint32
FileWriteBytesPersecFile Write Bytes/sec - Shows the overall rate, in incidents per second, at which bytes were written to satisfy file system write requests to all devices on the computer, including write operations to the file system cache.Uint64
FileWriteOperationsPersecFile Write Operations/sec - Shows the combined rate, in incidents per second, of file system write requests to all devices on the computer, including requests to write to data in the file system cache.Uint32
FloatingEmulationsPersecFloating Emulations/sec - Shows the rate, in incidents per second, of floating emulations performed by the system.Uint32
PercentRegistryQuotaInUsePercentage of the total registry quota allowed that is currently being used by the system. This property displays the current percentage value only; it is not an average.Uint32
ProcessesShows the number of processes in the computer at the time of data collection. This is an instantaneous count, not an average over the time interval. Each process represents a program that is running.Uint32
ProcessorQueueLengthProcessor Queue Length - Shows the number of threads in the processor queue. Unlike the disk counters, this counter shows ready threads only, not threads that are running. There is a single queue for processor time, even on computers with multiple processors. Therefore, if a computer has multiple processors, you need to divide this value by the number of processors servicing the workload. A sustained processor queue of greater than two threads generally indicates processor congestion.Uint32
SystemCallsPersecSystem Calls/sec - Shows the combined rate, in incidents per second, of calls to operating system service routines by all processes running on the computer. These routines perform all of the basic scheduling and synchronization of activities on the computer, and provide access to nongraphic devices, memory management, and name space management.Uint32
SystemUpTimeSystem Up Time - Shows the total time, in seconds, that the computer has been operational since it was last started.Uint64
ThreadsShows the number of threads in the computer at the time of data collection. This is an instantaneous count, not an average over the time interval. A thread is the basic executable entity that can execute instructions in a processor.Uint32

 B.2.8. agent.plugin

 Summary

The agent.plugin check will attempt to run a custom plugin on a host.

 Installing Custom Plugins

Custom plugins are simply executable files which report metrics via stdout. Plugins are placed on the server to be monitored at an installation path that depends on the operating system:

Operating System Installation Path
Linux /usr/lib/rackspace-monitoring-agent/plugins/
Windows (32-bit agent installed on a 64-bit system ) C:\Program Files (x86)\Rackspace Monitoring\plugins
Windows (64-bit agent installed on a 64-bit system or 32-bit agent installed on a 32-bit system) C:\Program Files\Rackspace Monitoring\plugins

Once the plugin has been installed to the server, create an agent.plugin check that specifies the name of the executable file, and the plugin will begin reporting metrics to the monitoring system, just like any other check. If the plugin requires any command line arguments, these may be specified using the optional args array.

Table B.36. Attributes
FieldDescriptionValidation
file Name of the plugin file
  • String matching the regex //[a-zA-Z0-9\.\-_]+//

args Command-line arguments which are passed to the plugin
  • Optional

  • Array [Non-empty string]

  • Array or object with number of items between 0 and 10

timeout Plugin execution timeout in milliseconds
  • Optional

  • Integer

Table B.37. Metrics
MetricDescriptionType
Available metrics are determined by the plugin.

 Community Plugin Repository

A curated repository of plugins created by Cloud Monitoring users is avaliable on GitHub. Contributions are welcome!

[Note]Note

The Cloud Monitoring Agent is also capable of executing Cloudkick plugins, so if you are a Cloudkick user you can just drop in any existing plugin and it should just work.

 Creating Custom Plugins

Creating custom plugins is as simple as writing a script that prints a status and up to 10 metrics to standard out. The format of the status line is:

status <status>

The status string should describe whether the check was able to successfully gather metrics. It could be as simple as "success" to incidate that metrics were successfully gathered. When an error occurs that prevents metrics from being gathered, plugins should print a status that describes the error, then should exit non-zero without printing any metric lines.

The status line may be followed by up to 10 metric lines. The format of a metric line is:

metric <name> <type> <value>

where:

name

is the name of the metric. No spaces are allowed. Example: memory_free.

type

is the type of the metric. This must be one of:

int32

Signed 32 bit integer value.

uint32

Unsigned 32 bit integer value.

int64

Signed 64 bit integer value.

uint64

Unsigned 64 bit integer value.

double

Floating point values.

string

A string value.Note: the monitoring system records string metrics every time they change. String metrics are designed for recording an enumerated state which infrequently changes (for example an HTTP response code which is always 200 during normal operation). You should not store arbitrary, frequently changing values in a string metric.

value

is the value of the metric.

Putting it all together, the output of a plugin that has successfully executed might look something like:

status Turkey thermometer returned valid response
metric internal_temperature uint32 165
metric ambient_temperature uint32 325

If the plugin failed, it might print the following before exiting non-zero:

status Turkey thermometer not responding


loading table of contents...