Welcome to docs.opsview.com

REST API: Status

Security level required:

Host group summary

Object type: hostgroup

Example GET
Request URL /rest/status/hostgroup
Response
{
    "list": [
        {
            "computed_state": "critical",
            "downtime": "2",
            "hostgroupid": "4",
            "hosts": {
                "down": {
                    "handled": "1",
                    "unhandled": "1"
                },
                "handled": "7",
                "total": "8",
                "unhandled": "1",
                "up": {
                    "handled": "6"
                }
            },
            "leaf": "0",
            "matpath": [
                {
                    "id": "1",
                    "name": "Opsview"
                },
                {
                    "id": "3",
                    "name": "UK"
                }
            ],
            "name": "Leaf",
            "services": {
                "computed_state": "unknown",
                "handled": "4",
                "ok": {
                    "handled": "1"
                },
                "total": "19",
                "unhandled": "15",
                "unknown": {
                    "handled": "3",
                    "unhandled": "15"
                }
            }
        },
        {
            "computed_state": "critical",
            "downtime": "2",
            "hostgroupid": "1",
            "hosts": {
                "down": {
                    "handled": "1",
                    "unhandled": "1"
                },
                "handled": "10",
                "total": "11",
                "unhandled": "1",
                "up": {
                    "handled": "9"
                }
            },
            "leaf": "0",
            "matpath": [],
            "name": "Opsview",
            "services": {
                "computed_state": "critical",
                "critical": {
                    "unhandled": "3"
                },
                "handled": "6",
                "ok": {
                    "handled": "3"
                },
                "total": "26",
                "unhandled": "20",
                "unknown": {
                    "handled": "3",
                    "unhandled": "17"
                }
            }
        }
    ],
    "summary": {
        "handled": "27",
        "host": {
            "down": "4",
            "handled": "17",
            "total": "19",
            "unhandled": "2",
            "up": "15"
        },
        "service": {
            "critical": "3",
            "handled": "10",
            "ok": "4",
            "total": "45",
            "unhandled": "35",
            "unknown": "38"
        },
        "total": "64",
        "totalhgs": "4",
        "unhandled": "37"
    }
}
Parameters
hostgroupid Includes this host group in list. Can be repeated. Note, this is for this one host group ID only.
parentid Includes all host groups with this parent. Can be repeated.
fromhostgroupid Will include all host groups from this point in the hierarchy “downwards”. Includes itself. Can be repeated.
host Filter hosts by this host name. Can be repeated.
servicecheck Filter services by this service check name. Can be repeated.
filter Either “handled” or “unhandled”. Filters services by this condition.
host_filter Either “handled” or “unhandled”. Filters host by this condition.
state Filters by services in this state. Expects the numeric id for state. Can be repeated.
host_state Filters by hosts in this state. Expects the numeric id for state. Can be repeated.
includeunhandledhosts If set to 1, will include hosts that are unhandled. Otherwise will only return services that are unhandled.
include_servicegroups If set to 1, will include service group information, with number of ok, warning, critical and unknown states.
only_leaves If set to 1, will only return host groups that are leaf host groups.
rows Returns this number of rows. Set to “all” to get all results. Defaults to “all”.
page Returns this page number if rows is set to a number. Defaults to 1st page.
cols Can specify columns to remove. Possible columns: leaf, matpath. Example: cols=-leaf,-matpath
order If set to “dependency”, will return order based on hierarchy, starting with the top first then depth first. Otherwise, returns back ordered by name.

Note: The “computed_state” keyword represents the highest state based on host state and service state. Specifically, this will return critical if the host is down or unreachable otherwise the service computed_state. This is available from Opsview 3.13.0.

Note: PUT, POST, and DELETE are not supported.

The “summary.totalhgs” value represents the number of host groups in this request, without any filtering. This means that if the value is > 0, the user has access to see host groups from this part of the host group tree. If the value is 0, then the user does not have access to this part of the host group tree.

Host summary

Object type: host

Example GET
Request URL /rest/status/host?host=opslave&host=opsview
Response
Parameters
hostgroupid Includes this host group in list. Can be repeated. Note, this will return all hosts in this hosgroupid and below in the hierarchy (so a hostgroupid of 1 effectively returns all hosts).
host Filter hosts by this host name. Can be repeated.
servicecheck Filter services by this service check name. Can be repeated.
filter Either “handled” or “unhandled”. Filters services by this condition.
host_filter Either “handled” or “unhandled”. Filters host by this condition.
state Filters by services in this state. Expects the numeric ID for state. Can be repeated.
state_type Filters by service state type. Expects either “0” (soft) or “1” (hard). Defaults to both.
host_state Filters by hosts in this state. Expects the numeric ID for state. Can be repeated.
host_state_type Filters by host state type. Expects either “0” (soft) or “1” (hard). Defaults to both.
includeextradetails If set, will include extra detail.
rows Returns this number of rows. Set to “all” to get all results. Defaults to “all”.
page Returns this page number if rows is set to a number. Defaults to 1st page.
include_reload_time If set to 1, then the summary data will include the last reload time of Opsview in epoch seconds.
only_with_children If set, then only hosts with at least 1 child are returned.
monitoredby If set, filter hosts if it is monitored by the monitoring server by this ID.

Note: The following attributes will only be returned if true. If the attribute does not exist, you can assume that the values are 0:

  • acknowledged = 1
  • flapping = 1

Note: PUT, POST, and DELETE are not supported.

Service list

Object type: service

Example GET
Request URL /rest/status/service
Response
{
    "list": [
        {
            "alias": "Opsview Master Server",
            "comments": "1",
            "current_check_attempt": "0",
            "downtime": "0",
            "icon": "opsview",
            "last_check": "1970-01-01 00:00:00",
            "max_check_attempts": "0",
            "name": "opsview",
            "num_interfaces": "0",
            "num_services": "6",
            "output": "Dummy output",
            "services": [
                {
                    "current_check_attempt": "1",
                    "downtime": "0",
                    "last_check": "2011-01-16 22:51:29",
                    "markdown": "0",
                    "max_check_attempts": "3",
                    "name": "Slave-node: opslave",
                    "output": "slave-node check with fake results",
                    "perfdata_available": "1",
                    "service_object_id": "219",
                    "state": "ok",
                    "state_duration": "9296782",
                    "state_type": "hard",
                    "unhandled": "0"
                },
                {
                    "current_check_attempt": "1",
                    "downtime": "0",
                    "last_check": "2011-01-16 22:52:34",
                    "markdown": "0",
                    "max_check_attempts": "3",
                    "name": "Slave-node: opslaveclusterA",
                    "output": "slave-node opslaveclusterA check with fake results",
                    "perfdata_available": "1",
                    "service_object_id": "220",
                    "state": "critical",
                    "state_duration": "9296717",
                    "state_type": "soft",
                    "unhandled": "1"
                }
            ],
            "state": "up",
            "state_duration": "1304515071",
            "state_type": "hard",
            "summary": {
                "computed_state": "critical",
                "critical": "1",
                "handled": "1",
                "ok": "1",
                "total": "2",
                "unhandled": "1"
            },
            "unhandled": "0"
        }
    ],
    "summary": {
        "handled": "2",
        "host": {
            "handled": "1",
            "total": "1",
            "unhandled": "0",
            "up": "1"
        },
        "service": {
            "critical": "1",
            "handled": "1",
            "ok": "1",
            "total": "2",
            "unhandled": "1"
        },
        "total": "3",
        "unhandled": "1"
    }
}
Parameters (includes the service object filtering parameters)
downtime_start_time & downtime_comment Filter based on downtime that matches these conditions.
filter Either “handled” or “unhandled”. Filters services by this condition.
host_filter Either “handled” or “unhandled”. Filters host by this condition.
state Filters by services in this state. Expects the numeric ID for state. Can be repeated.
state_type Filters by service state type. Expects either “0” (soft) or “1” (hard). Defaults to both.
host_state Filters by hosts in this state. Expects the numeric ID for state. Can be repeated.
host_state_type Filters by host state type. Expects either “0” (soft) or “1” (hard). Defaults to both.
includeperfdata If set, will add data re: the performance metrics for services that have performance information.
convertuom If set, will convert performance data into base units. Eg, if value=1500 and uom=MB, with this flag set, will return value=1500000000 uom=bytes.
includehandleddetails If set, will include acknowledgement information.
rows Returns this number of rows. Set to “all” to get all results. Defaults to “all”.
page Returns this page number if rows is set to a number. Defaults to 1st page.
order Can order the results. Can be repeated. Valid values (you can suffix with “_desc” to order descending):
  • state - Orders by service state. Host states have priority.
  • service - Orders by service name.
  • host - Orders by host name.
  • host_state - Orders by host state.
  • last_check - Orders by last check time.
  • last_state_change - Orders by last state change time.

Note: The following attributes will only be returned if true for a host or service. If the attribute does not exist, you can assume that the values are 0.

  • acknowledged = 1
  • flapping = 1

Note: The format of the last_check field has changed to being epoch seconds. To have the old behaviour, use the “format_datetime=1” URL parameter.

Note: PUT, POST, and DELETE are not supported.

Filtering service objects

There are common filtering parameters that can be used for filtering of service objects.

Parameter Description
hostgroupid Includes this host group in list and all hosts and services below. Can be repeated.
hostgroupname Includes this host group in list and all hosts and services below. Can be repeated. If a host group name is duplicated, all host groups will be considered.
hostname Filter hosts by this host name. Can be repeated. Can include the % parameter for wildcard matching - use %25 in the URL so it doesn't get escaped. The parameter “host” is considered the same, but “hostname” will be used in preference.
hostid Filter hosts by this host id. Can be repeated.
servicename Filter services by this service check name. Can be repeated. Can include the % character for wildcard matching - use %25 in the URL so it doesn't get escaped. The parameter “servicecheck” is considered the same, but “servicename” will be used in preference.
serviceid Filter services by this service id. Can be repeated.
hs Filter services that match this format: “hostname::servicename”. Must match exactly. Can be repeated.
keyword Filter services by keyword. Can be repeated.
monitoredby Filter by name of the monitored by server. Can be repeated.
htid Host template ID. Can be repeated.
bsid Business service ID. Can be repeated.
bcid Business component ID. Can be repeated.

Set service status

Object type: status

Example POST
Request URL /rest/status?svc.serviceid=1&svc.serviceid=2
Request data
{
    "comment": "This is a known unknown",
    "new_state": "0"
}
Response
{
    "list": {
        "hosts": [],
        "services": [
            {
                "hostname": "host1",
                "id": "1",
                "servicename": "service on host1"
            },
            {
                "hostname": "host2",
                "id": "2",
                "servicename": "service on host2"
            }
        ]
    },
    "summary": {
        "num_hosts": "0",
        "num_services": "2"
    }
}
Parameters
svc.serviceid The service ID to operate on. Can be specified multiple times.
state The state that should be applied to the services listed in service_selection. Expects the numeric ID for state.
comment Free text comment that should be given to the state change.

Note: GET, POST, and DELETE are not supported.

Viewport

A viewport is a summarised state of all the services tagged with a specific keyword.

Example GET
Request URL /rest/status/viewport
Response
{
    "list": [
        {
            "computed_state": "critical",
            "description": "All services handled",
            "downtime": null,
            "hosts": {
                "down": {
                    "handled": "1"
                },
                "handled": "1",
                "total": "1",
                "unhandled": "0"
            },
            "name": "allhandled",
            "services": {
                "computed_state": "unknown",
                "handled": "1",
                "total": "1",
                "unhandled": "0",
                "unknown": {
                    "handled": "1"
                }
            }
        }
    ],
    "summary": {
        "handled": "15",
        "host": {
            "down": "1",
            "handled": "12",
            "total": "12",
            "unhandled": "0",
            "up": "11"
        },
        "service": {
            "handled": "3",
            "total": "34",
            "unhandled": "31",
            "unknown": "34"
        },
        "total": "46",
        "unhandled": "31"
    }
}
Parameters
keyword Filter by these keywords. Can be repeated.
host Filter hosts by this host name. Can be repeated.
servicecheck Filter services by this service check name. Can be repeated.
filter Either “handled” or “unhandled”. Filters services by this condition.
host_filter Either “handled” or “unhandled”. Filters host by this condition.
state Filters by services in this state. Expects the numeric id for state. Can be repeated.
host_state Filters by hosts in this state. Expects the numeric id for state. Can be repeated.
rows Returns this number of rows. Set to all to get all results. Defaults to all.
page Returns this page number, if “rows” is set to a number. Defaults to first page.

Note: As you must login to the REST API, all queries are bound to a user, so effectively the public flag on each keyword is not relevant.

Note: The computed_state keyword represents the highest state based on host state and service state. Specifically, this will return critical if the host is down or unreachable, otherwise the service computed_state. In Opsview 4.6.3, this also considers whether the keyword has “exclude handled” set in its configuration - if so, when calculating the highest state, the highest state will ignore handled services and hosts. In versions of Opsview before 4.6.3, the configuration flag was ignored.

Note: PUT, POST, and DELETE are not supported.

Detailed viewport

URL: /rest/status/viewport/*

This is effectively a Services search, with keyword set to be the first argument.

Note: PUT, POST, and DELETE are not supported.

Performance metrics

Example GET
Request URL /rest/status/performancemetric
Response
{
    "list": [
        {
            "hostname": "opslave",
            "metricname": "age",
            "servicename": "Nagios Stats",
            "servicestate": "critical",
            "uom": "s",
            "value": "5"
        },
        {
            "hostname": "opsview",
            "metricname": "rta",
            "servicename": "TCP/IP - LAN",
            "servicestate": "unknown",
            "uom": "ms",
            "value": "25"
        },
        {
            "hostname": "winvpn",
            "metricname": "rta",
            "servicename": "TCP/IP - LAN",
            "servicestate": "unknown",
            "uom": "",
            "value": ""
        }
    ],
    "rows": "3",
    "total": "5"
}
Filtering parameters
hostgroupid Includes this host group in list. Can be repeated.
hostgroupname Includes this host group in list. If the name is associated with more than one host group, all will be included in the response. Can be repeated.
hostname Filter hosts by this host name. Can specify wildcards with ”%25”. Can be repeated.
hostid Filter hosts by this host id number. Can be repeated.
servicename Filter services by this service check name. Can specify wildcards. Can be repeated.
serviceid Filter services by this service id number. Can be repeated.
metricname Filter metrics by this metric name. Can be repeated.
hs Filter based on this host service. Of the form “hostname::servicename”. Can be repeated.
hsm Filter based on this host service metric. Of the form “hostname::servicename::metricname”. Can be repeated.
convertuom If set, will convert performance data into base units. Eg, if value=1500 and uom=MB, with this flag set, will return value=1500000000 uom=bytes.
Other parameters
rows Limit results by this many rows. Note: if ordering by value, Opsview needs to check for all services before sorting, so we recommend you filter the list of performance metrics to have a smaller set first.
order You can suffix with “_desc” to sort descending. You can specify multiple values to have secondary sorting (except when sorting by value):
  • hostname
  • servicename
  • metricname
  • value - If this is set, will order by value, then hostname, servicename. Values of empty strings will be sorted to the bottom of the list, regardless of ascending or descending.

It is possible for the value to be the empty string - this means the value is not available (for instance, if the service has a response without any performance data).

Note: PUT, POST, and DELETE are not supported.

Navigation
Print/export
Toolbox