voxel.devices.monitors.create

Create a new monitor on a device.

Parameters

device_id (required)
Numeric Voxel device id, available from voxel.devices.list
monitor_type (required)
Type of monitor. One of: ping, http, ftp, smtp, imap, pop3, snmp_monitor, custom, server_metrics, bandwidth, power, apache_status, mysql_status

Connection Settings

ip_address (required)
IP Address to connect to when monitoring device. (valid for: every type except power)
port (optional)
Port to connect to when monitoring device. Required for type custom. (valid for: http, ftp, smtp, imap, pop3, custom)
ssl (optional)
Indicates whether the monitor should use SSL or not when attempting a connection. One of: 0, 1. (valid for: http, ftp, smtp, imap, pop3, snmp, custom)
username (optional)
Username to send in monitor request. (valid for: http, ftp, imap, pop3)
password (optional)
Password to send in monitor request. (valid for: http, ftp, imap, pop3)

Notification Settings

notification_delay (optional)
Time in seconds to delay sending the notification email after the first failure of monitor.
notification_email (optional)
Comma separated list of email addresses to send monitor alerts to.
notification_interval (optional)
Time in seconds to wait before repeating a notification message on a down monitor.
staff_notification_level (optional)
Alert level to indicate to Voxel Support Staff. One of: none, emergency, 911. Emergency is the default, and they are handled by on-duty support staff within minutes. 911 pages the entire support staff and should be used only in extreme situations.

apache_status

max_active_connections (optional)
Maximum number of active connections. (valid for: apache_status)

bandwidth

min_inbound_transfer_rate (optional)
Minimum transfer rate of inbound traffic, in bits per second. (valid for: bandwidth)
max_inbound_transfer_rate (optional)
Maximum transfer rate of inbound traffic, in bits per second. (valid for: bandwidth)
min_outbound_transfer_rate (optional)
Minimum transfer rate of outbound traffic, in bits per second. (valid for: bandwidth)
max_outbound_transfer_rate (optional)
Maximum transfer rate of outbound traffic, in bits per second. (valid for: bandwidth)
min_transfer_rate (optional)
Minimum transfer rate of total traffic, in bits per second. (valid for: bandwidth)
max_transfer_rate (optional)
Maximum transfer rate of total traffic, in bits per second. (valid for: bandwidth)

custom

action_0_type (optional)
Custom action for monitor. One of: send - send text string to server, sendline - send text string to server followed by newline, matchregex - wait for a line from server that matches this perl-style regex, matchexact - wait for a line from server that matches this text exactly. Can be any number of actions (action_0_type, ..., action_n_type). (valid for: custom)
action_0_value (optional)
Value for matching custom action. For send/sendline, this is the string to send. For matchregex/matchexact, this is the value to match against. 1 value per matching action type (action_0_value, ..., action_n_value). (valid for: custom)

ftp

test_file (optional)
Full path of file monitor should test for. (valid for: ftp)

http

http_request_method (optional)
Request method to use in HTTP monitor request. One of: HEAD, GET. Default is: HEAD. (valid for: http)
hostname (optional)
Hostname to send in monitor request. (valid for: http)
response_regex (optional)
Perl-style regular expression to match the server response against. (valid for: http)
test_url (optional)
URL to use in monitor requests. Default is: /. (valid for: http)

mysql_status

is_slave (optional)
Whether or not a MySQL instance is a replication slave. One of: 0, 1. Tests for running slave threads. (valid for: mysql_status)
max_slave_delay (optional)
Maximum delay in seconds for MySQL slave thread. This should only be set on replication slaves. (valid for: mysql_status)
min_slave_processing_rate (optional)
Minimum rate slave should be processing entries from the master, in writes per second. This should only be set on replication slaves. (valid for: mysql_status)
max_available_connections_used (optional)
Maximum percentage of available connections allowed in use. (valid for: mysql_status)

ping

max_packet_loss (optional)
Even if connection is made, trigger an alert if packet loss reaches this percentage. (valid for: ping)

power

min_power_draw (optional)
Minimum power that should be drawn from server, in Amps. (valid for: power)
max_power_draw (optional)
Maximum power that should be drawn from server, in Amps. (valid for: power)
min_available_power_used (optional)
Minimum percentage of available power used by server. (valid for: power)
max_available_power_used (optional)
Maximum percentage of available power used by server. (valid for: power)

server_metrics

min_cpu_used (optional)
Minimum percentage of CPU in use on system. (valid for: server_metrics)
max_cpu_used (optional)
Maximum percentage of CPU in use on system. On systems with multiple CPUs/cores, this can be greater than 100 (valid for: server_metrics)
min_cpu_io_wait_used (optional)
Minimum percentage of CPU in io-wait state on system. (valid for: server_metrics)
max_cpu_io_wait_used (optional)
Maximum percentage of CPU in io-wait state on system. On systems with multiple CPUs/cores, this can be greater than 100. (valid for: server_metrics)
min_disk_io_usage (optional)
Minimum percentage of Disk I/O in use on system. (valid for: server_metrics)
max_disk_io_usage (optional)
Maximum percentage of Disk I/O in use on system. (valid for: server_metrics)
min_disk_io_operations (optional)
Minimum I/O operations running on disk, in operations per second. (valid for: server_metrics)
max_disk_io_operations (optional)
Maximum I/O operations running on disk, in operations per second. (valid for: server_metrics)
max_disk_space_used (optional)
Maximum percentage of total disk space used on system. (valid for: server_metrics)
min_ram_used (optional)
Minimum RAM in use by system, in megabytes. (valid for: server_metrics)
max_ram_used (optional)
Maximum RAM in use by system, in megabytes. (valid for: server_metrics)
min_vmem_used (optional)
Minimum Virtual Memory in use on system, in megabytes. (valid for: server_metrics)
max_vmem_used (optional)
Maximum Virtual Memory in use on system, in megabytes. (valid for: server_metrics)
max_system_load (optional)
Maximum system load. (valid for: server_metrics)

snmp

snmp_community (optional)
SNMP community to use in monitor tests. (valid for: snmp)
snmp_timeout (optional)
Timeout to use in SNMP tests, in seconds. Minimum is .5, Maximum is 5. (valid for: snmp)
snmp_0_oid (optional)
OID to use in an snmp test on a monitor. Can be up to 5 per monitor (snmp_0_oid, snmp_1_oid, snmp_2_oid, snmp_3_oid, snmp_4_oid). (valid for: snmp)
snmp_0_regex (optional)
Perl-style regex to match the response against. Can be 1 per each OID in monitor (snmp_0_regex, ..., snmp_4_regex). (valid for: snmp)
snmp_0_min (optional)
Minimum value to test OID for. Can be 1 per each OID in monitor (snmp_0_min, ..., snmp_4_min). (valid for: snmp)
snmp_0_max (optional)
Maximum value to test OID for. Can be 1 per each OID in monitor (snmp_0_max, ..., snmp_4_max). (valid for: snmp)

Example Response

<rsp stat="ok">
<monitor id="1234" device_id="5678" state="down" type="http">
<ip_address>http</ip_address>
<port>80</port>
<staff_notification_level>emergency</staff_notification_level>
<notification_delay units="seconds">300</notification_delay>
<notification_interval units="seconds">3600</notification_interval>

<settings>
<setting name="ssl">0</setting>
<setting name="http_request_method">HEAD</setting>
</settings>
</monitor>
</rsp>

Notes

None

Method Specific Error Codes

100: Unknown device
The device_id passed in can't be matched to a valid device.
111: Invalid monitor type
The monitor_type passed in is not valid.