Monitor Types¶

agent.cpu.cpuUsage¶

CPU utilisation data

The utilisation data is calculated as a rolling average (over a 1 minute period on UNIX platforms and a 10 second period on Windows platforms).

Parameters¶

cpu (int)

Optional (default: -1). Identifier of which CPU to monitor

Specifying a cpu parameter value of -1 will create facet values that represent overall CPU and only create a single sample per period. Specifying a cpu parameter value of -2 will monitor each CPU individually and create a sample per period per CPU core. Specifying a cpu parameter of zero or above will be interpreted as the ID of the processor to monitor (e.g. for a 4-CPU machine a value of 0, 1, 2 or 3 would be valid). Note if the ID specified is not a valid processor ID the monitor will not be created.

Notes¶

On hosts with multiple CPUs the value of the facets depends on the cpu parameter. As described above a value of -1 creates a single sample per period. Each facet value represents the overall cpu usage for all detected CPUs. For example percentTotal will represent the sum of cpu utilisation for all CPUs, divided by the number of CPUs. Therefore, if on a 4-CPU system each CPU was 100% utilised the percentTotal facet would equal (4 * 100%) / 4, i.e 100%. Note that the sample sub-id on these samples will be the string “total”.

A cpu parameter value of -2 creates a single sample per CPU per period. Therefore on a 4-CPU system each, 4 samples would be created per monitor period. For each sample created the facet values represent the utilisation of a single CPU. Therefore if a single CPU on a 4-CPU system was 100% utilised the related sample’s percentTotal facet would equal 100% and the percentIdle facet would equal 0%. Note that the sample sub-id on these samples will be the CPU ID (e.g. 0, 1, 2 or 3 on a 4-CPU host).

A cpu parameter value that is a CPU ID (e.g. 3) creates a single sample per monitor period. The facet values are as described above, but a sample is created for only the specified CPU. The sample sub-id on the sample will be the same as the specified CPU ID.

In general percentUser + percentSys equals percentTotal while percentTotal + percentIdle will equate to 100%.

However, this may not always be the case due to rounding. Furthermore it is possible for a CPU facet to be more than 100% on some machines. E.g. on AIX LPARs a partition might be allowed to steal CPU time from other idle domains, likewise it might donate CPU resulting in idle time higher than 100%.

agent.cpu.loadAvg¶

Load average data

The load average monitor is not supported on Windows platforms.

Parameters¶

None

Facets¶

one (float)

Performance metric type: gauge

One minute load average

five (float)

Performance metric type: gauge

Five minute load average

fifteen (float)

Performance metric type: gauge

Fifteen minute load average

agent.disk.diskIO¶

Disk utilisation data

Note

This monitor is not available on: OS X, AIX, Solaris 11 (SPARC and x86) or branded Solaris 10 zones running Solaris 11.

Parameters¶

devid (string)

Optional. The device ID, e.g. sda1 or dm-0.

Either this parameter or the regex parameter must be present.

regex (regex)

Optional. Regular expression the device ID must match

Using this parameter rather than the devid parameter allows you to select more than one device.

match_multiple (bool)

Optional (default: true). Whether the regex parameter can match multiple devices

When this is set to true all devices matched by the regex parameter are monitored and differentiated using sample sub IDs. This will also scan for devices on each sample run and thus will detect new devices dynamically.

When setting this to false only one device will be monitored, if the regex parameter matches multiple devices one will be picked and an warning logged. In this case the device must be present when the monitor starts and asagent will not scan for new devices at runtime.

Facets¶

diskId (string): Disk identifier/name

bytesRead (int)

Performance metric type: counter

Number of bytes read from this device

bytesWritten (int)

Performance metric type: counter

Number of bytes written to this device

readCount (int)

Performance metric type: counter

Number of reads made from this device

writeCount (int)

Performance metric type: counter

Number of writes made to this device

agent.disk.diskUsage¶

Disk device usage data

Parameters¶

device (string)

Optional. Name of the mount point, e.g. /home

Either this parameter or the regex parameter must be present.

regex (regex)

Optional. Name of the mount point, e.g. /home

This is a regular expression to match the disk. If match_multiple is set to true then multiple disks will be monitored if they all match. In this case asagent will also scan for new disks automatically on each sample run dealing with hotplugging by adding and removing disks as required.

Either this parameter or the device parameter must be present.

local (bool)

Optional (default: true). Whether to only consider local disks or not

When set to true the diskUsage monitor will only scan for local disks when looking for the matching mount point. This can be useful to avoid potentially long timeouts and errors if a networked disk is not reachable.

match_multiple (bool)

Optional (default: true). Whether the regex parameter can match multiple disks

If multiple disk can be matched asagent will scan for new disk automatically on each sample run dealing with hotplugging by adding and removing disks as required. This is slightly more resource intensive than monitoring just one disk.

Facets¶

percentUsed (float)

Performance metric type: gauge

Percentage space used

percentFree (float)

Performance metric type: gauge

Percentage space free

This is the also known as the “available” space, i.e. the space still available to non-privileged users.

bytesUsed (int)

Performance metric type: gauge

Used space in bytes

bytesFree (int)

Performance metric type: gauge

Free space in bytes

This is the also known as the “available” space, i.e. the space still available to non-privileged users.

bytesTotal (int)

Performance metric type: none

Total bytes on device

diskId (string): Disk identifier

volumeName (string): Volume name or mountpoint

dfPercentUsed (int)

Performance metric type: gauge

Space usage calculated like df does

Percentage space used calculated in a similar manner to the UNIX df command. This is not the actual usage but a more conservative appoximation. See the Single UNIX Specification for details.

Note

Not available on Windows platforms

agent.mem.bufferCache¶

Gets buffers and cache data

Note

This monitor is not available on Solaris and OS X

Parameters¶

None

Facets¶

bytes (int)

Performance metric type: gauge

Bytes used for disk caching

On Windows platforms this facet does not include bytes buffered, only cache.

percentOfTotal (float)

Performance metric type: gauge

Percentage of total memory used for the buffercache

agent.mem.memUsage¶

Gets memory utilisation data

Parameters¶

None

Facets¶

percentUsed (float)

Performance metric type: gauge

Percentage of used memory

percentFree (float)

Performance metric type: gauge

Percentage of free memory

bytesUsed (int)

Performance metric type: gauge

Bytes of used memory

bytesFree (int)

Performance metric type: gauge

Bytes of free memory

bytesTotal (int)

Performance metric type: none

Total available memory in bytes

agent.mem.swapUsage¶

Gets swap space usage data

Parameters¶

None

Facets¶

percentUsed (float)

Performance metric type: gauge

Percentage of used swap space

percentFree (float)

Performance metric type: gauge

Percentage of free swap space

bytesUsed (int)

Performance metric type: gauge

Used swap space in bytes

bytesFree (int)

Performance metric type: gauge

Free swap space in bytes

bytesTotal (int)

Performance metric type: none

Total size of swap space

bytesAvail (int)

Performance metric type: gauge

Available swap space (swap+memory) in bytes

Note

This is not available on Windows or OSX.

bytesTaskManager (int)

Performance metric type: gauge

PageFile usage as reported by the Windows Task Manger

The Windows Task Manger reports PageFile usage in a different manner, this facet represents that value.

Note

Only available on Windows.

agent.mon.dbMonitor¶

Database Monitoring Sampler

This sampler provides a database monitoring facility. Given the relevant connection info and (optionally) a query to perform the sampler will record database connection alive-ness, query response times, row counts (for specified query) and limited row data.

Parameters¶

flavour (string)

Flavour of database to connect to

Valid flavours are: SYBASE, ORACLE, DB2, POSTGRESQL, MYSQL. On Windows there is also an ADO flavour which supports monitoring of any ADO supported database like SQL Server, Oracle, DB2, Sybase, PostgreSQL, MySQL etc.

Monitoring of some database flavours may require additional packages to be installed alongside the agent. See Installing Database Extensions.

database (string)

Optional. Database name

The semantics and optionality of this parameter is flavour specific. See the notes on the flavours below for details.

connStr (string)

Optional. Connection string to the database, flavour specific

In general either this parameter or all of the database, usr and pwd parameters are required (and mutually exclusive).

usr (string): Optional. Database username, flavour specific

pwd (string): Optional. Database password, flavour specific

query (string)

Optional. Query to perform

If no query is specified only database availability will be tested.

numRows (int)

Optional (default: 0). Maximum number of rows returned

Number of result rows to be returned as sample facets when query is specified. Each row returned from the query is added as a sample facet with a facet ID of rowN where N is a zero-based counter. The facet value is a comma-separated representation of the row data’s attributes. If not specified, 0 is assumed. Values greater than 100 are ignored and a value of 100 inferred.

samplePerRow (bool)

Optional (default: false). Create a new sample for each database row

When query is specified, numRows is greater than 0 and this parameter is “true” then a sample is created per returned row with a single facet called row.

sybaseDtFmt (string)

Optional (default: auto). Sybase specific: date time format

SYBASE flavour only. Tells adapter how to interpret time data. Valid values for this parameter are: auto, sybase, mx, python.

alivenessSQL (string)

Optional. Specifies SQL used for database aliveness checks

This is a mandatory parameter for the ADO and SYBASE flavours.

Facets¶

alive (bool)

Performance metric type: twgauge

True if login and aliveness test succeed

responseTime (int)

Performance metric type: gauge

Response time in miliseconds for query

Time in miliseconds it took to execute the query specified in the query parameter. Only available if a valid query is specified.

checkResponseTime (int)

Performance metric type: gauge

Response time in miliseconds for aliveness test

rowN ()

Dynamic facet name, regex=/row[0-9]+/

One row of returned data

For each row of data resulting from the query parameter a facet is created containing the comma-separated representation of the row. N is zero-based. If numRows is 0 or the samplePerRow parameter is enabled these facets are not created.

row ()

Comma-separated representation of data

When the samplePerRow parameter is enabled and data was returned by the query each sample will have this facet, containing the comma-separated representation of the row data.

errorInfo (string): Indicates query failure

Notes¶

This section details the various database flavours and how the MA Database Monitor should be used with them. Also, each section describes the aliveness checks performed.

As a general note, make sure query parameters are escaped or within CDATA blocks as follows:

<Parameter name="query">
<![CDATA[
select * from DEPARTMENTS where department_id < 100
]]>
</Parameter>

<Parameter name="query">
select * from DEPARTMENTS where department_id < 100
</Parameter>

Oracle Flavour¶

Note

This flavour is not currently available on Solaris 11 SPARC and x86.

Aliveness-Test¶

select 2+2 "abilisoft" ,3*3 from dual

Configuration¶

You may specify connection parameters for <usr>, <pwd> and <database> or a <connStr>.

Defining a Monitor¶

Define an Oracle monitor in one of the following ways:

<Monitor name="oraMonitor" type="agent.mon.dbMonitor" periodicity="10">
  <Parameter name="flavour">ORACLE</Parameter>
  <Parameter name="usr">hr</Parameter>
  <Parameter name="pwd">hr</Parameter>
  <Parameter name="database">xe</Parameter>
</Monitor>

<Monitor name="oraMonitor" type="agent.mon.dbMonitor" periodicity="10">
  <Parameter name="flavour">ORACLE</Parameter>
  <Parameter name="connStr">hr/hr@xe</Parameter>
</Monitor>

The example above shows a connection string short-hand because the Oracle service is on the local host. When connecting to an Oracle instance on a remote host, the host should be specified in the connStr parameter is as follows:

user/password@host:port/service-name

When using Oracle connection string naming methods which require configuration files, like TNSNAMES, then the TNS_ADMIN environment variable needs to be used to point to the directory with these configuration files in it. If TNS_ADMIN is not set but ORACLE_HOME is then the configuration files are searched for in $ORACLE_HOME/network/admin.

Stored Procedures and Functions¶

The invocation of stored procedures is not currently supported by the Oracle flavour. The invocation of stored functions is supported in the context of a traditional query.

Sybase Flavour¶

Aliveness-Test¶

As specified in alivenessSQL parameter

Configuration¶

You may only specify connection parameters for <usr>, <pwd> and <database> (<connStr> is not supported). <sybaseDtFmt> tells the Sybase connection how to handle date/time data. Valid values are auto (default), sybase, mx, and python.

The Sybase Database monitor utilises a configuration file (called freetds.conf) that specifies the data source attributes and other possible connection parameters.

The Agent’s Sybase runtime uses a configuration file that is shipped in /opt/abilisoft.com/thirdparty/freetds/etc/freetds.conf. This contains example Sybase server entries. You must update this configuration to match the database parameter used in any database monitor that you specify that uses the Sybase flavour. You must also update the host and port values to match those of the Sybase server you want to connect to. Updating the TDS version is inadvisable.

[global]
  tds version = 5.0
  timeout = 10
  connect timeout = 10

# Test Sybase server
[MYSYBASE]
  host = testvm-xp
  port = 5000
  tds version = 5.0

Other points to note:

Only set initial block size setting when connecting to Netcool Object Servers (a Sybase derivative). Remove the setting for any other Sybase connection. If you want the agent to monitor both Sybase Adaptive Servers and Netcool Object Servers put initial block size in the relevant server sections, NOT in the [global] section.
To prevent the agent from hanging when connecting to a non-existent or unavailable database, set timeout and connect timeout settings accordingly (e.g. 10 seconds).

Troubleshooting¶

You can start freetds logging by exporting the following environment variables before running the agent (obviously with a manifest that includes your Sybase database monitoring configuration):

EXPORT TDSDUMPCONFIG=/tmp/freetdsconfig.log
EXPORT TDSDUMP=/tmp/freetds.log

This will cause the agent to dump configuration and log connection progress respectively. The TDSDUMPCONFIG log is often the most revealing as logs where it searched for the database reference, where it found it and what host and port it tried to connect to. The TDSDUMP log shows the result of the connection and provides an insight into how far the agent is getting with the Sybase connection attempt.

Defining a Monitor¶

Define a Sybase monitor as follows:

<Monitor name="sybMonitor" type="agent.mon.dbMonitor" periodicity="30">
  <Parameter name="flavour">SYBASE</Parameter>
  <Parameter name="usr">admin</Parameter>
  <Parameter name="pwd">secret</Parameter>
  <Parameter name="database">MYSYBASE</Parameter>
  <Parameter name="query">select count(*) from people</Parameter>
  <Parameter name="numRows">10</Parameter>
  <Parameter name="alivenessSQL">select * from people</Parameter>
</Monitor>

Note that:

When you specify the database parameter you don’t specify a host or port, these values are obtained from the freetds.conf file, the database parameter is a reference to an entry in freetds.conf.
Sybase doesn’t use the connStr parameter; only ever use usr, pwd and database to specify the connection parameters.
You must provide the alivenessSQL parameter. The SYBASE flavour can be used to connect to various Sybase based products (SQL Server, Netcool etc) and they have various default stored procedures. As an example, set this to be a query against a system table like sysusers. Contact your Sybase DBA for further guidance on a useful aliveness test query.

Stored Procedures and Functions¶

The invocation of stored procedures and functions is generally supported by the Sybase flavour. One specific caveat is that the invocation of a stored procedure that has one or more out parameters is not currently supported. Note that this caveat should not be confused with stored procedures that return result sets or stored functions that return values; these are supported. Stored procedures and functions are invoked by setting the query parameter appropriately.

Stored Procedure Examples Here is an example of a parameter-less stored procedure call:

<Parameter name="query">sp_spaceused</Parameter>

This will give rise to a row0 facet value as follows:

master, 26.0 MB

Some stored procedure calls require parameters:

<Parameter name="query">sp_help sysobjects</Parameter>

This will give rise to a row0 facet value as follows:

sysobjects, dbo, system table, -- none --, Sep  2 2010  2:32PM

As one can see, the parameter to the stored procedure sp_help does not require quotes. However, sometimes a parameter value has spaces and one needs to distinguish the parameter(s) from the procedure or function name:

<Parameter name="query">sp_monitorconfig 'number of user connections'</Parameter>

Elicits:

number of user connection, 21, 4, 16.00, 6, 0, None

Stored Function Example Consider the following simple stored function definition:

create function xp_echo(@param1 varchar(255))
returns varchar(255)
as
begin
  declare @result varchar(255)
  set @result='SYB_SERVER.' + @param1
  return @result
end

A simple test using the query parameter as follows:

<Parameter name="query">select dbo.xp_echo("test")</Parameter>

Note that the database owner may need to be specified (‘dbo’ in this example). This would (normally, depending on the database configuration) give rise to a row0 value as follows:

row0: 'SYB_SERVER.test'

Here is a more realistic query parameter:

<Parameter name="query">select dbo.xp_echo(name) from sysobjects
                              where name like '%remote%'</Parameter>

This would (normally, depending on the database configuration) give rise to row0, row1 and row2 facet values as follows:

row0: 'SYB_SERVER.sp_check_remote_tempdb'
row1: 'SYB_SERVER.sp_remotesql'
row2: 'SYB_SERVER.sysremotelogins'

PostgreSQL Flavour¶

Aliveness-Test¶

select 2+2 "abilisoft" ,3*3 from dual

Configuration¶

You may only specify a connection string parameter <connStr> which includes the host and port, database, username and password. No other configuration required.

Defining a Monitor¶

A postgreSQL monitor can be defined as follows:

<Monitor name="pgMonitor" type="agent.mon.dbMonitor" periodicity="30">
  <Parameter name="flavour">POSTGRESQL</Parameter>
  <Parameter name="connStr">dbname=training
                            user=flub
                            password=%(training@localhost)s
                            host=localhost"</Parameter>
  <Parameter name="query">select count(*) from people</Parameter>
  <Parameter name="numRows">10</Parameter>
</Monitor>

Stored Procedures and Functions¶

The invocation of stored procedures is not currently supported by the PostgreSQL flavour. The invocation of stored functions is supported in the context of a traditional query.

DB2 Flavour¶

Aliveness-Test¶

select current date from sysibm.sysdummy1

Configuration¶

You may only specify connection parameters for <usr>, <pwd> and <database> (<connStr> is not supported). The <database> parameter specifies a Data Source Name (DSN) which is usually the database name. No other configuration required.

Defining a Monitor¶

A DB2 monitor can be defined as follows:

<Monitor name="db2Monitor" type="agent.mon.dbMonitor" periodicity="30">
  <Parameter name="flavour">DB2</Parameter>
  <Parameter name="usr">db2admin</Parameter>
  <Parameter name="pwd">db2admin</Parameter>
  <Parameter name="database">SAMPLE</Parameter>
  <Parameter name="query">select * from DAVEC.DEPARTMENT</Parameter>
  <Parameter name="numRows">20</Parameter>
</Monitor>

Stored Procedures and Functions¶

The invocation of stored procedures is not currently supported by the DB2 flavour. The invocation of stored functions is supported in the context of a traditional query.

ADO Flavour¶

Aliveness-Test¶

As specified in alivenessSQL parameter.

Specifying ADO as the database flavour is only permissible when the agent is running on Windows platforms. Using the ADO flavour will allow the monitor to connect to the chosen database via the Microsoft ADO API. This enables one to connect to a wide range of database flavours. Note that the database to be monitored does not need to be on the same platform as the agent. Some of the databases that can be monitored using this flavour are:

Microsoft SQL Server
Microsoft Access
Oracle
MySQL
PostgreSQL
Sybase
Firebird
Interbase
DB2

Furthermore, given the appropriate connection string the ADO Database Monitor can be used to monitor XML, folders on disk, Microsoft Excel and Microsoft Outlook.

Configuration¶

You may only specify a connection parameter for <connStr>. The connection string depends largely on the database you are connecting to and the OLE driver you want ADO to use.

Defining a Monitor¶

Here are some examples of defining a monitor using the ADO flavour:

SQL Server using OLEDB

<Monitor name="sqlSvrMonitor" type="agent.mon.dbMonitor">
  <Parameter name="flavour">ADO</Parameter>
  <Parameter name="connStr">Provider=SQLOLEDB.1;
                            Data Source=192.168.1.100;
                            Uid=username;
                            Pwd=password;
                            Database=dbname;
  </Parameter>
</Monitor>

MySQL using ODBC

<Monitor name="mySQLMonitor" type="agent.mon.dbMonitor">
  <Parameter name="flavour">ADO</Parameter>
  <Parameter name="connStr">Driver={MySQL ODBC 3.51 Driver};
                            Server=192.168.1.100;
                            Port=3306;
                            User=username;
                            Password=password;
                           Database=mydatabase;
  </Parameter>
</Monitor>

Excel Spreadsheet using OLEDB

<Monitor name="excelMonitor" type="agent.mon.dbMonitor">
  <Parameter name="flavour">ADO</Parameter>
  <Parameter name="connStr">Provider=Microsoft.Jet.OLEDB.4.0;
                            Data Source=C:\Path\To\sheet.xls;
  </Parameter>
</Monitor>

Oracle using OLEDB

<Monitor name="oraMonitor" type="agent.mon.dbMonitor">
  <Parameter name="flavour">ADO</Parameter>
  <Parameter name="connStr">Provider=OraOLEDB.Oracle;
                            Data Source=xe;
                            User Id=hr;
                            Password=hr;
  </Parameter>
</Monitor>

Stored Procedures and Functions¶

The invocation of stored procedures is not currently supported by the ADO flavour. The invocation of stored functions is supported in the context of a traditional query.

agent.mon.dirMonitor¶

Monitors a directory

This sampler will monitor a directory and allows one to notice any changes made to any files in it. It does this by taking checksum of all the stat structures from the files in the directory.

To use this declare a sample like this in the manifest:

<Monitor name="postfixConf"
            type="agent.mon.dirMonitor"
            periodicity="1800">
  <Parameter name="path">/etc/postfix</Parameter>
</Monitor>
<Monitor name="postfixConfSasl"
            type="agent.mon.dirMonitor"
            periodicity="1800">
  <Parameter name="path">/etc/postfix/sasl</Parameter>
</Monitor>

Parameters¶

path (string): Directory path

Facets¶

fileCount (int)

Performance metric type: gauge

Number of files in the directory

size (int)

Performance metric type: gauge

The space occupied by the directory in bytes

The size of a subdirectory will not he the size of it’s contents but only the size of it’s inode listings taken on the filesystem (and thus will be multiples of the blocksize).

checksum (string)

Checksum of the directory contents

This can be used to notice any changes in the directory. Note that this includes the modification times of all file objects, including directories.

mode (string): Octal representation of the directory permissions

agent.mon.esxFolderMonitor¶

Monitor VMWare ESX folders

This monitor logs into the ESX VI API and looks up the specified folder Managed Object. It retrieves the “configStatus” and “overallStatus” of the folder. The intention is that the user will configure control actions to switch-on relevant esxHostMonitors (or esxVmMonitors if we implement it) that pertain to the monitored folder. When the state reverts to green one could switch that monitoring off again.

To use, declare a monitor like this in the manifest (last two parameters are optional):

<Monitor name="esxDataCenter" type="agent.mon.esxFolderMonitor">
  <Parameter name="server">eris</Parameter>
  <Parameter name="folder">ha-datacenter</Parameter>
  <Parameter name="usr">root</Parameter>
  <Parameter name="pwd">secret</Parameter>
  <Parameter name="realm">Custom Realm</Parameter>
  <Parameter name="authType">basic</Parameter>
</Monitor>

Parameters¶

server (string): ESX Server or Virtual Centre hostname, FQDN or IP address

folder (string)

Folder to be monitored

This can be any managed object that is a Folder Type (e.g. DataCenter or VM folder).

usr (string)

Session username

By default ESX credentials are the root username and password

pwd (string): Session password

realm (string): Optional (default: VMware VI SDK Browser). Authentication realm

authType (string)

Optional (default: basic). Authentication type

If the ESX service has been configured with a different authentication type, specify it here. Valid values are basic and digest.

Facets¶

available (bool)

Performance metric type: twgauge

Whether the data was obtained or not

errorInfo (string): Error message if there were issues getting the data

responseTime (int)

Performance metric type: gauge

Response time of the call to the service

configStatus (string)

VMWare configuration status of the folder

“green”, “yellow”, “red”, “gray” or “unknown”. Value is set to “unknown” if the monitor cannot extract the required data.

overallStatus (string)

VMWare overall status of the folder

“green”, “yellow”, “red”, “gray” or “unknown”. Value is set to “unknown” if the monitor cannot extract the required data.

agent.mon.esxHostInfoMonitor¶

VMWare ESX host info monitor

This monitor logs into the ESX VI API and looks up the specified host resource Managed Object. It retrieves basic (static) ESX host information.

To use, declare a monitor like this in the manifest (last two parameters are optional):

<Monitor name="esxHostInfo" type="agent.mon.esxHostInfoMonitor">
  <Parameter name="server">eris</Parameter>
  <Parameter name="hostname">ha-host</Parameter>
  <Parameter name="usr">root</Parameter>
  <Parameter name="pwd">secret</Parameter>
  <Parameter name="realm">Custom Realm</Parameter>
  <Parameter name="authType">basic</Parameter>
</Monitor>

Parameters¶

server (string): ESX Server or Virtual Centre hostname, FQDN or IP address

usr (string)

Session username

By default ESX credentials are the root username and password

pwd (string): Session password

realm (string): Optional (default: VMware VI SDK Browser). Authentication realm

authType (string)

Optional (default: basic). Authentication type

If the ESX service has been configured with a different authentication type, specify it here. Valid values are basic and digest.

Facets¶

available (bool)

Performance metric type: twgauge

Whether service data was obtained or not

errorInfo (string): Error message if there where issues getting the data

responseTime (int)

Performance metric type: gauge

Response time of the call to the service

product (string): E.g. “VMWare ESX Server 3i 3.5.0 build-123629”

osType (string): E.g. “vmnix-x86”

apiVersion (string): VI-API version, e.g. “2.5u2”

vendor (string): Hardware vendor

model (string): Hardware Model

cpuModel (string): Hardware CPU Model

cpuSpeedGHz (float)

Performance metric type: none

Hardware CPU Speed in GHz

numCpuCores (int)

Performance metric type: none

Number of hardware CPU Cores

numCpuThreads (int)

Performance metric type: none

Number of hardware CPU threads

numNics (int)

Performance metric type: none

Number of Network Interfaces

numHBAs (int)

Performance metric type: none

Number of Host Bus Adaptors

agent.mon.esxHostMonitor¶

VMWare ESX host runtime information

This monitor logs into the ESX VI API and looks up the specified host Managed Object. It retrieves ESX host runtime information.

To use, declare a monitor like this in the manifest (vmstats, dsstats, nicstats, realm and authType are optional):

<Monitor name="esxHostMon" type="agent.mon.esxHostMonitor">
  <Parameter name="server">eris</Parameter>
  <Parameter name="hostname">ha-host</Parameter>
  <Parameter name="usr">root</Parameter>
  <Parameter name="pwd">secret</Parameter>
  <Parameter name="vmstats">true</Parameter>
  <Parameter name="dsstats">true</Parameter>
  <Parameter name="nicstats">true</Parameter>
  <Parameter name="realm">Custom Realm</Parameter>
  <Parameter name="authType">basic</Parameter>
</Monitor>

Parameters¶

server (string): ESX Server or Virtual Centre hostname, FQDN or IP address

hostname (string): ESX Name of the host in the data centre monitored

usr (string)

Session username

By default ESX credentials are the root username and password

pwd (string): Session password

vmstats (bool): Optional (default: false). Whether to gather information about VMs

dsstats (bool): Optional (default: false). Whether to gather information about Data Stores

nicstats (bool): Optional. Whether to gather information about network interfaces

realm (string): Optional (default: VMware VI SDK Browser). Authentication realm

authType (string)

Optional (default: basic). Authentication type

If the ESX service has been configured with a different authentication type, specify it here. Valid values are basic and digest.

Facets¶

available (bool)

Performance metric type: twgauge

True if the server specified is available

errorInfo (string): Error message if there were issues getting the service status

responseTime (int)

Performance metric type: gauge

Response time of the call to the service

connectionState (string): String representing the host connection state

powerState (string): String representing the host power-on state

inMaintenanceMode (bool)

Performance metric type: twgauge

Maintenance mode flag

bootTime (string)

Performance metric type: none

Boot time timestamp

rebootRequired (bool)

Performance metric type: none

True if the host requires a reboot

configStatus (string)

VMWare configuration status

green, yellow, red, or unknown. Value is set to unknown if monitor cannot extract the required data.

overallStatus (string)

VMWare overall status

green, yellow, red, or unknown. Value is set to unknown if monitor cannot extract the required data.

cpuPct (float)

Performance metric type: gauge

Host CPU usage as a percentage

cpuMhz (int)

Performance metric type: none

Host CPU usage in MHz

memTotal (int)

Performance metric type: none

Host total memory in bytes

memUsed (int)

Performance metric type: gauge

Host used memory in bytes

numVms (int)

Performance metric type: gauge

Number of VMs guested on this host

Facet only available if vmstats is true

nonGreenCfgVms (string)

List of VM on this host with non-green configStatus

Facet only available if vmstats is true

nonGreenOverallVms (string)

List of VMs on this host with non-green overallStatus

Facet only available if vmstats is true

numDs (int)

Performance metric type: gauge

Number of configured datastores on this host

Facet only available if dsstats is true

numDsAccessible (int)

Performance metric type: gauge

Number of datastores marked as accessible

Facet only available if dsstats is true

ds_access_NAME (bool)

Performance metric type: twgauge

Dynamic facet name, regex=/ds_access_\w+/

True if datastore NAME is accessible

Facet only available if dsstats is true

ds_location_NAME (string)

Dynamic facet name, regex=/ds_location_\w+/

URL of the datastore NAME

Facet only available if dsstats is true

ds_capacity_NAME (int)

Performance metric type: gauge

Dynamic facet name, regex=/ds_capacity_\w+/

Total capacity (bytes) of the datastore NAME

Facet only available if dsstats is true

ds_free_NAME (int)

Performance metric type: gauge

Dynamic facet name, regex=/ds_free_\w+/

Free capacity (bytes) of the datastore NAME

Facet only available if dsstats is true

numNics (int)

Performance metric type: none

Number of physical network interfaces found for this host

Facet only available if nicstats is true

nic_speed_NAME (int)

Performance metric type: none

Dynamic facet name, regex=/nic_speed_\w+/

The speed of the NIC NAME (e.g. 10/100/1000)

Facet only available if nicstats is true

nic_duplex_NAME (bool)

Performance metric type: none

Dynamic facet name, regex=/nic_duplex_\w+/

True if the NIC is in full-duplex mode

Facet only available if nicstats is true

agent.mon.esxServiceMonitor¶

Get data from the VMWare ESX Service Content Managed Object

This monitor logs into the ESX VI API and gets data from the Service Content Managed Object. It ascertains that the service is responding (a good starting point) and then gets “About” information. It then identifies the eventManager MOID and gets latest event information.

To use, declare a monitor like this in the manifest (realm and authType are optional):

<Monitor name="esxService" type="agent.mon.esxServiceMonitor">
  <Parameter name="server">eris</Parameter>
  <Parameter name="usr">root</Parameter>
  <Parameter name="pwd">secret</Parameter>
  <Parameter name="realm">Customer Realm</Parameter>
  <Parameter name="authType">basic</Parameter>
</Monitor>

Parameters¶

server (string): ESX Server or Virtual Centre hostname, FQDN or IP address

usr (string)

Session username

By default ESX credentials are the root username and password

pwd (string): Session password

realm (string): Optional (default: VMware VI SDK Browser). Authentication realm

authType (string)

Optional (default: basic). Authentication type

If the ESX service has been configured with a different authentication type, specify it here. Valid values are basic and digest.

Facets¶

available (bool)

Performance metric type: twgauge

True if service data was obtained

errorInfo (string): Error message if there were issues getting the data

responseTime (int)

Performance metric type: gauge

Respone time for the service call

latestEventType (string): E.g. “UserLoginSessionEvent”

latestEventTime (string): E.g. “2009-05-08 15:22:15”

latestEventMsg (string): E.g. “User root@127.0.0.1 logged in”

agent.mon.fileMonitor¶

Monitors a disk file

Parameters¶

path (string): Path to the file to monitor

md5 (bool)

Optional (default: false). Enable MD5 checksumming of the monitored file

The MD5 checksum of a file is not computed by default since it consumes a lot of CPU power and thus might result in a performance impact on the running agent when monitoring large files.

Facets¶

exists (bool)

Performance metric type: twgauge

Whether the file exists or not

True (1) if the file specified by the path parameter exists and False (0) otherwise.

md5 (string)

Hash of file contents

The MD5 checksum of the contents of the file, this can be used to detect changes in the file contents. It is only present if the md5 parameter is set to true.

sizeBytes (int)

Performance metric type: gauge

Size of the file in bytes

lastModification (int)

Performance metric type: none

Last modification time (MTIME)

Timestamp of the last modification time of the file’s contents.

lastAccess (int)

Performance metric type: none

Last time the file was accessed (ATIME)

lastChange (int)

Performance metric type: none

Last meta-data change (CTIME)

Timestamp of the last change to the files’s meta-data.

mode (string): Octal representation of the file mode permissions

inodeNumber (int): File’s inode number

device (int): Device the file is on

numLinks (int)

Performance metric type: gauge

Number of links to the file

This is the number of refrences to the file’s inode.

ownerUserId (int): File owner’s ID

ownerGroupId (int): File Owner’s group ID

ownerUserName (string): File owner’s user name

ownerGroupName (string): File owner’s group name

agent.mon.heartbeat¶

Simple heartbeating sampler

Parameters¶

None

Facets¶

timestamp (int)

Performance metric type: counter

UNIX timestamp when the sample ran

Notes¶

The heartbeat monitor is pre-configured in the HOST_MON built in and can be enabled with the following default settings:

Periodicity = 60 seconds
Message = Heartbeat: %(hostname)s at %(dts)s (%(facetValue)s)
Action = defaultTrap

<Component type="HOST_MON">
  <Monitor name="heartbeat"/>
</Component>

Customisation example:

Periodicity = 1 hour
Traps to heartbeatTrap

<Component type="HOST_MON">
  <Monitor name="heartbeat" periodicity=":1::">
    <Observation name="heartbeatObservation">
      <Trap name="heartbeatTrap"/>
    </Observation>
  </Monitor>
</Component>

agent.mon.httpMonitor¶

Monitor a HTTP resource

Perform an HTTP GET on a specified URL and parse the returned page using the supplied regex. Only the URL parameter is obligatory.

To use this monitor, declare a sample like this in the manifest:

<Monitor name="webServerMonitor"
            type="agent.mon.httpMonitor"
            periodicity="240">
  <Parameter name="url">http://earth.abilisoft.com</Parameter>
  <Parameter name="regex">.{,10}Earth.{,10}</Parameter>
  <Parameter name="authtype">BASIC</Parameter>
  <Parameter name="realm">foo</Parameter>
  <Parameter name="username">someone</Parameter>
  <Parameter name="password">secret</Parameter>
</Monitor>

Note that the authtype, realm, username and password are optional, but if any one of them is used all of them must be present.

Note: If you want your matching text to show context, judicious use of the regular expression should be employed. The expression /.{,10}/ used above is identical to /.{0,10}/ and will show up to 10 characters, but if the document contains less characters it will still match.

Parameters¶

url (string): URL for the resource

authtype (string)

Optional. Type of authentication

Only BASIC is currently supported, omit this parameter for no authentication.

realm (string): Optional. Authentication realm

username (string): Optional. Username required in the authentication realm

password (string): Optional. Password required in the authentication realm

regex (string): Optional. Regular expression to be applied to the resource content

Facets¶

responseCode (int)

Performance metric type: none

HTTP response code

responseMsg (string): HTTP response message (short)

responseDescr (string): HTTP response message (long)

loadTime (float)

Performance metric type: gauge

Resource load time

contentsHash (string): Checksum of the resource content

matchCount (int)

Performance metric type: gauge

Number of matches from the regular expression

matchN ()

Dynamic facet name, regex=/match\d+/

The matched text from the regular expression

Multiple facet values containing the value of each match from “match0” to “match(matchCount-1)”

agent.mon.ifStats¶

Monitor network interface statistics

Note

This monitor is not available on: OS X, AIX, Windows, Solaris 11 (SPARC and x86) or branded Solaris 10 zones running Solaris 11.

Parameters¶

name (string)

Optional. The interface name, e.g. lo, eth0, bge0 etc.

Either this or the regex parameter must be present.

regex (regex)

Optional. Regular expression to match interface name

This parameter can be used together with match_multiple to monitor multiple devices and deal with hotplugging.

Either this or the name parameter must be present.

match_multiple (bool)

Optional (default: true). Whether regex can match multiple devices

When multiple devices can be matched the monitor will scan for devices on every sample run, thus dealing with hotplugging of devices.

When this is set to false to monitoring is done static and the device must be present when the monitor starts. If regex matches multiple devices one will be picked at random and a warning logged.

Facets¶

name (string): The name of the interface

mtu (int)

Performance metric type: none

The Maximum Transfer Unit

status (string): Status, “up”, “down” or “unknown”

duplex (string): Duplex status: “full”, “half” or “unknown”

rxBytes (int)

Performance metric type: counter

Number of bytes received on interface

rxErrors (int)

Performance metric type: counter

Number of received packets with errors

rxDiscards (int)

Performance metric type: counter

Number of received packets discarded

txBytes (int)

Performance metric type: counter

Number of bytes sent on the interface

txErrors (int)

Performance metric type: counter

Number of packets with sending errors

txDiscards (int)

Performance metric type: counter

Number of packets discarded while sending

txQueueLen (int)

Performance metric type: gauge

TX queue length

agent.mon.logMonitor¶

Monitors a logfile

Note that the log files will only get opened once even for multiple instances of a LogMonitor. This means the updateRateThreshold of all but the first instance will be ignored.

The regular expression uses the DOTALL and MULTILINE flags.

This monitor will deal with rotating logfiles fine. To do this it checks if the file it is monitoring has been renamed and re-opening it if this is the case.

It also supports copy-truncate logfile rotating, but you must be aware of the limitations this scheme has:

Any data written after the last time the monitor ran but before the logfile was rotated will be lost.
If the logfile grows fast the monitor can not detect the file has rolled. In particular if the logfile grows larger then the previous size before the monitor runs again the monitor data will be lost.

Parameters¶

path (string)

Optional. The filename of the logfile to monitor

It is recommended to use an absolute path here. When this parameter is used the monitor will only monitor a single file.

pathregex (string)

Optional. Regular expression of logfiles to monitor

This is an alternative to path (and conflicts with it), it allows you to monitor multiple files by specifying a regular expression that the filenames must match.

Note that the regular expression can not include path separators (/ on Unix, \ on Windows) as each component in the path is split and matched separately. If you need an optional component make the contents of the component optional, e.g.: /foo/(bar)?/baz will monitor both /foo/baz and /foo/bar/baz (if they exist).

Also beware of accidentally matching the wrong directories: /var/adm/.+\.warn will monitor files in both /var/adm/ and /var/sysadmin/`. To only match files in one of the directories the more specific: /^var$/^adm$/.+\.warn should have been used.

Lastly note that resources used by a monitor using pathregex are not shared with any other monitor. This means that resource usage of asagent will increase if you have multiple monitors monitoring the same files as files monitorted by a monitor using pathregex. You can easily avoid this increased resource usage by only creating one monitor using pathregex and ensuring all your observations are made in this one monitor.

regex (string)

The regular expression applied to the log file content

Data matching the regular expression will result in samples being taken. Note that lines from the logfile being monitored will be searched for a match, so they will match at any location in the line. You could consider this as the expression being implicitly surrounded by .*. If you do not want this behaviour you must explicitly anchor the expression to the beginning and/or end of the line using ^ and $ respectively.

samplePerMatch (bool)

Optional (default: true). Whether to create one sample per match

Create a sample for each matching line, so that a sample will only have the occurrence facet. If this is disabled you will get only one sample without the occurrenceCount facet and multiple occurrenceN facets.

window (int)

Optional (default: 1). Enable multi-line log monitoring

When specified this must be 2 or higher. In this case the regular expression will be checked against the last N lines, where N is the number given to this parameter.

template (string)

Optional. A string template to use instead of the matched line

By using regular expression references to groups, either numbered or named, you can include parts of or the whole matched text. See below for examples.

maxGrowthRate (string)

Optional (default: 1Mb). Only read up to this amount of data in one sample run

If more data is available data will be skipped, refer to the cluster parameter for details of how it is skipped. This defaults to 1Mb which results in fairly sensible resource usage normally. If you specify just a number it will be interpreted as bytes, you can also use suffixes like Kb, Mb, KiB, MiB etc.

cluster (int)

Optional (default: max(512, maxGrowthRate/1024)). Chunk size of read data

When the filesize has gown too much in one sample run the monitor will only read up to maxGrowthRate data. This is done by reading a number of chunks equally spaced in the new data until the maximum amount of dat is read. This parameter allows you to fine-tune this behaviour by modifying the size of the chunks read. By default this is a sensibe value calculated as max(120, maxGrowthRate/1024). Numbers are interpreted as bytes, but you can also use suffixes like Kb, Mb, KiB, MiB etc.

maxfiles (int)

Optional (default: 1). Maximum number of logfiles to monitor

An upper bound to the number of log-files that can be selected using the pathregex parameter. All the matching files will be sorted as specified by the sort parameter and only the first N will be monitored, where N is defined by this parameter.

sort (string)

Optional (default: mtime,ctime,alpha). How to sort filenames before applying maxfiles

Sort matching log-files in this order before maxfiles is applied. This must be a comma separated list of:

mtime: Most recent mtime.

ctime: Most recent ctime.

atime: Most recent atime.

alpha: Alphabetically, from the base name of the log-file (i.e. no leading path).

custom: Custom template, see the sorttemplate parameter.

sorttemplate (string)

Optional. Template to allow custom sorting of matching logfiles

Allow custom sorting of matching log-files. This parameter contains a string which can be used by the custom sort key to the sort parameter. The string can use any regular-expression template substitutions to use parts of the pathname to sort on. This allows you to reference groups from the pathregex regular expression using the groupid and (?P=groupname) syntax. Each resulting string (after group substitution) will be sorted alphabetically.

seekend (bool)

Optional (default: true). Whether to start scraping the logfile from the top

Normally the logmonitor will start monitoring a logfile at the bottom and only check lines added after the agent has started monitoring it. However this option allows you to process the entire logfile on the first sample run.

Note that when a file is rolled over, which in the case of using the pathregex parameter means different new files got selected, the monitor will always start from the top of the file.

Facets¶

Changed in version 2.6.3: The errorInfo facet has been officially removed. It was already unused before.

logfile (string)

Path of the file which this sample came from

This facet is only present if the pathregex and samplePerMatch parameters where used.

New in version 2.6.3.

occurrenceCount (int)

Performance metric type: tally

Number of matches found in a single sampling effort

When samplePerMatch is disabled this facet represents the number of matches.

occurrenceN (string)

Dynamic facet name, regex=/occurrence\d+/

The line matching the regular expression

When samplePerMatch is disabled multiple occurrence*N* facets are made for each matching line. N starts counting from 0.

allOccurrences (string): All occurences separated by newlines

occurrence (string)

The line matching the regular expression

When samplePerMatch is enabled each sample will have this facet containing the matching line.

Notes¶

Using Templates¶

The template parameter specifies a string template to use instead of the matched line. By using regular expression references to groups, either numbered or named, you can include parts of (or the whole) matched text.

Specifying a template actually modifies the text stored in the agent’s data-store, so when using the template parameter the matched text will not be stored. The only information stored is what is available as the resulting facets data.

Some examples:

regex:        ^DEBUG (.*)
template:     \1
matched line: DEBUG doing something
stored match: doing something

regex:        ^DEBUG (?P<foo>.*)
template:     \g<foo>
matched line: DEBUG doing something
stored match: doing something

regex:        crit temp (?P<id>[a-z][0-9]) [0-9]+deg at (?P<loc>[a-zA-Z])
template:     Temperature \g<id> is critical in \2
matched line: crit temp c2 87deg at core
stored match: Temperature c2 is critical in core

As one can see, it is possible to strip out unimportant data which would normally make several matches look different.

Monitoring Multiple Files¶

Beware for suppressions when using the monitor to monitor multiple files. The suppression state will be shared between all sample results. This means that when a suppression is configured to not repeat the observation for 1 minute and two of the monitored files both have a new match only one of these observations will be raised while the other one will be suppressed.

The primary reason for the pathregex parameter is to be able to monitor logfiles of applications which name logfiles based on some pattern rather than a constant name.

agent.mon.multiProcessMonitor¶

Monitor an application that has many same-named processes

This sampler samples multiple processes at the same time, giving you the number of processes as well as min max and avg values of the same facets as the normal ProcessMonitor.

You must take into account that this is a fairly expensive monitor. On each run this had to trawl trough the entire process table.

Parameters¶

regex (string): Regular expression the processes must match

groupLeader (bool)

Optional (default: false). Whether the regular expression must match a group leader

Boolean value indicating that the regular expression must be the leader of a process group. All processes in the group will be monitored. Processes that match the regular expression but are not group leaders will trigger a warning message in the log file and will not be monitored.

samplePerGroup (bool)

Optional (default: false). Whether to match multiple process groups

Only valid if groupLeader is set to true, in that case if this is also true then there can be multiple group leaders that match the regular expression: each process group will get it’s own sample.

Facets¶

count (int)

Performance metric type: gauge

The number of processes found

minPercentCpu (float)

Performance metric type: gauge

Lowest percentage CPU usage of all processes

maxPercentCpu (float)

Performance metric type: gauge

Highest percentage CPU usage of all processes

avgPercentCpu (float)

Performance metric type: gauge

Average percentage CPU usage of all processes

totalPercentCpu (float)

Performance metric type: gauge

Total percentage CPU of all processes

maxPercentCpuPid (string): The process ID of the process with the highest CPU usage

minRss (int)

Performance metric type: gauge

The lowest resident memory usage of all processes (bytes)

maxRss (int)

Performance metric type: gauge

The highest resident memory usage of all processes (bytes)

avgRss (int)

Performance metric type: gauge

The average resident memory usage of all processes (bytes)

totalRss (int)

Performance metric type: gauge

The total resident memory usage of all processes (bytes)

maxRssPid (string): The process ID of the process with the hightest RSS

minVsz (int)

Performance metric type: gauge

The lowest virtual memory usage of all processes (bytes)

maxVsz (int)

Performance metric type: gauge

The highest virtual memory usage of all processes (bytes)

avgVsz (int)

Performance metric type: gauge

The average virtual memory usage of all processes (bytes)

totalVsz (int)

Performance metric type: gauge

The total virtual memory usage of all processes (bytes)

maxVszPid (string): The process ID of the process with the hightest VSZ

processGroup (int): The process group monitored (when groupLeader is true)

agent.mon.oidGet¶

Sampler for AgentX GET requests

This sampler allows you to get any SNMP OID that has been registered by AgentX (RFC 2741) subagents. It uses the AgentX master agent build in into asagent to get the sample types. This means that the subagent the sample will be retrieved from will depend on normal AgentX rules based on registered subtrees and their priority.

Parameters¶

oid (string): The SNMP value object identifier (OID)

context (string)

Optional. The SNMP context

If the context parameter is missing no context is used, if it is empty the empty context (‘’) is used, otherwise the given context.

internal (bool)

Optional (default: false). Use the AgentX subagent internal to asagent

If true the monitor will use the AgentX subagent, otherwise it will get values from a second sub-agent (if connected; the socket a second sub-agent connects to is specified by the agentx_listenaddr runtime setting).

Warning

Use of the internal subagent for oidGet monitoring is very much discouraged, especially in a production environment. It is possible to kill off the connection to the internal subagent which will have a serious impact on asagent‘s main monitoring capability. You should only set this parameter to true for testing and experimental purposes.

Note

It is possible to use the same snmpd binary which is shipped with asagent as a subagent by starting it with the required arguments from an init.d script or similar system startup tool. Please note however that while this is the approved usage of oidGet monitoring, it cannot be considered a static and backwards compatible interface of asagent. The capabilities of the snmpd binary is out of Abilisoft’s control may change between releases without notice. Therefore it is important to verify the behaviour is as expected after each asagent release to ascertain it still suits your needs.

Facets¶

errorInfo (string): Error reported, if any

oid (string): The SNMP value object identifier (OID)

type (string): The MA datatype of the data facet

snmpType (string): The SNMP type of the value

data (): The returned data, mapped from SNMP-types to MA-types

Notes¶

SNMP Data Types¶

SNMP data facet is mapped from SNMP types to agent type as follows:

SNMP Type	AsAgent Type
Integer	int
OctetString	string
Null	string
ObjectIdentifier	string
IpAddress	string
Counter32	int
Gauge32	int
TimeTicks	int
Opaque	string
Counter64	int
noSuchObject	string
noSuchInstance	string
endOfMibView	string

Using net-snmp as AgentX Subagent¶

It is possible to use the popular Net-SNMP free software package as an AgentX (RFC 2741) subagent. Essentially this just needs the -X argument, a full example of starting the net-snmp agent as an AgentX subagent would be:

snmpd -n myname -X -x $AS_HOME/var/agentx/asagent-master -r -C -c /path/to/mysnmpd.conf

where:

-X: Run in AgentX subagent mode instead of SNMP master agent

-x: The address to use for a connection to the AgentX master

-n: Specifies a different application name instead of “snmpd”

-r: Do not require root permissions

-C: Ignore configuration files others the specified by -c

-c: Use a specific configuration file

agent.mon.oidWalk¶

Sampler for AgentX GET-NEXT requests

MA leverages its own SNMP sub-agent to get certain metrics. This monitor makes available data from any OID tables supported by the sub-agent. Furthermore when the internal parameter is false, MA will attempt to get the specified OID from a second sub-agent (if connected).

The monitor must be defined with a valid tableoid parameter. This is important because the monitor assumes that this parameter references an OID table structure; for example, consider the SysORTable:

sysORTable:  .1.3.6.1.2.1.1.9
sysOREntry:  .1.3.6.1.2.1.1.9.1
sysORIndex:  .1.3.6.1.2.1.1.9.1.1 (i.e. column 1)
sysORID:     .1.3.6.1.2.1.1.9.1.2 (i.e. column 2)
sysORDescr:  .1.3.6.1.2.1.1.9.1.3 (i.e. column 3)
sysORUpTime: .1.3.6.1.2.1.1.9.1.4 (i.e. column 4)

Which gives rise to the rows:

row 1:

.1.3.6.1.2.1.1.9.1.1.1
.1.3.6.1.2.1.1.9.1.2.1
.1.3.6.1.2.1.1.9.1.3.1
.1.3.6.1.2.1.1.9.1.4.1

row 2:

.1.3.6.1.2.1.1.9.1.1.2
.1.3.6.1.2.1.1.9.1.2.2
.1.3.6.1.2.1.1.9.1.3.2
.1.3.6.1.2.1.1.9.1.4.2

Note the row indices don’t have to start from one, nor do they have to be contiguous. Some tables (for example, the tcpConnectionTable has multiple indices).

New in version 2.6.2: Multi-indexed tables are supported.

Example¶

A complete example, this will alert if any agent capability (from the sysORTable) was reinstantiated. It does this by checking that the sysORUpTime value of each capability has not changed since the last time:

<Monitor name="sysor" type="agent.mon.oidWalk" periodicity="1800">
  <Parameter name="tableoid">.1.3.6.1.2.1.1.9</Parameter>
  <Parameter name="columns">2,4</Parameter>
  <Observation>
    <SourceFacet>col4_data</SourceFacet>
    <Test type="compare">
      <Parameter name="arg0">$col4_data</Parameter>
      <Parameter name="arg1">last($col4_data)</Parameter>
      <Parameter name="operator">ne</Parameter>
    </Test>
    <Message>
      The %(Facet.col2_data)s capability got reinstatiated
    </Message>
    <Trap name="defaultTrap"/>
  </Observation>
</Monitor>

Parameters¶

internal (bool)

Optional (default: false). Use the AgentX subagent internal to asagent

If true the monitor will use the AgentX subagent, otherwise it will get values from a second sub-agent (if connected; the socket a second sub-agent connects to is specified by the AgentXSocket runtime setting).

Warning

Use of the internal subagent for oidWalk monitoring is very much discouraged, especially in a production environment. It is possible to kill off the connection to the internal subagent which will have a serious impact on asagent‘s main monitoring capability. You should only set this parameter to true for testing and experimental purposes.

Note

It is possible to use the same snmpd binary which is shipped with asagent as a subagent by starting it with the required arguments from an init.d script or similar system startup tool. Please note however that while this is the approved usage of oidWalk monitoring, it cannot be considered a static and backwards compatible interface of asagent. The capabilities of the snmpd binary is out of Abilisoft’s control may change between releases without notice. Therefore it is important to verify the behaviour is as expected after each asagent release to ascertain it still suits your needs.

context (string)

Optional (default: None). The context to get the OID from

The default is to not use any context. To use a context set this parameter to the required string.

Note that to get an empty context you need to specify an empty string in this parameter, i.e. make sure the parameter is present but does not contain any string.

tableoid (string)

Base OID to walk the tree from

This must be the OID of a table, so the OID of the entry can be created by appending .1, the OID of the first column by appending .1.1, the second column by appending .1.2 etc.

columns (string)

Optional. List of column IDs to create facets for

Comma separated list of column IDs that the agent should create facet values for. If empty or not specified all columns will get facets.

rows (string)

Optional. List of row IDs to create samples for

Comma separated list of the rows to create samples for. If empty or not specified all rows will be retrieved (up to ‘maxrows’).

maxrows (int): Optional (default: 50). Maximum number or rows to retrieve

Facets¶

error (string)

In case of an error a description of the problem

Changed in version 2.6.2: This facet used to be called errorInfo.

colX_oid (string)

Dynamic facet name, regex=/col\d+_oid/

The OID of the returned VarBind

This will be the index of the exact cell in the table

colX_type (string)

Dynamic facet name, regex=/col\d+_type/

The type of the data returned

This is the type it has inside the asagent database, not the SNMP type. This is different from the snmpType to help creating tests for observations.

colX_snmpType (string)

Dynamic facet name, regex=/col\d+_snmpType/

The SNMP type of the data returned

This is the type of the original SNMP varbind.

colX_data ()

Dynamic facet name, regex=/col\d+_data/

The actual data returned, type depends on the type of the OID

Notes¶

See the notes on the agent.mon.oidGet monitor.

agent.mon.osCmd¶

Execute a command and create samples based on the result

Parameters¶

Changed in version 2.6.0: The type parameter has been dropped, this should now be done by using casting functions in the tests.

command (string)

Command to be executed

It is recommended the to refer to the command with an absolute path as the agent environment might not have the PATH you expect.

timeout (int)

Optional (default: 5). Maximum time the command can run

Timeout in seconds before the command will be killed if it hasn’t returned by then.

New in version 2.6.0.

parse (bool)

Optional (default: false). Parse the output into facets

When this option is enabled the standard output of the command is parsed and multiple facets and/or samples are created.

The simplest use is to create multiple facets on the sample, this can be done by creating an output like this:

facet:foobar:bool: 0
facet:foo:int: 42
facet:baz:float: 7.3
facet:bar:string: some text, must not include newlines

That means facets are newline-separated and each facet must start with literal text facet, the name of the facet and the type of the facet, all separated by :, i.e. facet:<name>:<type>:. Facet names cannot conflict with the existing facets names: error, stdout, stderr and status.

The facet types are:

Bool :	A boolean, represented as `0` or `1` only.
Int :	An integer number.
Float :	A floating point number.
String :	A string which can contain any character except a newline. Note that leading and trailing white space will be stripped from this string.

Creating multiple samples, each with one or more facets, is slightly more involved, e.g.:

sample:0:0:facet:foo:int: 4
sample:0:0:facet:bar:int: 42
sample:0:1:facet:foo:int: 5
sample:0:1:facet:bar:int: 43

Here sample:0:0: defines the sample a facet belongs too, while the actual specification of the facet, facet:foo:int: 4 is exactly as above. So this example creates two samples both with a foo and bar facet.

To fully understand how samples are distinguished you should know how sample sub-IDs and sample instances work. Each 0:0 pair is actually <subid>:<instance>, the subid will be literally used in the created sample and will ensure different suppressors and testers are used for each different subid. The instance is simply a number and will represent different sample instances, but the instance numbers will not necessarily match those actually used in the samples.

New in version 2.6.0.

Changed in version 2.6.1: Creating multiple samples was added.

Facets¶

Changed in version 2.6.0: The value facet has been dropped, you can use the stdout facet in combination with casting functions (Test Argument Expressions) instead.

error (string)

Description of the problem in case of error

If this facet is present the value facet will not be present as there will have been no result.

stdout (string): Raw standard output of the command

stderr (string): Raw standard error of the command

status (int)

Exit status of the command

A negative exit status signifies the process was killed by a signal.

as_parsed ()

Dynamic facet name, regex=/.*/

Dynamically created facets as parsed

agent.mon.peerMonitor¶

Monitors a peer agent specified by host name

This sampler checks that the specified agent is responding and also gathers key metrics like CPU and Memory utilisation. This enables all sorts of interesting peer monitoring like checking for excessive cpu and memory usage, configuration changes and restarts.

Examples¶

Peer Alive-ness monitor:

<Monitor name="neighbour@amazonia"
         type="agent.mon.peerMonitor"
         periodicity="60">
  <Parameter name="host">amazonia:28001</Parameter>
  <Parameter name="usr">admin</Parameter>
  <Parameter name="pwd">secret</Parameter>
  <Parameter name="stats">false</Parameter>
  <Observation name="aliveAliveO">
    <Test type="compare">
      <Parameter name="arg0">$alive</Parameter>
      <Parameter name="arg1">false</Parameter>
      <Parameter name="operator">eq</Parameter>
    </Test>
    <Message>MA at %(Parameter.host)s is not responding</Message>
    <Suppression numberOfTimes="3"/>
    <Smtp name="defaultSmtp"/>
  </Observation>
</Monitor>

Peer is railing monitor:

<Monitor name="neighbour@amazonia"
         type="agent.mon.peerMonitor"
         periodicity="60">
  <Parameter name="host">amazonia:28001</Parameter>
  <Parameter name="usr">admin</Parameter>
  <Parameter name="pwd">secret</Parameter>
  <Observation name="railing">
    <Test type="compare">
      <Parameter name="arg0">$cpu</Parameter>
      <Parameter name="arg1">90</Parameter>
      <Parameter name="operator">gte</Parameter>
    </Test>
    <Message>MA at %(Parameter.host)s is using excessive CPU</Message>
    <Suppression numberOfTimes="3"/>
    <Smtp name="defaultSmtp"/>
  </Observation>
</Monitor>

Peer has bounced monitor:

<Monitor name="neighbour@amazonia"
         type="agent.mon.peerMonitor"
         periodicity="60">
  <Parameter name="host">amazonia</Parameter>
  <Parameter name="usr">admin</Parameter>
  <Parameter name="pwd">secret</Parameter>
  <Observation name="bouncyBouncy">
    <Test type="compare">
      <Parameter name="arg0">$upTimeSeconds</Parameter>
      <Parameter name="arg1">last($upTimeSeconds)</Parameter>
      <Parameter name="operator">lt</Parameter>
    </Test>
    <Message>MA at %(Parameter.host)s has restarted</Message>
    <Suppression numberOfTimes="0"/>
    <Smtp name="defaultSmtp"/>
  </Observation>
</Monitor>

Parameters¶

host (string)

The host the peer agent is on

This can be a hostname or an IP address. If the agent is running on a nonstandard port then specify host:port.

usr (string)

Username

Note that this user must have privilege for the ma.aapi.Query feature.

pwd (string): Password

stats (bool): Optional (default: true). Whether to gather agent stats or only do an aliveness check

ssl (bool): Optional (default: true). Whether to use ssl for the connection

Facets¶

alive (bool)

Performance metric type: twgauge

True if peer responds, False otherwise

errorInfo (string): Information about any connection issues

responseTime (int)

Performance metric type: gauge

Period in ms response took

startTime (string)

Performance metric type: none

Peer start time in SYSTEM_TIME_FMT

upTimeSeconds (int)

Performance metric type: counter

Peer uptime in seconds

upTime (string): Peer uptime in Days, Hours, Minutes, Seconds

configLocation (string): Peer’s configuration file path

configDts (string): Peer’s configuration file time stamp

host (string): Peer’s hostname

ip (string): Peer’s IP address(es)

cpu (float)

Performance metric type: gauge

Peer’s CPU usage

rss (int)

Performance metric type: gauge

Peer’s memory usage (RSS)

vsz (int)

Performance metric type: gauge

Peer’s memory usage (VSZ)

rssStr (string): RSS usage as a friendly string

vszStr (string): VSZ usage as a friendly string

agent.mon.processMonitor¶

Monitor a process

Monitor a single process whose command line matches the regex parameter.

The zoneid and zonename parameters are optional, mutually exclusive and only supported on Solaris 10 or higher.

Note that if samplePerGroup is used then new groups will only be detected when an already monitored group leader disappears. Furthermore it’s use exclude the use of the processDead and processBounce test types. This is because these tests can only function if the regular expression used to identify a process identifies the process uniquely in time, which is not the case when samplePerGroup is used.

If more than one process matches the regex parameter the first process matched found is used to create facet data and a warning log message is output to the agent’s log file.

If no process matches the regex parameter a sample with no facets is created.

Parameters¶

regex (string): Fingerprint of the process to monitor

cmdOldest (bool): Optional (default: false). Whether to take the oldest from all matching processes

sessionLeader (bool): Optional (default: false). When true, only match processes who are session leaders

groupLeader (bool): Optional (default: false). When true, only match processes who are group leaders

samplePerGroup (bool): Optional (default: false). When true, create a sample for each matching process if they are in different groups

zoneid (int): Optional. The zone ID the process must be in

zonename (string): Optional. The zone name the process must be in

username (string): Optional. The username the process should be running as

Facets¶

pid (int)

Process ID

Changed in version 2.6.3: The type used to be a string which could be empty, now if there is no process a sample with only the error facet is created.

ppid (int)

Parent process ID

Changed in version 2.6.3: The type used to be a string.

sTime (int)

Performance metric type: none

Timestamp of the start time

time (float)

Performance metric type: counter

Total CPU time of a process

percentCpu (float)

Performance metric type: gauge

Percent of 1 CPU core this process has used. E.g. on a dual core machine this can be maximum 200%.

percentCpuByCore (float)

Performance metric type: gauge

Percent of CPU this process has used averaged by number of cores. E.g. on a dual core machine this can be maximum 100%.

percentCpuLife (float)

Performance metric type: gauge

Percent CPU usage over the process lifetime. This is not averaged over the number of cores so e.g. on a dual core machine this can be maximum 200%.

residentSize (int)

Performance metric type: gauge

RSS memory in bytes

virtualSize (int)

Performance metric type: gauge

VSZ memory in bytes

userName (string): User name of process owner

executable (string): Path to the executable image

command (string): Process command line

args (string): Process arguments

argCount (int): Process argument count

argN (string)

Dynamic facet name, regex=/arg\d+/

The N*th argument, 1 <= *N <= argCount

Multiple facet values containing the value of each process argument from “arg0” to “arg(argCount-1)”.

pgrp (int): Process Group ID (UNIX only)

sid (int): Session ID (UNIX only)

error (string)

In case of a problem this facet is added

Usually this is the case if the process can not be found as otherwise you’d have sample with no facets which would be hard to detect in the SAMPLE table.

zoneid (int): The zone ID when running on Solaris 10

zonename (string): The zone name when running on Solaris 10

Notes¶

Arguments on Solaris¶

On Solaris the default ps command /usr/bin/ps shows the initial argument string the command was invoked with. This information is provided by the Solaris kernel in the /proc/<pid>/psinfo file and never changes for the lifetime of the process. However, this string is limited to PRARGSZ characters (typically 80). Therefore, for processes with arguments that exceed this limit the full command line is not available.

To alleviate this problem the /usr/ucb/ps and /usr/bin/pargs programs read the program commands from the process’s address spaces, thus allowing the full command line to be retrieved. This is also the approach taken by MA as it provides the most complete command line to match regular expressions against. This does however have two consequences:

The watching process (asagent, pargs or /usr/ucb/ps) needs to have permission to read the address space of the process. Generally you can only read the address space of processes belonging to the same user as the process reading, but when running as root you can read any process’ address space.
Processes can re-write the memory in their own address space. While most processes don’t change their original argument list, some will do this (some known examples are sendmail and postgresql). This means the original command line the process was invoked with is lost. In this case you must check the output of pargs or /usr/ucb/ps axww to understand which regular expression will match the process. Care should be taken as some processes will keep changing the arguments during their lifetime as a way of representing “status” messages.

agent.mon.selfMonitor¶

selfMonitor gathers AsAgent health metrics of itself

This sampler gathers the agents health metrics. This enables all sorts of interesting agent-local monitoring like checking for excessive cpu and memory usage, configuration changes and restarts.

Usage:

Restart monitor:

<Monitor name="restart"
         type="agent.mon.selfMonitor"
         periodicity="60">
  <Observation name="restartObs">
    <Test type="compare">
      <Parameter name="arg0">$upTimeSeconds</Parameter>
      <Parameter name="arg1">last($upTimeSeconds)</Parameter>
      <Parameter name="operator">lt</Parameter>
    </Test>
    <Message>MA at %(hostname)s has restarted</Message>
    <Suppression numberOfTimes="0"/>
    <Smtp name="defaultSmtp"/>
  </Observation>
</Monitor>

Excessive cpu monitor:

<Monitor name="excessCpu"
         type="agent.mon.selfMonitor"
         periodicity="60">
  <Observation name="excessCpuObs">
    <Test type="compare">
      <Parameter name="arg0">$cpu</Parameter>
      <Parameter name="arg1">5</Parameter>
      <Parameter name="operator">gt</Parameter>
    </Test>
    <Message>MA at %(hostname)s is using excessive CPU</Message>
    <Suppression numberOfTimes="10"/>
    <Smtp name="defaultSmtp"/>
  </Observation>
</Monitor>

Parameters¶

None

Facets¶

startTime (string)

Performance metric type: none

Agent start time

The timezone is influenced by the LogTimeUTC setting.

upTimeSeconds (int)

Performance metric type: counter

Agent uptime in seconds

upTime (string): Agent uptime in days, hours, minutes, seconds

configLocation (string): Agent’s configuration file path

configDts (string)

Agent’s configuration file time stamp

The timezone is influenced by the LogTimeUTC setting.

host (string): Agent’s hostname

ip (string): Agent’s IP address(es)

cpu (float)

Performance metric type: gauge

Agent’s %CPU usage

This is the percentage of available CPU on the system which has been used in the last minute by asagent.

Since this data is taken from the same source as the STATUS table via the AAPI it is only updated once a minute.

rss (int)

Performance metric type: gauge

Agent’s memory usage (RSS) in bytes

Since this data is taken from the same source as the STATUS table via the AAPI it is only updated once a minute.

vsz (int)

Performance metric type: gauge

Agent’s memory usage (VSZ) in bytes

Since this data is taken from the same source as the STATUS table via the AAPI it is only updated once a minute.

rssStr (string)

RSS usage as a friendly string

Since this data is taken from the same source as the STATUS table via the AAPI it is only updated once a minute.

vszStr (string)

VSZ usage as a friendly string

Since this data is taken from the same source as the STATUS table via the AAPI it is only updated once a minute.

agent.mon.snmpGet¶

Get sample values from the specified SNMP agent

Parameters¶

Changed in version 2.6.2: The type parameter was removed. Use casting functions inside the tests instead.

oid (string): The SNMP OID to get

host (string): The host to send the request to

version (string): Optional (default: 2c). SNMP version to use: 1, 2c or 3

community (string): Optional (default: public). Community string to use for SNMPv1 and v2c

contextName (string): Optional (default: “” (empty string)). Context name for SNMPv3

seclevel (string)

Optional (default: noAuthNoPriv). SNMPv3 security level

This must be one of: “noAuthNoPriv”, “authNoPriv” or “authPriv”.

secName (string): Optional. Security name used for SNMPv3 authentication

authProtocol (string): Optional. Authentication protocol for SNMPv3, one of “MD5” or “SHA”

authPassword (string): Optional. Authentication password for SNMPv3

privProtocol (string): Optional. Privacy protocol for SNMPv3, one of “DES” or “AES”

privPassword (string): Optional. Privacy password for SNMPv3

Facets¶

oid (string): The OID of the returned varbind

value (): The value of the returned varbind

type (string): The SNMP type of the value

agent.mon.systemInfo¶

Gathers system information including OS type

Parameters¶

None

Facets¶

osName (string): Name of the operating system

osVersion (string): Version string of the operating system

osCategory (string): Abilisoft TKM OS category

cpuCount (int)

Performance metric type: none

Number of processors on the system

upTime (int)

Performance metric type: counter

Time the system has been running in seconds

release (string): The release of the operating system

platform (string): Identified platform

processor (string): Processor type

processesCount (int)

Performance metric type: gauge

Total number of processes currently running

virtualised (bool)

If the host is virtualised or not

This currently is currently detected when the agent is running in a Linux, Solaris or AIX guest virtualised by Xen, KVM, Qemu, VMware, VirtuaPC, LPAR, LDOM or Solaris zones.

virtType (string)

Type of virtualisation

The known virtualisation technologies are: VMware, Xen, QEMU/KVM, LDOM, LPAR, zone.

virtInfo (string)

Extra info about the VM where available

This contains information like the ID or name of a virtualised environment where this is possible for the guest to know this (e.g. AIX LPARs and Solaris zones).

agent.mon.winEventLogMonitor¶

Monitor the Windows event log

Matching criteria are defined with a regular expression using one or more of the *_re parameters. Individually the *_re parameters are optional but at least one must be specified.

Note

This monitor is only available on Windows platforms.

Parameters¶

logType (string)

The type of event log to be monitored

E.g. APPLICATION, SECURITY, SYSTEM, etc.

type_re (regex): Optional. Regular expression to match on event type field. The event type field defines the event log record’s level, e.g: Information, Warning, Error etc.

src_re (regex): Optional. Regular expression to match on event source field. The event source field defines the origin of the event log record, e.g: Kernel-General, Service Control Manager etc.

cat_re (regex): Optional. Regular expression to match on event category field. The event category field is an application-specific integer value subcategory the event provider specified for the event.

evt_re (regex): Optional. Regular expression to match on event ID field. The event ID field is an application-specific integer value identifier that the event provider specified for the event.

usr_re (regex): Optional. Regular expression to match on event user field. The event user field is the name of the user that created the event, e.g: SYSTEM, LOCAL SERVICE, NETWORK SERVICE. The value is derived from the record’s SID field value and when this is not set the monitor assumes a value of n/a.

msg_re (regex): Optional. Regular expression to match on event message field. The event message field contains a descriptive message for the event, e.g: The Software Protection service entered the stopped state.

Facets¶

occurrenceCount (int)

Performance metric type: tally

Number of matches found in a single sampling run

occurrenceN (string)

Dynamic facet name, regex=/occurrence\d+/

The individual matches

Multiple facet values containing the value of each match from “occurrence0” to “occurrence(occurrenceCount-1)”

agent.mon.wmiMonitor¶

Sampler that performs WMI Queries

This sampler is only available on Windows(tm) platforms. It allows the user to specify a WQL query to be performed. All property values of the first class instance returned from the WQL query are added as facet values of the same name. Note that only the first instance is considered when copying property values to sample facets. If no instances are returned the facet ‘errorInfo’ is set with (hopefully) useful information.

However, if the parameter ‘instanceCount’ is true, then the number of class instances returned from the WQL query are added to the facet called ‘instanceCount’ (whether 0 or otherwise).

If the WQL query fails under any circumstances the facet ‘errorInfo’ is set.

Example Usage:

Registry Size Monitor:
<Monitor name="registrySizeMonitor"
         type="agent.mon.wmiMonitor"
         periodicity=":::10">
  <Parameter name="moniker">//./root/cimv2</Parameter>
  <Parameter name="wql">SELECT CurrentSize FROM Win32_Registry</Parameter>
  <Parameter name="CurrentSize_type">int</Parameter>
  <Observation name="RegistrySizeBreach">
    <Test type="threshold">
      <Parameter name="arg0">$CurrentSize</Parameter>
      <Parameter name="upper">5</Parameter>
      <Parameter name="lower">0</Parameter>
      <Parameter name="inclusive">false</Parameter>
    </Test>
    <Message>%(hostname)s: Registry has exceeded 5Mb</Message>
    <Trap name="defaultTrap"/>
  </Observation>
</Monitor>
Any interfaces unavailable:
<Monitor name="interfaceMonitor"
         type="agent.mon.wmiMonitor"
         periodicity=":::10">
      <Parameter name="wql"><![CDATA[SELECT Name, NetConnectionStatus from Win32_NetworkAdapter WHERE NetConnectionStatus <> 2]]</Parameter>
  <Parameter name="instanceCount">true</Parameter>
  <Observation name="ifUnavailable">
    <Test type="compare">
      <Parameter name="arg0">$instanceCount</Parameter>
      <Parameter name="arg1">0</Parameter>
      <Parameter name="operator">ge</Parameter>
    </Test>
    <Message>%(hostname)s - There are %(facetValue)s interfaces unavailable</Message>
    <Suppression numberOfTimes="1"/>
    <Trap name="defaultTrap"/>
  </Observation>
</Monitor>
Note the CDATA block in the wql parameter, this is necessary because of the “not-equals” operator embedded in the XML.

Parameters¶

moniker (string): Optional. The moniker parameter used when opening the WMI connection

wql (string): The WQL query to perform

<property_name>_type (string)

Optional (default: string). The facet type a property value should be cast to

WmiMonitor will attempt to cast the WMI class instance property to a facet of this type. If the cast fails the facet will not be added. Valid values are int, float, string and bool.

instanceCount (bool)

Optional (default: false). Whether to only create the instanceCount facet

When true, the only facet value that is added to the sample result is the number of class instances returned from the WMI query.

Facets¶

ClassInstancePropertyName ()

Dynamic facet name, regex=/.*/

A WMI class instance property returned from the query

The type is defined by the *property_name*_type parameter (int, float, string or bool).

instanceCount (int)

Performance metric type: gauge

The number of class instances returned

Only set when instanceCount parameter is true.

errorInfo (string)

Error infromation in case of failure

Error information when a WQL query fails or when there are no instances returned by a query and the instanceCount parameter was not set to true.

agent.mon.xenHostInfoMonitor¶

Static information about Xen hosts

Monitors the nominated Xen pool host for availability, response time and a range of “static” facets values that could be gathered on a one-time basis. Facets include Xen Version, OS Version, number of CPUs, PBDs (storage) and NICs.

To use, declare a monitor like this in the manifest:

<Monitor name="xenHostInfoMon" type="agent.mon.xenHostInfoMonitor">
  <Parameter name="server">ceres</Parameter>
  <Parameter name="hostname">192.168.2.116</Parameter>
  <Parameter name="usr">root</Parameter>
  <Parameter name="pwd">secret</Parameter>
</Monitor>

Parameters¶

server (string)

The hostname, IP address or FQDN of any host in the pool

Preferably this is the pool master.

usr (string)

Session username

By default Xen credentials are the root username and password.

pwd (string): Session password

hostname (string)

The name of the pool host that is to be monitored

This value will be compared to the host record “name_label”, “hostname” and “address” fields when trying to identify the host.

Facets¶

available (bool)

Performance metric type: twgauge

True if Xen pool master is available

errorInfo (string): Error message if there were issues getting the data

responseTime (int)

Performance metric type: gauge

Response tim for the call to the service

actualMaster (string)

If server is not the master, this contains the master

If the server parameter was not the pool master, this facet specifies the URL of the master MA did log into.

product (string): Xen product brand

xenVersion (string): Xen product version (e.g. 3.2.1)

osVersion (string): OS Version (e.g. 5.0.0)

apiVersion (string): Host API Version (e.g. 1.5)

xapiVersion (string): XAPI Version(e.g. 1.2)

vendor (string): Xen Vendor

description (string): Host description

numCPUs (int)

Performance metric type: none

Number of physical CPUs

cpuModel (string): Hardware CPU Model

cpuSpeed (int)

Performance metric type: none

Hardware CPU Speed

cpuVendor (string): Hardware CPU Vendor

numPBDs (int)

Performance metric type: none

Number of Physical Block Devices

numNICs (int)

Performance metric type: none

Number of Network Interfaces

agent.mon.xenHostMonitor¶

Availability monitoring of a Xen host

Monitors the nominated Xen pool host for availability, response time, enabled state, live status, boot time, cpu and memory. Optional parameters specify whether PBD (storage) and NIC status should be gathered.

To use, declare a monitor like this in the manifest:

<Monitor name="xenHostMon" type="agent.mon.xenHostMonitor">
  <Parameter name="server">ceres</Parameter>
  <Parameter name="hostname">192.168.2.116</Parameter>
  <Parameter name="usr">root</Parameter>
  <Parameter name="pwd">secret</Parameter>
</Monitor>

Parameters¶

server (string)

The hostname, IP address or FQDN of any host in the pool

Preferably this is the pool master.

usr (string)

Session username

By default Xen credentials are the root username and password.

pwd (string): Session password

hostname (string)

The name of the pool host that is to be monitored

This value will be compared to the host record “name_label”, “hostname” and “address” fields when trying to identify the host.

vmstats (bool): Optional (default: false). Whether to gather information about VMs on this physical host

pbdstats (bool)

Optional (default: false). Whether to gather storage statistics

If true the monitor will gather information about physical block devices (PBD) and storage repositories (SR) on this physical host.

nicstats (bool): Optional (default: false). Whether to gather network interface statistics

Facets¶

available (bool)

Performance metric type: twgauge

True if xen pool master is available and false otherwise

errorInfo (string): Error message if there were issues getting the data

responseTime (int)

Performance metric type: gauge

Response time for the call

actualMaster (string)

If server is not the master, this contains the master

If the server parameter was not the pool master, this facet specifies the URL of the master MA did log into.

live (bool)

Performance metric type: twgauge

True if the pool master thinks the host is live

enabled (bool)

Performance metric type: twgauge

True if the host is enabled, false otherwise

bootTime (string)

Performance metric type: none

Time last booted

cpuPct (float)

Performance metric type: gauge

Host CPU usage as a percentage

memTotal (int)

Performance metric type: none

Host total memory (bytes)

memUsed (int)

Performance metric type: gauge

Host used memory (bytes)

numVms (int)

Performance metric type: gauge

Number of VMs guested on this host

Facet only available if vmstats parameter is true.

numVmsRunning (int)

Performance metric type: gauge

Number of VMs on this host that have a running powerState

Facet only available if vmstats parameter is true.

numPBDs (int)

Performance metric type: none

Number of PBDs on this host

Facet only available if pbdstats parameter is true.

numPBDsAttached (int)

Performance metric type: none

Number of PBDs on this host that are attached

Facet only available if pbdstats parameter is true.

pbd_attached_N (bool)

Performance metric type: twgauge

Dynamic facet name, regex=/pdb_attached_\d+/

True if PBD N is attached

Facet only available if pbdstats parameter is true.

pbd_location_N (string)

Dynamic facet name, regex=/pdb_location_\d+/

Location/device name of parent PBD

Facet only available if pbdstats parameter is true.

sr_name_N (string)

Dynamic facet name, regex=/sr_name_\d+/

Associated SR Name

Facet only available if pbdstats parameter is true.

sr_virt_allocation_N (int)

Performance metric type: none

Dynamic facet name, regex=/sr_virtu_allocation_\d+/

Total size of all VDIs in this storage repository

Facet only available if pbdstats parameter is true.

Sum of virtual_sizes of all VDIs in this storage repository (in bytes).

sr_physical_size_N (int)

Performance metric type: gauge

Dynamic facet name, regex=/sr_physical_size_\d+/

Currently used space on the storage repository

Facet only available if pbdstats parameter is true.

Physical space currently utilised on this storage repository (in bytes).

numNics (int)

Performance metric type: none

Number of pyhsical network interfaces found for this host

Facet only available if nicstats parameter is true.

nic_device_N (string)

Dynamic facet name, regex=/nic_device_\d+/

NIC device name

Facet only available if nicstats parameter is true.

nic_name_N (string)

Dynamic facet name, regex=/nic_name_\d+/

NIC descriptive name

Facet only available if nicstats parameter is true.

nic_io_read_kbs_N (int)

Performance metric type: counter

Dynamic facet name, regex=/nic_io_read_kbs_\d+/

NIC Kbytes read

Facet only available if nicstats parameter is true.

nic_io_write_kbs_N (int)

Performance metric type: counter

Dynamic facet name, regex=/nic_io_write_kbs_\d+/

NIC Kbytes written

Facet only available if nicstats parameter is true.

nic_speed_N (int)

Performance metric type: none

Dynamic facet name, regex=/nic_speed_\d+/

Speed of the NIC (e.g. 10/100/1000)

Facet only available if nicstats parameter is true.

nic_duplex_N (bool)

Dynamic facet name, regex=/nic_duplex_\d+/

True when NIC is in full duplex, false otherwise

Facet only available if nicstats parameter is true.

agent.mon.xenPoolMonitor¶

Monitor a Xen pool master for availability

Monitors the Xen pool master for availability, response time, number of hosts and hosts that are deemed dead. If the pool master specified is incorrect this monitor automatically connects to the real pool master and adds a facet value to specify the real master (MA also logs a message to this effect).

To use, declare a monitor like this in the manifest:

<Monitor name="xenPoolMon" type="agent.mon.xenPoolMonitor">
  <Parameter name="server">ceres</Parameter>
  <Parameter name="usr">root</Parameter>
  <Parameter name="pwd">secret</Parameter>
</Monitor>

Parameters¶

server (string)

The hostname, IP address or FQDN of any host in the pool

Preferably this is the pool master.

usr (string)

Session username

By default Xen credentials are the root username and password.

pwd (string): Session password

Facets¶

available (bool)

Performance metric type: twgauge

True if server was contacted and false otherwise

errorInfo (string): Error message if there were issues getting the data

responseTime (int)

Performance metric type: gauge

Response time for the call

actualMaster (string)

If server is not the master, this contains the master

If the server parameter was not the pool master, this facet specifies the URL of the master MA did log into.

numHosts (int)

Performance metric type: none

Number of hosts in the pool

numDeadHosts (int)

Performance metric type: none

Number of dead hosts in the pool

deadHostNames (string)

List of dead host names

If numDeadHosts > 0, this is a list of dead host names

agent.net.expect¶

TCP expect monitor for generic text-based protocol monitoring

New in version 7.1.

This monitor can be used to execute a programmed dialogue with a TCP service. The dialogue is written in a small Domain Specific Language (DSL) which specifies which text to send and receive.

An expect script consists of a number of expressions each on a line by themselves. Leading and trailing whitespace is allowed, but any leading whitespace must be exactly the same for each line. Comments can be written after the # character, either on a line by itself or on the same line as an expression. Each expression is a simple function call.

This is best explained by an example:

# This is a comment
expect(r'FTP server')
send('USER anonymous\r\n')
expect(r'password.?')         # An inline comment
send('PASS me@example.com')
expect(r'Login successful')
disconnect()

The Expect Domain Specific Language¶

This mini-language is syntactically a subset of Python’s syntax and is parsed by Python’s parser. Practically this means you have function calls and string arguments. Strings can be enclosed in either single or double quotes and have an optional r prefix which makes them “raw” strings. This is especially useful for strings containing special characters like \n which should not be interpreted.

There are only 3 functions in this DSL:

send(string):

Send a data to the remote host. No data will be received during this call.

Note that many services will expect you to end the data you have send with the appropriate newline characters. Many internet services use \r\n for this.

expect(regex):

Receive data from the remote host until the regular expression matches. It is highly recommended to use raw strings here by prefixing the string regular expression with an r.

Note that you should avoid using the ^ and & special characters. They can not be used to match newlines since the monitor is working on a stream. Instead you should use the correct newline characters depending on the service. Many internet services use \r\n as newline characters.

See appendix Regular Expression Syntax for details of the regular expression syntax.

disconnect():

This function takes no arguments, it will close the connection to the remote host. If you do not call this function the connection will stay open until the timeout occurs or until the remote closes the connection.

Note

This monitor is not available on Windows platforms

Parameters¶

host (string): The hostname or IP address to connect to

port (string): The TCP port to connect to

script (string)

The script this monitor will execute

This parameter must contain the script used to interact with the remote TCP socket. See the monitor description above for details on the syntax and functions available in this DSL.

Note that you can store the script in an external file and include it using XInclude if you wish. This makes no difference whatsoever as to how the monitor sees the script. E.g.:

<Parameter name="script">
  <xi:include href="$AS_HOME/etc/my_service.expect"
              encoding="utf-8"
              parse="text"/>
</Parameter>

However do not confuse the XInclude encoding parameter with the encoding parameter of the monitor.

timeout (int): Optional (default: 3). The maximum time to wait, in seconds, for a response

transcript (bool)

Optional (default: true). Whether to save the dialogue transcript in a facet

When enabled this will created the transcript facet with the full dialogue between the remote server and monitor.

encoding (string)

Optional (default: ASCII). The encoding to use for decoding received data

Since the monitor is unicode-aware the expect script in the script parameter is read and interpreted as unicode text by the monitor. However since the TCP socket transport handles bytes this unicode text needs to be encoded to bytes before being send and any received data needs to be decoded back to unicode. This parameter specified the encoding to be used for this encoding and decoding. Valid values are normal encodings like ascii, utf-8, latin-1 etc.

encoding_error (string)

Optional (default: ignore). How to handle encoding/decoding errors

As explained for the encoding parameter this monitor needs to encode and decode the data send over the wire. This parameter specifies how to handle errors in the encoding or decoding. There are several possible values:

Strict :	When and error occurs the monitor run will be aborted. The decoding error will be logged both in the logfile and in the error facet.
Ignore :	Will silently ignore errors. If random characters go missing this is probably the reasons.
Replace :	Any encoding errors will result in the unicode replacement character U+FFFD being used.

Facets¶

status (string)

The status of the sample

If the expect script executed correctly this will be ok. Otherwise this can contain values like timed out, remote disconnected, connection refused etc.

ip (string)

The IP address which the monitor connected to

When using a hostname you may not always know which endpoint the monitor might connect too. This facet tells you the IP address which was connected too.

duration (int)

Performance metric type: gauge

The total time, in milliseconds, a connection was established

transcript (string): The transcript of the dialogue, if transcript was true

txSize (int)

Performance metric type: gauge

The number of bytes sent

rxSize (int)

Performance metric type: gauge

The number of bytes received

txSpeed (int)

Performance metric type: gauge

The average speed at which data was sent (bytes/s)

Note that the timing resulution for this calculation is one micro-second so there is a maximum speed the monitor will report for a given number of bytes.

rxSpeed (int)

Performance metric type: gauge

The average speed at which data was received (bytes/s)

Note that the timing resulution for this calculation is one micro-second so there is a maximum speed the monitor will report for a given number of bytes.

error (string): If an error occurs this facet will contain details

agent.net.icmp¶

ICMP Echo monitor

New in version 2.6.0.

This is a classic “ping” monitor which sends ICMP Echo-Request packets to a host and looks for returned ICMP Echo-Reply packets.

Note

For this monitor asagent needs to be running as root. On systems with fine-grained capability permissions it might be sufficient to give asagent permissions for raw sockets and/or icmp messages.

An example of achieving this on Linux is by giving the CAP_NET_RAW capability to the Abilisoft python binary:

# setcap CAP_NET_RAW+pie /opt/abilisoft.com/thirdparty/python27/python

On Solaris one way to achieve this is by giving a user the required permissions:

# usermod -K defaultpriv=basic,net_icmpaccess my_user

Changed in version 2.6.4: On Solaris 10 this monitor now only needs the PRIV_NET_ICMPACCESS privilege.

Changed in version 7.1: This now supports ICMPv6 so IPv6 endpoints can be pinged.

Note

This monitor is not available on Windows platforms

Parameters¶

hostgroup (bool)

Optional (default: false). Whether to use a hostgroup or just host

This controls how the dest parameter gets interpreted. When false it will be regarded as a single host name or IP address. When true it will be regarded as the name of a defined <hostgroup> tag.

details (bool)

Optional (default: true). Whether to record detailed ping results or just alivenes

When true all ping details will be recorded as facets. When false however only the alive facet will be created.

dest (string): Destination, IP address or hostname

timeout (int)

Optional (default: 10). Maximum time to wait for a reply (in seconds)

If no reply is received in this time the packet is considered lost.

count (int): Optional (default: 3). The number of Echo-Requests to send

interval (int): Optional (default: 1). Number of seconds, to wait between sending Echo-Requests

size (int)

Optional (default: 64). The size of the ICMP Echo-Request package in bytes

The size specified is the total package size including the headers. Note that currently the monitor can not deal with fragmented IP packets so you must make sure the total size of the IP packet does not exceed the smallest MTU of the path between the agent and the destination. To know the total IP packet size you need to add 20 bytes accounting for the IP header size.

Facets¶

alive (bool)

Performance metric type: twgauge

Whether the remote host is alive

The remote host is considered alive if at least one reply was received. When the details parameter is set to false this is the only facet created.

host (string)

The hostname or IP address of the host pinged

When using hostgroups this facet is useful to kno which host the alive facet was for.

time (int)

Performance metric type: gauge

Total time in miliseconds

This is the time from the first Echo-Request to the last Echo-Reply, so if you have a count greater than 1 it will be affected by the interval parameter.

minrtt (int)

Performance metric type: gauge

Minimum Round Trip time in miliseconds

The minimum Round Trip Time (RTT) of of all the (Echo-Request, Echo-Reply) pairs in milliseconds. The RTT is the time between sending the Echo-Request and receiving the Echo-Reply.

maxrtt (int)

Performance metric type: gauge

Maximum Round Trip Time in miliseconds

avgrtt (int)

Performance metric type: gauge

Average Round Trip Time in miliseconds

lost (int)

Performance metric type: tally

Number of packets with no reply

The number of Echo-Request packets which did not receive an Echo-Reply in the specified timeout.

error (string)

Error description in case of a problem

If there is an error, e.g. name resultion failed, then the probem will be described in this facet.

Notes¶

This monitor needs to know the IP address of every host, but allows specifying a hostname too. Note however that when configured using a hostname the monitor needs to resolve the hostname every time it runs.

agent.net.web¶

Web Monitor to perform both protocol and web-page monitoring

New in version 7.0.

Changed in version 7.1: This monitor has had a major overhaul and is no longer compatible with the version shipped in 7.0.

Monitor an HTTP/HTTPS endpoint. This monitor is a combined protocol and web page monitor and is able to perform HTTP and HTTPS requests using various HTTP verbs, asynchronously on either a single URL or a list of URLs. It’s functionality includes the ability to:

Access resources behind HTTP basic and digest authentication as well as single sign on (SSO) systems.
Perform HTTP GET, HEAD and POST requests.
Operate via a proxy.
Follow redirects (can be disabled).
Perform requests with specific header and body data.
Perform SSL certificate validation.
Inspect content or detect changes in the content.

Note

This monitor is not available on RHEL 3 and Windows.

Parameters¶

url (string)

URL of the resource to request

This contains one or more URLs to use as endpoints. URLs must start with the scheme (http:// or https://). And if they end in whitespace they must use RFC 2396 encoding (%20).

If specifying more than one URL they must be separated by newlines.

auth (string)

Optional. The type of authentication to use

This can be NONE (default), BASIC, DIGEST or SSO. In all cases the credentials parameter is also required and for SSO the ssourl parameter is needed as well.

credentials (string)

Optional. The name of the credentials element to use

If an authentication method needs user credentials these are extracted from a <credentials/> element. This parameter specifies the name of the credentials element to use.

ssourl (regex)

Optional. The URL of the page providing the SSO login form

When using SSO authentication this parameter specifies the URL of the page providing the login form as a regular expression. This is needed so the monitor can notice when it got redirected to the login page and submit it’s credentials.

httpverb (string)

Optional (default: GET). The HTTP verb to use in the request

Currently the supported verbs are GET, HEAD and POST.

headers (string)

Optional. Head data to use in the request

JSON encoded head data (note the use of double quotes), e.g. {“Accept”: “text/plain”} By default the header “cache-control”: “no-cache” is used, this can be overridden by specifying a different value for “cache-control”.

Note that you can not use multiple keys with the same header field-name. If this is required you must concatenate the field values as a comma-separated list as explained in section 4.2 of RFC 2616.

data (string)

Optional. Data to send in the request body

This is normally used to send the data in e.g. a POST or PUT request.

Note that since this data is specified in the XML file, which has it’s own encoding specified, it will be seen as unicode data by asagent. Therefore asagent will encode it as specified by the data_encoding parameter.

Do not forget to set the correct Content-Type header in the headers parameter when adding data to a request. The monitor can not do this automatically.

data_encoding (string)

Optional (default: x-www-form-urlencoded). How to encode the data sent in the request body

Since any data specified in the data parameter is read by asagent as unicode text it needs to be encoded to bytes for HTTP. This specifies the encoding which should be used, e.g. ascii, utf-8, latin-1, cp1140 etc.

One special encoding is also possible: x-www-form-urlencoded, in this case the data parameter must contain a JSON encoded object with the form fields encoded as members. The form fields will then be encoded using the application/x-www-form-urlencoded method. This is also the only case in which you do not need to specify the Content-Type header in the headers parameter, it will be added automatically.

If you want to use multi-value form fields simply use a sequence of strings as the value of a member pair and a field=value pair will be created for each value in order.

verify_certs (bool)

Optional (default: true). Whether to check SSL certificates

If disabled the SSL certificate chain will not be checked and hence invalid certificates will be accepted. If enabled an invalid certificate from the server will mean the HTTP request is aborted and an error facet will be created.

cacerts (path)

Optional (default: $AS_HOME/etc/cacerts.pem). Path to a PEM formatted SSL certificate file

When the verify_certs parameter is set to true this file must contain the required PEM-formatted Certification Authority (CA) certificates to validate the chain (multiple certificates can simply be concatenated together).

By default asagent ships with a version of Mozilla’s bundle of root certificates.

Warning

The default root certificates bundle may not be suitable or outdated

The default bundle is here for your convenience but there is no update process for it so may contain certificates which have been revoked. Using this bundle as is can be a potential security risk. You should manage your own certificate bundle to ensure you trust all the root certificates.

follow_redirects (bool): Optional (default: true). Whether to follow redirects

timeout (int)

Optional (default: 10). Timeout in seconds

Amount of time to wait for a response from the server. If no response was received in this time the connection is terminated and no response will be available.

regex (regex)

Optional. Regular expression to match in the resource content

When supplying a regular expression it will be matched on the resource content returned by the server. The number of matches will then be available in the reMatchCount facet. The actual matched content will not be available.

headerfields (string)

Optional. List of header fields to record as facets

Normally the headers from the response are not accessible. But this parameter allows you to specify a comma-separated list of header fields to record as facets. E.g. Content-Length, Age, Content-Location. These will appear as facets like hdr_ContentLength, hdr_Age, hdr_ContentLocation.

certfields (string)

Optional. List of SSL certificate fields to record as facets

Normally the fields from the server’s SSL certificate are not accessible. But this parameter allows you to specify a comma-separated list of certificate fields to record as facets, e.g. notAfter, version which will result in facets as cert_notAfter, cert_version etc.

Some fields in the certificate, such as subject, can contain other fields to access these use a dot (.) to separate them, e.g.: subject.description which will result in a facet named cert_subject_description.

hashcontent (bool)

Optional (default: false). Whether to take a hash of content of the page

When enabled this creates the contentHash facet which will contain an MD5 hash of the HTTP response’s body. This is useful if you want to detect if the contents of a page has changed.

http_proxy (string)

Optional. The proxy to use for HTTP requests

When set this must be the IP address and port of the HTTP proxy to use, e.g. 10.10.1.10:1234. You can also use HTTP Basic Authentication with the proxy using the http://user:password@host/ syntax, e.g. http://me:secret@10.10.1.10:1234/.

https_proxy (string)

Optional. The proxy to use for HTTPS requests

This works identical as the http_proxy parameter but is used for HTTPS connections.

Facets¶

url (string): The URL of the retrieved resource

responseCode (int): HTTP response code

responseMsg (string): HTTP response message

responseTime (int)

Performance metric type: gauge

Resource load time in milliseconds

Note that when following redirects this is the total time from the request of the first resource to the response of the last resource.

Also note that when SSO authentication is enabled, the time spent performing the authentication is not included in the total response time.

responseSize (int)

Performance metric type: gauge

Size of request response in bytes

contentHash (string)

Checksum of the resource content

This facet is only available if the hashcontent parameter is true.

redirectCount (int)

Performance metric type: gauge

Number of redirects followed

reMatchCount (int)

Performance metric type: gauge

Number of matches from the regular expression

This facet is only available if the regex parameter is used.

hdr_NAME (string)

Dynamic facet name, regex=/hdr_\w+/

Value of requested header field

The facet name will be hdr_NAME where NAME is the field name of a header requested by the headerfields parameter.

cert_NAME (string)

Dynamic facet name, regex=/cert_\w+/

Value of requested SSL cert field

The facet name will be cert_NAME where NAME is the field name of a certificate field requested by the certfields parameter. When the field is nested inside another field underscore will be used as a a separator for example cert_subject_country

error (string)

Textual description of any errors with fetching the resource

This facet is created when there has been an error while fetching the resource. This can range from servers not being available or connections being refused to invalid SSL certificates and missing headers or certfields requested by the headerfields and certfields parameters.

agent.snmp.disk¶

Remote disk monitor using SNMP

Parameters¶

snmp_host (string)

SNMP agent to connect too

This must be in the form of hostname[:port] where the port is the optional port number (defaults to 161) and hostname can either be a DNS name or an IPv4 address.

snmp_version (string): SNMP version to use: 1, 2c or 3

snmp_community (string)

Optional (default: public). Community string to use for SNMP v1 and v2c

The community string to use when connection via SNMPv1 or SNMPv2c

snmp_secname (string): Optional (default: ). The security name for SNMPv3 USM

snmp_seclevel (string)

Optional (default: ). The security level for SNMPv3

When using SNMPv3 you need to specify the security level, which must be one of “noAuthNoPriv”, “AuthNoPriv” and “authPriv”.

snmp_authkey (string): Optional (default: ). The SNMPv3 authentication key

snmp_privkey (string): Optional (default: ). The SNMPv3 privacy key

snmp_authproto (string): Optional (default: MD5). The SNMPv3 authentication protocol to use

snmp_privproto (string): Optional (default: DES). The SNMPv3 privacy protocol to use

regex (regex)

Optional (default: .)*. Regular expression to match disk name

All disks matching this regular expression will be monitored. The process names will be matched against hrStorageDescr. Only fixed disks will be considered by default, see the local parameter for enabling networked disks.

match_multiple (bool)

Optional (default: true). If the regex parameter can multiple disks

This defines the behaviour when the regex parameter matches multiple disks. When set to true the monitor will monitor all disks matched. When set to false only one of the matching disks will be monitored and a warning will be logged.

It also defines the behaviour of how to look for disks: when set to true the entire list of available disks will be scanned on each sampler run, which can be a minor preformance hit. When set to false the entire process list will only be scanned if the disk is not found.

local (bool)

Optional (default: true). Whether to include network disks or not

Only when this parameter is set to false will networked disks be monitored on the server. This is to avoid long network timeouts in case you do not care about networked disks.

Facets¶

name (string)

The name of the disk

mib-2.host...hrStorageDescr

bytesTotal (int)

Performance metric type: none

The size of the disk in bytes

mib-2.host...hrStorageSize

bytesUsed (int)

Performance metric type: gauge

The number of bytes used

mib-2.host...hrStorageUsed

bytesFree (int)

Performance metric type: gauge

The number of unused bytes

percentUsed (float)

Performance metric type: gauge

Percentage of total space which is used

percentFree (float)

Performance metric type: gauge

Percentage of total space which is available

agent.snmp.mem¶

Remote memory monitor using SNMP

Parameters¶

snmp_host (string)

SNMP agent to connect too

This must be in the form of hostname[:port] where the port is the optional port number (defaults to 161) and hostname can either be a DNS name or an IPv4 address.

snmp_version (string): SNMP version to use: 1, 2c or 3

snmp_community (string)

Optional (default: public). Community string to use for SNMP v1 and v2c

The community string to use when connection via SNMPv1 or SNMPv2c

snmp_secname (string): Optional (default: ). The security name for SNMPv3 USM

snmp_seclevel (string)

Optional (default: ). The security level for SNMPv3

When using SNMPv3 you need to specify the security level, which must be one of “noAuthNoPriv”, “AuthNoPriv” and “authPriv”.

snmp_authkey (string): Optional (default: ). The SNMPv3 authentication key

snmp_privkey (string): Optional (default: ). The SNMPv3 privacy key

snmp_authproto (string): Optional (default: MD5). The SNMPv3 authentication protocol to use

snmp_privproto (string): Optional (default: DES). The SNMPv3 privacy protocol to use

collapse (bool)

Optional (default: false). Whether to collapse multiple memory entries

It is possible for a remote system to show it’s memory as multiple distict entries when this makes sense for the system. By default each entry will get a separate sample but when setting this parameter to true all values will be aggregated into one and only one sample will be created.

Facets¶

bytesTotal (int)

Performance metric type: none

The size of the memory in bytes

mib-2.host...hrStorageSize

bytesUsed (int)

Performance metric type: gauge

The number of bytes used

mib-2.host...hrStorageUsed

bytesFree (int)

Performance metric type: gauge

The number of unused bytes

percentUsed (float)

Performance metric type: gauge

Percentage of total space which is used

percentFree (float)

Performance metric type: gauge

Percentage of total space which is available

agent.snmp.proc¶

Remote process monitor using SNMP

Parameters¶

snmp_host (string)

SNMP agent to connect too

This must be in the form of hostname[:port] where the port is the optional port number (defaults to 161) and hostname can either be a DNS name or an IPv4 address.

snmp_version (string): SNMP version to use: 1, 2c or 3

snmp_community (string)

Optional (default: public). Community string to use for SNMP v1 and v2c

The community string to use when connection via SNMPv1 or SNMPv2c

snmp_secname (string): Optional (default: ). The security name for SNMPv3 USM

snmp_seclevel (string)

Optional (default: ). The security level for SNMPv3

When using SNMPv3 you need to specify the security level, which must be one of “noAuthNoPriv”, “AuthNoPriv” and “authPriv”.

snmp_authkey (string): Optional (default: ). The SNMPv3 authentication key

snmp_privkey (string): Optional (default: ). The SNMPv3 privacy key

snmp_authproto (string): Optional (default: MD5). The SNMPv3 authentication protocol to use

snmp_privproto (string): Optional (default: DES). The SNMPv3 privacy protocol to use

regex (regex)

Regular expression to match process

All processes matching this regular expression will be monitored. The samples of matching processes will have different sub-IDs based on the process ID of the process. The expression is matched against the full process name, i.e. the concatenation of hrSWRunPath or hrSWRunName and hrSWRunParameters.

match_multiple (bool)

Optional (default: true). If the regex parameter can multiple processes

This defines the behaviour when the regex parameter matches multiple processes. When set to true the monitor will monitor all processes matched. When set to false only one of the matching processes will be monitored and a warning will be logged.

It also defines the behaviour of how to look for processes: when set to true the entire process list will be scanned on each sampler run, which can be a minor preformance hit. When set to false the entire process list will only be scanned if the process is not found.

Facets¶

pid (int)

The process ID

mib-2.host...hrSWRunIndex

command (string)

The full command line, when possible

This facets attempts to create the full command line by combining mib-2.host...hrSWRunPath (or mib-2.host...hrSWRunName if hrSWRunPath is empty) with mib-2.host...hrSWRunParameters.

name (string)

Name of program

mib-2.host...hrSWRunName

executable (string)

The executable, including it’s path if possible

mib-2.host...hrSWRunPath

args (string)

The argument passed to the process

mib-2.host...hrSWRunParameters

status (string)

The status of the process

One of “running”, “runnable”, “notRunnable” or “invalid”.

agent.snmp.sysinfo¶

Remote system info using SNMP

Parameters¶

snmp_host (string)

SNMP agent to connect too

This must be in the form of hostname[:port] where the port is the optional port number (defaults to 161) and hostname can either be a DNS name or an IPv4 address.

snmp_version (string): SNMP version to use: 1, 2c or 3

snmp_community (string)

Optional (default: public). Community string to use for SNMP v1 and v2c

The community string to use when connection via SNMPv1 or SNMPv2c

snmp_secname (string): Optional (default: ). The security name for SNMPv3 USM

snmp_seclevel (string)

Optional (default: ). The security level for SNMPv3

When using SNMPv3 you need to specify the security level, which must be one of “noAuthNoPriv”, “AuthNoPriv” and “authPriv”.

snmp_authkey (string): Optional (default: ). The SNMPv3 authentication key

snmp_privkey (string): Optional (default: ). The SNMPv3 privacy key

snmp_authproto (string): Optional (default: MD5). The SNMPv3 authentication protocol to use

snmp_privproto (string): Optional (default: DES). The SNMPv3 privacy protocol to use

Facets¶

descr (string)

System description

mib-2.system.sysDesc

oid (string)

Vendor OID identifying this system

mib-2.system.sysObjectID

contact (string)

System contact

mib-2.system.sysContact

location (string)

System location

mib-2.system.sysLocation

uptime (int)

Performance metric type: counter

System uptime in seconds

mib-2.host.hrSystem.hrSystemUptime

processes (int)

Performance metric type: gauge

Number of processes currently running

mib-2.host.hrSystem.hrSystemProcesses

cpucount (int)

Performance metric type: none

Number of processors on the system

numusers (int)

Performance metric type: gauge

Number of users on the system

mib-2.host.hrSystem.hrSystemNumUsers

agent.snmp.vmem¶

Remote virtual memory monitor using SNMP

This monitor uses SNMP to monitor virtual memory from remote devices. On conventional servers this is often defined as “swap space”.

Parameters¶

snmp_host (string)

SNMP agent to connect too

This must be in the form of hostname[:port] where the port is the optional port number (defaults to 161) and hostname can either be a DNS name or an IPv4 address.

snmp_version (string): SNMP version to use: 1, 2c or 3

snmp_community (string)

Optional (default: public). Community string to use for SNMP v1 and v2c

The community string to use when connection via SNMPv1 or SNMPv2c

snmp_secname (string): Optional (default: ). The security name for SNMPv3 USM

snmp_seclevel (string)

Optional (default: ). The security level for SNMPv3

When using SNMPv3 you need to specify the security level, which must be one of “noAuthNoPriv”, “AuthNoPriv” and “authPriv”.

snmp_authkey (string): Optional (default: ). The SNMPv3 authentication key

snmp_privkey (string): Optional (default: ). The SNMPv3 privacy key

snmp_authproto (string): Optional (default: MD5). The SNMPv3 authentication protocol to use

snmp_privproto (string): Optional (default: DES). The SNMPv3 privacy protocol to use

collapse (bool)

Optional (default: false). Whether to collapse multiple memory entries

It is possible for a remote system to show it’s memory as multiple distict entries when this makes sense for the system. By default each entry will get a separate sample but when setting this parameter to true all values will be aggregated into one and only one sample will be created.

Facets¶

bytesTotal (int)

Performance metric type: none

The size of the memory in bytes

mib-2.host...hrStorageSize

bytesUsed (int)

Performance metric type: gauge

The number of bytes used

mib-2.host...hrStorageUsed

bytesFree (int)

Performance metric type: gauge

The number of unused bytes

percentUsed (float)

Performance metric type: gauge

Percentage of total space which is used

percentFree (float)

Performance metric type: gauge

Percentage of total space which is available

agent.sys.proc¶

Monitor processes

This monitor collects information on one or more particular processes. Each process selected will be monitored individually and independently.

When running for the first time a sample will be created for each matched process with the process’ detail. The process’ PID will be used as the sample sub-ID.

On any consecutive runs the same samples will be created. But when monitoring multiple processes, see match_multiple below, a sample with just a single error facet will be created for each process which no longer exists but was available in the previous monitoring run. Likewise for each newly discovered process an additional sample with a single error facet is created, this is on top of the normal process sample.

If simply checking for aliveness it is recommended to use the pid facet. When checking for a new or disappeared process using the pid facet is recommended as well.

Parameters¶

regex (regex)

Regular expression to select the processes by command line

The regular expression used to select the processes is matched agains the full command line it was invoked with, including it’s name and all parameters. You can not rely on the full path name to the binary to be included however, this depends on how the process was invoked. See also the match_full parameter which can influence how regular expression matching behaves.

match_multiple (bool)

Optional (default: true). Whether to select multiple processes to monitor

If enabled all processes matched by the regex parameter are monitored. However if disabled only one process will monitored even if multiple processes matched the regular expression. Which process is selected in this case can depend on other parameters but is random in the absence of those.

Note that this settings has a preformance impact, when matching multiple processes the monitor must scan all running processes on every sample run to see if there are any new processes. This uses more resources then just checking for a running process.

match_full (bool)

Optional (default: false). Whether use the full command line for regex matching

On some operating systems, e.g. Solaris, it is rather expensive to extract the full command line of a running process. Instead the OS gives a shortened version by default. For performance reasons the monitor defaults to only using the shortened version. In the rare case where this is not sufficient to select the process this parameter will need to be switched on.

Do note that on some OSes this will have no influence and the full commandline will be used in all cases.

groupLeader (bool): Optional (default: false). Only select a process if it is a group leader

Facets¶

pid (int): Process ID

ppid (int): Parent process ID

sTime (int)

Performance metric type: none

POSIX timestamp of the start time

time (float)

Performance metric type: counter

Total CPU time of a process in seconds

percentCpu (float)

Performance metric type: gauge

Percentage of 1 CPU core used by this process

Note that on SMP and/or multicore systems this can be larger then 100%.

percentCpuAvg (float)

Performance metric type: gauge

Percentage of all available CPU used by this process

Alternatively this can be described as the CPU percentage used by this process averaged by the number of cores. This means regardless of the number of cores the maximum percentage will be 100%.

percentCpuLife (float)

Performance metric type: gauge

Percent CPU usage over the process lifetime

residentSize (int)

Performance metric type: gauge

RSS memory in bytes

virtualSize (int)

Performance metric type: gauge

VSZ memory in bytes

uid (int): The uid of the process owner (UNIX only)

user (string): Username of process owner

executable (string): Path to the executable image

command (string)

The command invoked

This is the first argument of the command line the process was invoked with, which may be different from the executable finally run.

args (string)

Process arguments, excluding the command itself

This is the remainder of the command line the process was invoked with, excluding the first argument which is the command itself.

argCount (int): Process argument count

argN (string)

Dynamic facet name, regex=/arg\d+/

The N*th argument, 1 <= *N <= argCount

Multiple facet values containing the value of each process argument from “arg0” to “arg(argCount-1)”.

pgrp (int): Process Group ID (UNIX only)

sid (int): Session ID (UNIX only)

error (string)

An error message in case a problem occurred

There are three cases in which this facet occurs, in each case a sample will be created with just this facet.

No process matching the parameters was found.
A process being monitored is no longer running.
A new process which matches the parameters was found and is added to the monitored processes. In this case a second sample containing the normal facets for the process is created as well.

zoneid (int): The zone ID when running on Solaris 10

zonename (string): The zone name when running on Solaris 10

mtime:	Most recent mtime.
ctime:	Most recent ctime.
atime:	Most recent atime.
alpha:	Alphabetically, from the base name of the log-file (i.e. no leading path).
custom:	Custom template, see the sorttemplate parameter.

-X:	Run in AgentX subagent mode instead of SNMP master agent
-x:	The address to use for a connection to the AgentX master
-n:	Specifies a different application name instead of “snmpd”
-r:	Do not require root permissions
-C:	Ignore configuration files others the specified by `-c`
-c:	Use a specific configuration file

Navigation

Table Of Contents

Previous topic

Next topic

Quick search

Monitor Types¶

agent.cpu.cpuUsage¶

Parameters¶

Facets¶

Notes¶

agent.cpu.loadAvg¶

Parameters¶

Facets¶

agent.disk.diskIO¶

Parameters¶

Facets¶

agent.disk.diskUsage¶

Parameters¶

Facets¶

agent.mem.bufferCache¶

Parameters¶

Facets¶

agent.mem.memUsage¶

Parameters¶

Facets¶

agent.mem.swapUsage¶

Parameters¶

Facets¶

agent.mon.dbMonitor¶

Parameters¶

Facets¶

Notes¶

Oracle Flavour¶

Aliveness-Test¶

Configuration¶

Defining a Monitor¶

Stored Procedures and Functions¶

Sybase Flavour¶

Aliveness-Test¶

Configuration¶

Troubleshooting¶

Defining a Monitor¶

Stored Procedures and Functions¶

PostgreSQL Flavour¶

Aliveness-Test¶

Configuration¶

Defining a Monitor¶

Stored Procedures and Functions¶

DB2 Flavour¶

Aliveness-Test¶

Configuration¶

Defining a Monitor¶

Stored Procedures and Functions¶

ADO Flavour¶

Aliveness-Test¶

Configuration¶

Defining a Monitor¶

Stored Procedures and Functions¶

agent.mon.dirMonitor¶

Parameters¶

Facets¶

agent.mon.esxFolderMonitor¶

Parameters¶

Facets¶

agent.mon.esxHostInfoMonitor¶

Parameters¶

Facets¶

agent.mon.esxHostMonitor¶

Parameters¶

Facets¶

agent.mon.esxServiceMonitor¶

Parameters¶

Facets¶

agent.mon.fileMonitor¶

Parameters¶

Facets¶

agent.mon.heartbeat¶

Parameters¶

Facets¶

Notes¶