# Understanding the v2.5 health API You can proactively monitor your Cognito Detect appliance and sensors with the v2.5 health REST API endpoint. The ability to monitor system health via API reduces the need for manual operation and enables early identification of issues within the Cognito platform. Please note that the Detect *view health* permission is required to access the health v2.5 API endpoint. The /api/v2.5/health endpoint supports the GET method and returns health information on the following resources: * CPU * Disk * Host ID * Memory * Network * Power * Sensors * System * Connectivity Alternatively, you can identify a single health resources using the URI /health/{resource}. ### CPU The CPU resource URI: **/health/cpu** Displays information related to the Cognito brain's cpu utilization. ``` { "cpu": { "idle_percent": 65.1, "user_percent": 34.2, "nice_percent": 0.0, "system_percent": 0.6 } } ``` The **idle\_percentage** is the percentage of the CPU sitting Idle. The **user\_percentage** is the percentage of the CPU processing tasks. The **nice\_percentage** is the percentage of the CPU working on higher prioritized tasks. The **system\_percentage** is the percentage of the CPU processing system specific tasks. ### Disk Disk resource URI: **/health/disk** Displays information related to the Cognito brain's disk utilization. ``` { "disk": { "raid_disks_missing": { "status": "OK", "output": {}, "error": "" }, "disk_utilization": { "free_bytes": 46023778304, "total_bytes": 62861103104, "usage_percent": 26.78, "used_bytes": 16837324800 }, "degraded_raid_volume": { "status": "OK", "output": [], "error": "" }, "disk_raid": { "status": "OK", "output": "", "error": "" } } } ``` The **raid\_disks\_missing** shows OK if all disks in the RAID are present. Optional health output and RAID error messages are included, if available. The **disk\_utilization** shows the number of free and total bytes in the filesystem. The usage percent bytes is calculated by (used bytes / total bytes) \* 100. The used bytes is calculated by (total bytes - free bytes). The **degraded\_raid\_volume** shows OK if all healthy disks are being utilized by RAID. Optional health output and RAID error messages are included, if available. The **disk\_raid** shows OK if RAID is functioning properly overall. Optional health output and RAID error messages are included, if available. ### Host ID Host ID resource URI: **/health/hostid** Displays information related to the Cognito brain's HostID coverage. HostID is a subsystem used by the Cognito platform to uniquely identify host in the network based on observed network metadata. ``` { "hostid": { "ip_never_percent": 100.0, "artifact_counts": { "kerberos_user": 0, "proxy_ip": 0, "crowdstrike": 0, "total": 1017, "arsenic": 0, "rdns": 0, "mdns": 0, "src_port": 0, "carbon_black": 0, "split": 0, "dns": 0, "dhcp": 0, "idle_start": 1, "kerberos": 0, "clear_state": 16, "static_ip": 0, "cookie": 0, "uagent": 1000, "netbios": 0, "idle_end": 0, "end_time": 0, "vmachine_info": 0 }, "ip_always_percent": 0.0, "ip_sometimes_percent": 0.0 } } ``` The **ip\_never\_percent** shows the percentage of IP addresses that are never covered by Host ID when seen on the network. The **artifact\_counts** shows the number of each type of artifact seen on the network. These counters are collected weekly, so expect up to one week between updates to this data. The **ip\_always\_percent** shows the percentage of IP addresses that are always covered by Host ID when seen on the network. The **ip\_sometimes\_percent** shows the percentage of IP addresses that are sometimes covered by Host ID when seen on the network. ### Memory Memory resource URI: **/health/memory** Displays information related to the Cognito brain's memory utilization. ``` { "memory": { "free_bytes": 64117665792, "dimm_status": [ { "status": "OK", "dimm": "mc1" }, { "status": "OK", "dimm": "mc0" } ], "used_bytes": 71043166208, "usage_percent": 38.0, "total_bytes": 135160832000 } } ``` The **free\_bytes** shows the memory not being used at all (zeroed) that is readily available. The **dimm\_status** shows OK if a DIMM slot is considered healthy. If a DIMM is unhealthy, it may affect RAM performance. The **used\_bytes** shows the amount of memory in use (total - free). The **usage\_percent** shows the percentage usage calculated as (total - available) / total \* 100. The **total\_bytes** shows the total physical memory available. ### Network Network resource URI: **/health/network** Displays information related to the Cognito brain and sensor's network utilization. ``` { "network": { "interfaces": { "brain": { "eth3": { "speed_mbps": 1000, "duplex": "FULL", "link": "UP", "link_stable": true }, "eth2": { "speed_mbps": 1000, "duplex": "FULL", "link": "UP", "link_stable": true }, "eth1": { "link_stable": true, "link": "DOWN" }, "eth0": { "link_stable": true, "link": "DOWN" } }, "sensors": {} }, "traffic": { "brain": { "interface_peak_traffic": { "eth3": { "peak_traffic_mbps": 0 }, "eth2": { "peak_traffic_mbps": 0 }, "eth1": { "peak_traffic_mbps": 0 }, "eth0": { "peak_traffic_mbps": 0 } }, "aggregated_peak_traffic_mbps": 0 }, "sensors": {} }, "vlan_count": 0 } } ``` The **interfaces** information is updated every five minutes and displays a list of network interfaces on the Cognito brain and sensors. The **speed\_mbps** shows the link speed given in megabits per second, will only show if link is "UP". The **duplex** shows the link duplex will be either "HALF" or "FULL", will only show if link is "UP". The **link** shows a status of either "UP" or "DOWN". The **interface\_peak\_traffic** shows the peak traffic seen on each interface. The **aggregated\_peak\_traffic\_mbps** shows the peak traffic seen over all the interfaces aggregated over one update interval. The **vlan\_count** shows the count of vlans that Cognito was able to analyze. **\*Note:** the parameter vlans is True by default. Setting vlans=false will omit the list of VLANs observed from the returned data. Large environments with many VLANs can result in slow performance from the /health and /health/network endpoints. \* ### Power Power resource URI: **/health/power** Displays information related to the Cognito brain power supply. ``` { "power": { "status": "CRITICAL", "power_supplies": { "1": { "faults": [], "temperature_celcius": 31.0 } }, "error": "" } } ``` The **power** information shows the status of the power supply. The **power\_supplies** returns a list of power supplies and their status. If present, any **faults** (e.g."Temperature", "Fan", "Power", "Output Power", etc.) will be listed for each power supply. The **temperature\_celcius** displays the operating temperature of the power supply. Any **error** information will be displayed if there are errors reading the power supply health. ### Sensors Sensors resource URI: **/health/sensors** Displays information related to Cognito sensors. ``` { "sensors": [ { "status": "paired", "name": "Sensor APP Team", "serial_number": "V422c32562bb80439756730fc8fb56ac7", "package_version": "4.9.0-13-31", "last_seen": "2019-11-26T16:16:39Z", "ip_address": "192.168.5.8", "luid": "mnyr567p", "location": "Austin" } } ``` The **status** shows the pairing status of the sensor. The **name** shows the name given to this sensor. The **serial\_number** shows the serial number of the sensor. The **package\_version** shows the sensor package version. The **last\_seen** information shows the timestamp of the latest heartbeat received from the sensor. The **ip\_address** shows the IP address of the sensor. The **luid** information shows a Vectra generated unique ID for the sensor. The **location** shows the location of this sensor. ### System System resource URI: **/health/system** Displays system information related to the Cognito brain. ``` { "system": { "serial_number": "S11156733702416", "uptime": "7 days, 2 hours, 9 minutes", "version": { "last_update": "Tue Dec 17 04:57:06 2019", "mode": "mixed", "vectra_version": "5.3.0-14-38", "model": "X4" } } } ``` The **serial\_number** shows the serial number of the brain. The **uptime** shows the amount of time that the brain has been powered on. The **last\_update** shows the date of the last Cognito software update. The **mode** shows the mode the brain is running in. The **vectra\_version** shows the version of the Cognito software. The **model** shows model information (S2, X4, X24, X20i, X29, X29v2, X80, etc). ### Connectivity System resource URI: **/health/connectivity** Displays the connectivity status for Cognito sensors. ``` {   "connectivity": {   "sensors": [   {   "name": "E1976E3611050022",   "output": {   "last_check": "2021-10-12T22"   },   "error": "",   "status": "OK",   "serial_number": "E1976E3611050022",   "luid": "snvv4hm0",   "ip_address": "192.168.1.1"   },   {   "name": "other sensor",   "output": {   "affected_metadata_hours": [   "2021-10-12-21",   "2021-10-12-22"   ],   "last_check": "2021-10-12T22"   },   "error": "exception trying to connect to remote database for past 2 hours",   "status": "CRITICAL",   "serial_number": "E1976E3611050023",   "luid": "l3vs98lu",   "ip_address": "192.168.1.2"   }   ]   } } ``` **connectivity** contains an array of objects one for each paired Cognito sensor Inside each object will be the following information: **output** tells you diagnostic information from the system including * **last\_check** the hour when the information for the check was curated * **affected\_metadata\_hours** a list of hours during which the metadata pipeline had issues. This field will not be present if the status is "OK". **error** gives a message detailing what issues have happened in the metadata pipeline **status** can be **OK**, **WARNING**, **CRITICAL**, or **UNKNOWN** **name** has the provided name for the sensor. **serial\_number** has the serial number of the sensor. **luid** is the Vectra generated unique ID for the sensor. **ip\_address** contains the ip of the sensor.