System Health Check Commands

This module describes the system health check commands available on the router. These commands are used to proactively monitor the health of the router.

For detailed information about system health check concepts, configuration tasks, and examples, see the System Health Check chapter in the System Monitoring Configuration Guide for Cisco 8000 Series Routers.

healthcheck

To configure the health check cadence and metrics of a system, use the healthcheck command in Configuration mode. To disable health check, use the no form of this command.


Note

Health check service is an optional RPM. You must download and install the package explicitly to use the service.

healthcheck cadence <cadence-configuration> {enable} {metric | cpu | fabric-health | filesystem | fpd | free-mem | | shared-mem}

no healthcheck metric <metric-name>

Syntax Description

cadence

Collects data about system health for enabled metrics at a configured time interval. The cadence can range from 30 to 1800 seconds.

enable

Enables health check service on the Route Processor (RP).

metric {cpu | fabric-health | filesystem | fpd | free-mem | shared-mem}

Specifies the configurable metrics based on a threshold that applies only to system resources (CPU, free-mem, shared-mem and filesystem).

Command Default

Health check is disabled.

Command Modes

XR Config mode

Command History

Release

Modification

Release 7.0.12

This command was introduced.

Usage Guidelines

None

Task ID

Task ID

Operations

root-system or diag or cisco-support or monitor or root-lr

read, write

This example shows how to enable health check service: 

Router(config)#healthcheck enable

This example shows how to configure cadence (in seconds) at which data about system health is collected: 

Router(config)#healthcheck cadence 30

This example shows how to configure the average utilization threshold of CPU metric: 

Router(config)#healthcheck metric cpu avg-util 15-minute

healthcheck metric

To disable the health check for the metrics of a system, use the healthcheck metric command in Configuration mode.

healthcheck metric { cpu | fabric-health | filesystem | fpd | free-mem | shared-mem | platform | redundancy | interface-counters | asic-errors | fabric-stats } disable

Syntax Description

cpu

Specifies system health data for cpu configurations

fabric-health

Specifies system health data for fabric configurations

filesystem

Specifies system health data for file-system usage configurations

fpd

Specifies system health data for fpd configurations

free-mem

Specifies system health data for free memory

shared-mem

Specifies system health data for shared memory

platform

Specifies system health data for platform configuration

redundancy

Specifies system health data for redundancy configuration

interface-counters

Specifies system health data for interface counters

asic-errors

Specifies system health data for asic-errors

fabric-stats

Specifies system health data for fabric statistics

disable

Disables the collection of health-check information

Command Default

Health-check for metrics is enabled.

Command Modes

XR Config mode

Command History

Release

Modification

Release 7.0.12

This command was introduced.

Release 7.0.14

Command options for platform and redundancy infrastructure services and counters were added.

Usage Guidelines

None

Task ID

Task ID

Operations

monitor

read, write, execute

This example shows how to disable health check service for plaform: 

Router(config)#healthcheck metric platform disable
Router(config)#commit

This example shows how to disable health check service for interface-counters: 

Router(config)#healthcheck metric intf-counters disable
Router(config)#commit

show healthcheck metric

To view the detailed information about the utilization and state of each metric used to check the health of the system, use the show healthcheck metric command in EXEC mode.

show healthcheck metric cpu | free-mem | shared-mem | filesystem | fpd | fabric-health | platform | redundancy | interface-counters { summary | | | detail } | asic-errors { summary | | | detail } | fabric-stats { summary | | | detail }

Syntax Description

cpu | free-mem | shared-mem | filesystem

Name of the system resource for which the metric is viewed.
fpd | fabric-health | platform | redundancy

Name of the infrastructure service for which the metric is viewed.

interface-counters | asic-errors | fabric-stats

Name of the counters for which the metric is viewed.

Command Default

None

Command Modes

XR EXEC mode

Command History

Release

Modification

Release 7.0.12

This command was introduced.

Release 7.0.14

Health-check for the platform and redundancy infrastructure services and counters were added.

Usage Guidelines

No specific guidelines impact the use of this command.

Task ID

Task ID

Operations

monitor

read

This is sample output from the show healthcheck metric command to view the CPU usage: 

Router#show healthcheck metric cpu 
CPU Metric State: Normal
Last Update Time: <date-time>
CPU Service State: Enabled
Number of Active Nodes: 2
Configured Thresholds:
   Minor: 20%
   Severe: 50%
   Critical: 75%
Node Name: 0/RP0/CPU0
    CPU 1 Minute Average Usage: 6%
    CPU 5 Minute Average Usage: 5%
    CPU 15 Minute Average Usage: 5% *
Node Name: 0/0/CPU0
    CPU 1 Minute Average Usage: 4%
    CPU 5 Minute Average Usage: 4%
    CPU 15 Minute Average Usage: 3% *
'*' indicates the traceked average CPU utilization

This is sample output from the show healthcheck metric platform : 

Router#show healthcheck metric platform 
Platform Metric State: Normal ==========> Health of the metric
Last Update Time: 25 Jun 05:17:03.508172 =====> Timestamp at which the metric data was collected
Platform Service State: Enabled =====> Service state of Platform
Number of Racks: 1 ======> Total number of racks in the testbed
Rack Name: 0 
Number of Slots: 12
Slot Name: RP0 
Number of Instances: 2
Instance Name: CPU0 
Node Name 0/RP0/CPU0 
Card Type 8800-RP 
Card Redundancy State Active 
Admin State NSHUT 
Oper State IOS XR RUN

This is sample output from the show healthcheck metric interface-counters : 

Router#show healthcheck interface-counters summary
Interface-counters Health State: Normal ==========> Health of the metric
Last Update Time: 25 Jun 05:59:33.965851 =====> Timestamp at which the metric data was collected
Interface-counters Service State: Enabled =====> Service state of the metric
Interface MgmtEth0/RP0/CPU0/0 =====> Configured interface for healthcheck monitoring
Counter-Names Count Average Consistently-Increasing
------------------------------------------------------------------------------------------------
output-buffers-failures 0 0 N
Counter-Names =====> Name of the counters
Count =====> Value of the counter collected at "Last Update Time"
Average =====> Average of all values available in buffer
Consistently-Increasing =====> Trend of the counter values, as per data available in buffer
Router#show healthcheck interface-counters detail all
Last Update Time: 25 Jun 06:01:35.217089 =====> Timestamp at which the metric data was collected
Interface MgmtEth0/RP0/CPU0/0 =====> Configured interface for healthcheck monitoring
Following table displays data for last <x=5> values collected in periodic cadence intervals
-------------------------------------------------------------------------------------------------------
Counter-name Last 5 values
LHS = Earliest RHS = Latest
-------------------------------------------------------------------------------------------------------
output-buffers-failures 0 0 0 0 0 
parity-packets-received 0 0 0 0 0

show healthcheck report

To view the health check report for enabled metrics in the system, use the show healthcheck report command in XR EXEC mode.

show healthcheck report

Syntax Description

This command has no keywords or arguments.

Command Default

None

Command Modes

XR EXEC mode

Command History

Release

Modification

Release 7.0.12

This command was introduced.

Usage Guidelines

No specific guidelines impact the use of this command.

Task ID

Task ID

Operations

monitor

read

This is sample output from the show healthcheck report command: 

Router#show healthcheck report 
Healthcheck report for enabled metrics
cpu
  State: Normal
free-memory
  State: Normal
filesystem
  State: Normal
shared-memory
  State: Normal
fpd
  State: Warning
One or more FPDs are in NEED UPGD state
fabric-health
  State: Normal

show healthcheck status

To view the status of health check service and configured parameters for each of the enabled metrics, use the show healthcheck status command in XR EXEC mode.

show healthcheck status

Syntax Description

This command has no keywords or arguments.

Command Default

None

Command Modes

XR EXEC mode

Command History

Release

Modification

Release 7.0.12

This command was introduced.

Usage Guidelines

No specific guidelines impact the use of this command.

Task ID

Task ID

Operations

monitor

read

This is sample output from the show healthcheck status command: 

Router#show healthcheck status 
Healthcheck status: Enabled

Collector Cadence: 60 seconds

System Resource metrics
  cpu
      Thresholds: Minor: 10%
                  Severe: 20%
                  Critical: 30%

       Tracked CPU utilization: 15 min avg utilization

   free-memory
        Thresholds: Minor: 10%
                    Severe: 8%
                    Critical: 5%

   filesystem
        Thresholds: Minor: 80%
                    Severe: 95%
                    Critical: 99%

   shared-memory
        Thresholds: Minor: 80%
                    Severe: 95%
                    Critical: 99%

Infra Services metrics
   fpd

   fabric-health

show healthcheck use-case packet-drop

To view the packet-drop use-case trends, use the show healthcheck use-case packet-drop command in XR EXEC mode.

show healthcheck use-case packet-drop { summary | detail { npu | npu | location | location } | history { npu | npu | location | location } }

Syntax Description

npu npu

Specify the npu

location location

Specify the slot location

Command Default

None

Command Modes

XR EXEC mode

Command History

Release

Modification

Release 24.4.1

This command was modified to introduce the history keyword.

Release 7.3.4

This command was introduced.

Usage Guidelines

No specific guidelines impact the use of this command.

Task ID

Task ID

Operations

monitor

read

This is sample output from the show healthcheck use-case packet-drop summary command: 

Router# show healthcheck use-case packet-drop summary
Mon Jun 5 10:38:25.885 IST
Use Case Name: packet_drop
Timestamp : Mon 2023-06-05 10:38:25 IST
State : Normal

This is sample output from the show healthcheck use-case packet-drop detail command: 

Router# show healthcheck use-case packet-drop detail npu all location all
Mon Nov 25 08:35:47.701 UTC
Node: 0/0/CPU0 NPU Instance: 0
Timestamp : Mon 2024-11-25 08:35:29 UTC
Alerts :
1. npu-traps location: node-name: 0/0/CPU0 npu-id: 0 trap-string:
V4_CHECKSUM_ERROR(D*) tolerance: LOW trend: PEAK at 2024-11-25 08:35:26

This is sample output from the show healthcheck use-case packet-drop history command: 

Router# show healthcheck use-case packet-drop history npu 0 location 0/0/CPU0
Node: 0/0/CPU0     NPU Instance: 0 
Timestamp: 
Alerts    : 
        1. npu-traps location: node-name: 0/0/CPU0 npu-id: 0 trap-string: UNKNOWN_VLAN_OR_BUNDLE_MEMBER(D*) trend: PEAK at 2023-11-28 07:11:37 
        2. npu-drops location: node-name: 0/0/CPU0 npu-id: 0 field-name: counters.drop.slice[0].ifg[0].ifgb.port_4.rx_undersize_pkt_ severity: ERROR trend: PEAK at 2023-11-28 07:11:37 
        3. npu-traps location: node-name: 0/0/CPU0 npu-id: 0 trap-string: V4_CHECKSUM_ERROR(D*) trend: PLATEAU at 2023-11-28 07:13:37 
        4. npu-traps location: node-name: 0/0/CPU0 npu-id: 0 trap-string: UNKNOWN_VLAN_OR_BUNDLE_MEMBER(D*) trend: PLATEAU at 2023-11-28 07:13:37 
        5. npu-drops location: node-name: 0/0/CPU0 npu-id: 0 field-name: counters.drop.slice[0].ifg[0].ifgb.port_4.rx_undersize_pkt_ severity: ERROR trend: PLATEAU at 2023-11-28 07:21:37 
        6. npu-traps location: node-name: 0/0/CPU0 npu-id: 0 trap-string: UNKNOWN_VLAN_OR_BUNDLE_MEMBER(D*) trend: PLATEAU at 2023-11-28 07:31:09 
        7. npu-traps location: node-name: 0/0/CPU0 npu-id: 0 trap-string: V4_CHECKSUM_ERROR(D*) trend: PLATEAU at 2023-11-28 07:52:39 
        8. npu-traps location: node-name: 0/0/CPU0 npu-id: 0 trap-string: UNKNOWN_VLAN_OR_BUNDLE_MEMBER(D*) trend: PLATEAU at 2023-11-28 07:52:39 
        9. npu-traps location: node-name: 0/0/CPU0 npu-id: 0 trap-string: UNKNOWN_VLAN_OR_BUNDLE_MEMBER(D*) trend: RECOVERY at 2023-11-28 08:04:40 
        10. npu-traps location: node-name: 0/0/CPU0 npu-id: 0 trap-string: V4_CHECKSUM_ERROR(D*) trend: RECOVERY at 2023-11-28 08:04:40

use-case

To configure a system healthcheck use-case, use the use-case command in the healthcheck configuration mode.

Prior to Cisco IOS XR Release 24.1.1:

use-case { asic-reset { disable | drop-tolerance drop-tolerance-value } | packet-drop { disable | drop-tolerance drop-tolerance-value } }

From Cisco IOS XR Release 24.1.1 onwards:

use-case { asic-reset { disable | drop-tolerance drop-tolerance-value } | packet-drop { disable | window-size window-size-value | tolerance { high | medium | low } drop-tolerance-value } }

Syntax Description

asic-reset

Specify ASIC reset system healthcheck use-case
disable

Disable ASIC reset or packet-drop use-case. By default the use-case is enabled.
drop-tolerance drop-tolerance-value

Configure packet-drop tolerance value

Default value: 10

Range for drop-tolerance-value : 0 - 100

This option is removed from Release 24.1.1 onwards
packet-drop

Specify packet-drop system healthcheck use-case
window-size window-size-value

Configure the number of cadence intervals to alert you of packet-drops.

Default value: 10

Range for window-size-value : 5-20

This option is available from Release 24.1.1 onwards
tolerance { high | medium | low } drop-tolerance-value

Specify the NPU trap tolerance level and the drop-tolerance value.

Range for drop-tolerance-value : 0-1000000

This option is available from Release 24.1.1 onwards

Command Default

Health check use-case is enabled.

Command Modes

healthcheck configuration mode

Command History

Release Modification

Release 24.1.1

window-size and tolerance keywords are introduced

drop-tolerance keyword is removed

Release 7.3.3 / Release 7.5.4

This command was introduced

Usage Guidelines

System Health check and use-cases are not part of the base package and you must explicitly install the ‘xr-healthcheck’optional package to use this service.

Task ID

Task ID

Operations

root-system or diag or cisco-support or monitor or root-lr

read, write

Example

This example shows you how to configure the ASIC reset use-case:

Router(config)# healthcheck
Router(config-healthcheck)# use-case asic-reset drop-tolerance 10
Router(config-healthcheck)# enable

This example shows you how to configure the packet-drop use-case prior to Cisco IOS XR Release 24.1.1:

Router(config)# healthcheck
Router(config-healthcheck)# use-case packet-drop drop-tolerance 10
Router(config-healthcheck)# enable

This example shows you how to configure the packet-drop use-case from Cisco IOS XR Release 24.1.1 onwards:

Router# conf t
Router(config)# healthcheck
Router(config-healthcheck)# use-case packet-drop window-size 5
Router(config-healthcheck)# use-case packet-drop tolerance high 100
Router(config-healthcheck)# enable
Router(config-healthcheck)# commit