Follow

Understanding the Detect v2.1 Health API

You can now proactively monitor your Cognito Detect appliance and sensors with the new v2.1 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 new health v2.1 API endpoint. 

The /api/v2.1/health endpoint supports the GET method and returns health information on the following resources:

  • CPU
  • Disk
  • Host ID
  • Memory
  • Network
  • Power
  • Sensors
  • System

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.

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

Was this article helpful?
0 out of 0 found this helpful

Download PDF

0 Comments

Article is closed for comments.