Welcome to docs.opsview.com

REST API: Runtime

This section is for searching for live objects being monitored by Opsview. This is in the Runtime database, hence the URL path is /rest/runtime/{objecttype}.

Host and services

URL: /rest/runtime/service. Requires authentication - requires VIEWALL or VIEWSOME permission.

  • GET - Returns available objects, either grouped by host or grouped by service
  • POST, PUT, DELETE - Not implemented

Access control

VIEWALL allows all objects to be returned.

VIEWSOME allows objects to be returned where permission has been granted based on the access object selection.

Retrieving host or service lists

The same parameters as searching based on service filtering can be used.

Example GET
Request URL /rest/runtime/service?group_by=host&distinct=0
Response
{
    "allrows": "30",
    "list": [
        {
            "list": [
                "Another exception",
                "Coldstart",
                "Test exceptions"
            ],
            "name": "cisco"
        },
        {
            "list": [
                "Another exception",
                "Coldstart"
            ],
            "name": "cisco1"
        }
    ],
    "rows": "5",
    "total": "50"
}
Example GET
Request URL /rest/runtime/service?group_by=service&distinct=0
Response
{
    "allrows": "30",
    "list": [
        {
            "list": [
                "cisco",
                "cisco1",
                "cisco2",
                "cisco3",
                "cisco4"
            ],
            "name": "Another exception"
        }
    ],
    "rows": "5",
    "total": "50"
}
Example GET
Request URL /rest/runtime/service?group_by=host&distinct=1
Response
{
    "allrows": "12",
    "list": [
        {
            "name": "cisco"
        },
        {
            "name": "cisco1"
        },
        {
            "name": "cisco2"
        },
        {
            "name": "cisco3"
        },
        {
            "name": "cisco4"
        }
    ],
    "rows": "5",
    "total": "15"
}
Example GET
Request URL /rest/runtime/service?group_by=service&distinct=1
Response
{
    "allrows": "12",
    "list": [
        {
            "name": "Another exception"
        },
        {
            "name": "Check Loadavg"
        },
        {
            "name": "Check Memory"
        },
        {
            "name": "Coldstart"
        },
        {
            "name": "faked ok service"
        }
    ],
    "rows": "5",
    "total": "19"
}
Additional Parameters
rows Returns back this number of rows. Defaults to 50 rows.
group_by Returns results based on either host or service. Defaults to host.
distinct If set to 1, then only a distinct list of hosts or services are returned. This means you are searching for host names or service names rather than a host+service combination.
Response
rows The number of actual rows returned.
allrows The total number of rows based on filtering parameters.
total The total number of rows if filtering is not applied.
list An array of the results.

Performance metrics

URL: /rest/runtime/performancemetric. Requires authentication - requires VIEWALL or VIEWSOME permission.

  • GET - Returns available performance metric objects
  • POST, PUT, DELETE - Not implemented

Access control

VIEWALL allows all performance data to be returned.

VIEWSOME allows performance data to be returned for objects where permission has been granted for the service based on the access object selection.

Requesting performance metrics

Performance metrics consist of a name of the format:

{hostname}::{servicename}::{metricname}

For example, a fully qualified metric name is “opsview::Opsview NDO::ndo_file_backlog”.

Example GET
Request URL /rest/runtime/performancemetric?type=host
Response
{
    "list": [
        "build-sol10-amd64",
        "build-sol10-i386",
        "ov-build-centos4-32",
        "ov-build-centos4-64",
        "ov-build-centos5-32",
        "ov-build-centos5-64",
        "ov-build-etch-32",
        "ov-build-etch-64",
        "ov-build-hardy-32",
        "ov-build-hardy-64",
        "ov-build-lenny-64",
        "ov-build-rhel5-32",
        "ov-build-rhel5-64"
    ],
    "rows": "13",
    "total": "41"
}
Example GET
Request URL /rest/runtime/performancemetric?type=service
Response
{
    "list": [
        "/",
        "/backup",
        "/boot",
        "/home",
        "/srv/vms",
        "/var"
    ],
    "rows": "6",
    "total": "48"
}
Example GET
Request URL /rest/runtime/performancemetric?type=metric
Response
{
    "list": [
        "boot",
        "root"
    ],
    "rows": "2",
    "total": "279"
}
Example GET
Request URL /rest/runtime/performancemetric
Response
{
    "list": [
        "opslave::/::root",
        "opsview::/::root",
        "ov-build-centos5-64::/::root",
        "ov-build-hardy-32::/::root",
        "ov-build-hardy-64::/::root",
        "ov-build-rhel5-64::/::root",
        "prodservice1::/boot::boot",
        "prodservice1::/::root",
        "prodweb3::/::root",
        "vmhost1::/boot::boot",
        "vmhost1::/::root",
        "vmhost2::/::root",
        "vmhost3::/::root",
        "vmhost3::/srv/vms::root"
    ],
    "rows": "14",
    "total": "455"
}
Parameters
type This determines the type of results returned. If host is selected, then a set of unique host names will be returned where metrics exist based on the search parameters. Other possible values are: service, metric. If this value is not set, then the fully qualified metric names will be returned.
host Search host name based on these filters. Can use % as a wildcard. Can be repeated.
service Search service name based on these filters. Can use % as a wildcard. Can be repeated.
metric Search metric name based on these filters. Can use % as a wildcard. Can be repeated.
rows Returns back this number of rows. Defaults to all rows.
order Orders results based. Can be repeated. Valid values are host, service, metric.
collapse_multiple_services This reduces multiple services into a single response. For instance, the response with collapse_multiple_services=0 would be [“Disk: /”, “Disk: /var”, “Disk: /home”, “Interface: eth1”, “Interface: eth0”], but the response with collapse_multiple_services=1 would be ['Disk:', 'Interface:']. This only applies where type=service. Default is 0.
Response
rows Be the number of actual rows returned.
total The total number of rows if filtering is not applied.
list An array of the results.

Note: This will only return items that have performance data. If you want to search for all hosts, use /rest/runtime/host.

Monitoring servers

URL: /rest/runtime/monitoringserver. Requires authentication - requires VIEWALL or VIEWSOME permission.

  • GET - Returns monitoring servers
  • POST, PUT, DELETE - Not implemented

Access control

VIEWALL allows all monitoring servers to be returned.

VIEWSOME only lists monitoring servers that are associated to objects where permission has been granted based on the access object selection.

Retrieving monitoring servers

Example GET
Request URL /rest/runtime/monitoringserver
Response
{
    "allrows": "3",
    "list": [
        {
            "activated": "1",
            "hosts": [
                {
                    "name": "opsviewdev46"
                },
                {
                    "name": "cisco1"
                }
            ],
            "id": 1,
            "name": "Master Monitoring Server",
            "nodes": [
                {
                    "name": "opsview"
                }
            ],
            "passive": "0"
        },
        {
            "activated": "1",
            "hosts": [],
            "id": 2,
            "name": "ClusterA",
            "nodes": [
                {
                    "name": "opslave"
                }
            ],
            "passive": "0"
        },
        {
            "activated": "1",
            "hosts": [
                {
                    "name": "cisco2"
                },
                {
                    "name": "cisco3"
                }
            ],
            "id": 3,
            "name": "Cluster",
            "nodes": [
                {
                    "name": "opslaveclusterA"
                },
                {
                    "name": "opslaveclusterB"
                },
                {
                    "name": "opslaveclusterC"
                }
            ]
        }
    ],
    "rows": "3"
}
Parameters
include_hosts If set to 1, will include all hosts monitored by this monitoring server.
Response
list An array of the results. The list will be an associative array of:
  • id - ID number of the monitoring server. id=1 means it is the master server
  • name - Name of the monitoring server
  • nodes - This will be a list of the nodes by host name
  • hosts - If include_hosts=1, this will be a list of hosts by name
  • activated - Either 0 or 1
  • passive - Either 0 or 1

Network topology map

URL: /rest/runtime/network. Requires authentication - requires VIEWALL or VIEWSOME permission.

  • GET - Returns network topology map
  • POST, PUT, DELETE - Not implemented

Access control

VIEWALL allows all hosts to be returned.

VIEWSOME allows only hosts where permission has been granted based on the access object selection.

Retrieving topology map

Example GET
Request URL /rest/runtime/network
Response
{
    "allrows": 8,
    "list": [
        {
            "children": [
                "opsviewdev1",
                null,
                "cisco"
            ],
            "name": "opsview",
            "parents": []
        },
        {
            "children": [],
            "name": "opsviewdev1",
            "parents": [
                "opsview"
            ]
        },
        {
            "children": [
                "monitored_by_slave",
                "cisco4"
            ],
            "name": "cisco",
            "parents": [
                "opsview"
            ]
        },
        {
            "children": [
                null
            ],
            "name": "cisco4",
            "parents": [
                "cisco"
            ]
        }
    ],
    "rows": 4,
    "total": 20
}
Parameters
hostgroupid Includes this host group (by ID) 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).
fromhostname If set, then only the host descendants will be returned. Can be repeated.
host Filter hosts by this host name. Can be repeated.
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.
rows If set, sets the maximum of rows requested.
Response
rows The number of actual rows returned.
allrows The total number of rows based on filtering parameters.
total The total number of rows if filtering is not applied.
list An associative array of:
  • name - Name of the host
  • children - This will be a list of the children nodes by host name
  • parents - This will be a list of the parents nodes by host name

Note: If, due to permission restriction, children/parents are not visible, null will be used instead of host name.

Host templates

URL: /rest/runtime/hosttemplate. Requires authentication - requires VIEWALL or VIEWSOME permission.

  • GET - Returns all host templates
  • POST, PUT, DELETE - Not implemented

Access control

VIEWALL allows all host templates to be returned.

VIEWSOME allows only host templates that are associated to hosts where permission has been granted based on the access object selection.

Retrieving host templates

Example GET
Request URL /rest/runtime/hosttemplate
Response
{
    allrows => 4,
    list    => [
        { id => 7, name => "Agent only" },
        { id => 1, name => "Base Unix" },
        { id => 3, name => "Cisco Mgt" },
        { id => 2, name => "Network - Base" },
    ],
    rows  => 4,
    total => 4,
}

There are no parameters.

Response
rows The number of actual rows returned.
allrows The total number of rows based on filtering parameters. Note, since there is no filtering, this will always be total.
total The total number of rows if filtering is not applied.
list Array of associative arrays of:
  • id - Host template ID
  • name - Name of the host template
Navigation
Print/export
Toolbox