Status - Host Group Summary

Rest API status endpoint for Host Group summary

Request URL: /rest/status/hostgroup

  • GET - lists summarised information about host groups
  • PUT, POST, DELETE - unimplemented

URL 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.
  • has_perfdata - if set, will only return service that have performance data. Default not set.
  • 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.
  • include_cluster_health - if set to 1 will include additional details about collector health - see below
  • 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.

When include_cluster_health is set an additional cstatus field is returned in the output for each hostgroup entry. The value returned will be one of:

ValueMeaning
not setall hosts underneath have no collector problems
1has a host underneath which is monitored by a degraded cluster
2has a host underneath which is monitored by an offline cluster
3has a collector underneath and is degraded
4has a collector underneath and is offline

NOTE: When using fromhostgroupid, previous versions of Opsview were counting hosts and services multiple times in the summary - from 6.0, this will be the correct total number.

Example output:

{
   "summary" : {
      "handled" : "27",
      "unhandled" : "37",
      "service" : {
         "ok" : "4",
         "critical" : "3",
         "handled" : "10",
         "unhandled" : "35",
         "unknown" : "38",
         "total" : "45"
      },
      "total" : "64",
      "totalhgs" : "4",
      "host" : {
         "handled" : "17",
         "unhandled" : "2",
         "up" : "15",
         "down" : "4",
         "total" : "19"
      }
   },
   "list" : [
      {
         "hosts" : {
            "handled" : "7",
            "unhandled" : "1",
            "up" : {
               "handled" : "6"
            },
            "down" : {
               "handled" : "1",
               "unhandled" : "1"
            },
            "total" : "8"
         },
         "hostgroupid" : "4",
         "services" : {
            "ok" : {
               "handled" : "1"
            },
            "handled" : "4",
            "computed_state" : "unknown",
            "unhandled" : "15",
            "unknown" : {
               "handled" : "3",
               "unhandled" : "15"
            },
            "total" : "19"
         },
         "matpath" : [
            {
               "name" : "Opsview",
               "id" : "1"
            },
            {
               "name" : "UK",
               "id" : "3"
            }
         ],
         "computed_state" : "critical",
         "downtime" : "2",
         "name" : "Leaf",
         "leaf" : "0"
      },
      {
         "hosts" : {
            "handled" : "10",
            "unhandled" : "1",
            "up" : {
               "handled" : "9"
            },
            "down" : {
               "handled" : "1",
               "unhandled" : "1"
            },
            "total" : "11"
         },
         "hostgroupid" : "1",
         "services" : {
            "ok" : {
               "handled" : "3"
            },
            "critical" : {
               "unhandled" : "3"
            },
            "handled" : "6",
            "computed_state" : "critical",
            "unhandled" : "20",
            "unknown" : {
               "handled" : "3",
               "unhandled" : "17"
            },
            "total" : "26"
         },
         "computed_state" : "critical",
         "matpath" : [],
         "downtime" : "2",
         "name" : "Opsview",
         "leaf" : "0"
      }
   ]
}

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.
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.