Documentation for up.time 7.2 If you are looking for the latest version view

Unknown macro: {spacejump}

or visit the current documentation home.

This following describes all actions that can be executed with Element groups.

Managing Element Groups

Listing Groups

List Element groups visible to the authenticated user account.

Endpoint

To list all Element groups:

GET https://youruptime/api/v1/groups/

To list a specific Element group:

GET https://youruptime/api/v1/groups/<id>/

Example Request

List all visible Element groups:

GET https://youruptime/api/v1/groups 

List a specific Element group (e.g., ID #19):

GET https://youruptime/api/v1/groups/19

Example Responses

GET https://youruptime/api/v1/groups/ 

[
   {
      "description": "Collects basic performance data",
      "elements": 
      [
         {
            "id": 1,
            "isMonitored": true,
            "name": "win-dleith"
         },
         {
            "id": 2,
            "isMonitored": true,
            "name": "rd-vc2"
          }
      ],
      "groupId": null,
      "id": 1,
      "monitors":
      [
         {
            "elementId": 1,
            "id": 2,
            "isHidden": false,
            "isMonitored": true,
            "name": "PING-localhost"
         },
         ...
      ],
      "name": "My Infrastructure",
   },
   {
      "description": "", 
      "elements": 
      [
         ...
      ],
      "groupId": 1,
      "id": 2,
      "monitors": 
      [
         ...
      ],
      "name": "Discovered Virtual Machines",
   },
   {
      "description": "", 
      "elements": 
      [
         ...
      ],
      "groupId": 1,
      "id": 3,
      "monitors": 
      [
         ...
      ],
      "name": "Discovered Hosts",
   },
   ...
]

Response Field Details

For each returned Element group, the following fields will be provided:

FieldTypeDescription
descriptionStringdescription of this Element group
elementsArrayan array listing the Elements that belong to this Element group (see Working with Elements below for details)
groupIdIntegerID for this Element group's parent group; can return a null value for the top-level group
idIntegerID for this Element group
monitorsArrayan array listing the service monitors that belong to the Elements in this Element group (see Monitors Array below for details)
nameStringthe name of this Element group

Elements Array

For each Element belonging directly to this Element group the following fields will be provided:

FieldTypeDescription
idIntegerID for the child Element
isMonitoredBooleanmonitoring status for the child Element
nameStringdisplay name for the child Element

Monitors Array

For each service monitor belonging to Elements that belong to this Element group, the following fields will be provided:

FieldTypeDescription
elementIdIntegerID of the Element this child service monitor is related to; can be null for unassigned monitors
idIntegerID for the child service monitor
isHiddenBooleanhidden monitors are internal monitors that up.time uses, and can generally be ignored
isMonitoredBooleanmonitoring status for the child service monitor
nameStringname of the child service monitor

Actions On An Element Group

View Service Monitor Status Summary

Produces basic availability information, similar to the status shown on Global Scan. The 'status' task can only be called against one Element group at a time, based on ID.

Endpoint

GET https://youruptime/api/v1/groups/<id>/status

Example Response

GET https://youruptime/api/v1/groups/1/status

{
   "elementStatus": 
   [
      {
         "id": 1,
         "isMonitored": true,
         "lastCheckTime": "2012-09-17T14:14:17",
         "lastTransitionTime": "2012-09-13T11:34:24",
         "message": "",
         "name": "win-dleith",
         "powerState": "On",
         "status": "OK"
      },
      ...
   ]
   "id": 1,
   "monitorStatus": 
   [
      {
         "elementId": 1,
         "id": 7,
         "isHidden": false,
         "isHostCheck": false,
         "isMonitored": true,
         "lastCheckTime": "2012-09-17T14:13:56",
         "lastTransitionTime": "2012-09-17T14:05:56",
         "message": "",
         "name": "Default File System Capacity",
         "status": "UNKNOWN"
      },
      ...
   ]
   "name": "My Infrastructure",
   "topologyParentStatus": 
   [
      {
         "id": 2,
         "isMonitored": true,
         "lastCheckTime": "2012-09-17T14:14:17",
         "lastTransitionTime": "2012-09-13T11:34:24",
         "message": "",
         "name": "rd-vc2",
         "powerState": null,
         "status": "OK"
      },
      ...
   ]
}

 

Response Field Details

For the returned Element group, the following fields will be provided:

FieldTypeDescription
elementStatusArrayan object listing the status of the parent Element for this monitor (see Element Status Array below for details)
idIntegerID for this service monitor
monitorStatusArraythe output message produced the last time the service monitor was executed
nameStringname of this service monitor
topologyParentStatusArraylast known status of this service monitor

Element Status Array

If this Element group has child Elements, the following fields will be provided for each:

FieldTypeDescription
idIntegerID of the child Element
isMonitoredBooleanmonitoring status for the child Element
nameStringdisplay name of the child Element
messageStringthe output message produced the last time the child Element changed status
statusStringlast known status of the child Element
lastCheckTimeString - Date Timethe last time the child Element's status was successfully checked 
lastTransitionTimeString - Date Timelast time the child Element changed status, which can be used to determine time in its current status
powerStateStringthe current power state of the child Element (only provided for virtual Elements; all other Elements will return null)

Monitor Status Arrays

If this Element group has children Elements, the following fields will be provided for each service monitor associated with those Elements:

Field
Type
Description
elementIdIntegerID of the Element this monitor is related to
idIntegerID of the service monitor
isHiddenBooleanhidden monitors are internal monitors that up.time uses, and can generally be ignored
isHostCheckBooleanreturns true if this service monitor is the host check for its parent Element
isMonitoredBooleanmonitoring status for the service monitor
nameStringname of the service monitor
messageStringoutput message produced the last time the service monitor was executed
statusStringlast known status of this service monitor
lastCheckTimeString - Date Timethe last time this service monitor was executed successfully
lastTransitionTimeString - Date Timethe last time this service monitor changed status, which can be used to determine time at its current status

Topology Status Array

The topologyParentStatus array can be used to map topological dependency failures using identified parent child Element relationships:

Field
Type
Description
idIntegerID for this service monitor
isMonitoredBooleanmonitoring status for the parent Element
lastCheckTimeString - Date Timethe last time the parent Element was checked successfully
lastTransitionTimeString - Date Timethe last time this parent Element changed status, which can be used to determine time at its current status
messageStringoutput message produced the last time the parent's status changed
nameStringdisplay name of the parent Element
powerStateStringthe current power state of the parent Element (only provided for virtual Elements; all other Elements will return null)
statusStringlast known status of the parent Element
  • No labels