ajshedivy/system-health

IBM i System Health Monitoring

Monitor system health including CPU, memory, disk, ASPs, system limits, and network status using SQL services from QSYS2.

Available Tools

The ibmi CLI is the primary tool for executing system health queries. Set SKILL_DIR to this skill's installed location (the directory containing this SKILL.md file):

# SKILL_DIR = directory containing this SKILL.md
# Examples: ./skills/system-health, ~/.claude/skills/system-health

# List all system health tools
ibmi tools --tools "$SKILL_DIR/tools/" --toolset system_health_default

# Run a specific tool
ibmi tool get_system_status --tools "$SKILL_DIR/tools/"

# Ad-hoc SQL for custom queries
ibmi sql "SELECT * FROM TABLE(QSYS2.SYSTEM_STATUS(RESET_STATISTICS => 'YES')) X"

Service Selection Guide

System Status & Activity

• QSYS2.SYSTEM_STATUS() -- Comprehensive system metrics: CPU, memory, jobs, partition info
• QSYS2.SYSTEM_ACTIVITY_INFO() -- Real-time CPU utilization rates

Memory

• QSYS2.MEMORY_POOL() -- Pool sizes, threads, paging rates, tuning parameters

Disk & Storage

• QSYS2.SYSDISKSTAT -- Disk unit capacity, usage, I/O stats per unit
• QSYS2.ASP_INFO -- ASP capacity, thresholds, balance status

System Limits

• QSYS2.SYSLIMITS -- System limits with current vs maximum values
• QSYS2.SYSLIMITS_BASIC -- Lightweight limits view

Network

• QSYS2.NETSTAT_INFO -- TCP/IP connections, addresses, ports, transfer counts

Key Capabilities

CPU Monitoring

• Overall Utilization -- Average, minimum, maximum CPU percentages
• Capacity Info -- Configured CPUs, current capacity, sharing attributes
• Elapsed Metrics -- CPU used during measurement interval

Memory Analysis

• Pool Status -- Current size, defined size, reserved, thread counts
• Page Faults -- Database and non-database fault rates per pool
• Thread Activity -- Active, ineligible, and maximum threads per pool
• Tuning -- Priority, min/max size, min/max faults settings

Disk & ASP Health

• Disk Units -- Capacity, percent used, type, protection, I/O busy %
• ASP Status -- Total/available capacity, threshold, balance status
• Protected vs Unprotected -- Breakdown of storage by protection type

System Limits

• Threshold Monitoring -- Find limits approaching maximum values
• Capacity Planning -- Current vs maximum with percentage used
• Category Filtering -- Filter by limit type and category

Network Status

• Active Connections -- Established TCP connections with addresses and ports
• Connection Counts -- Total remote connections excluding loopback
• Transfer Stats -- Bytes sent/received per connection

Common Use Cases

1. System health check -- Quick overview of CPU, memory, jobs, and storage
2. CPU troubleshooting -- Identify high CPU utilization periods
3. Memory pressure -- Find pools with high page fault rates
4. Disk capacity planning -- Monitor ASP usage and thresholds
5. Limit monitoring -- Find system limits approaching maximum
6. Network audit -- Review active TCP connections
7. Performance baseline -- Capture system metrics for comparison
8. IPL planning -- Check system status before maintenance windows

Quick Examples

System status overview

ibmi tool get_system_status --tools "$SKILL_DIR/tools/"

Memory pool health

ibmi tool get_memory_pools --tools "$SKILL_DIR/tools/"

Find limits above 80% used

ibmi tool get_system_limits --tools "$SKILL_DIR/tools/" --pct-threshold 80

ASP capacity check

SELECT ASP_NUMBER, TOTAL_CAPACITY, TOTAL_CAPACITY_AVAILABLE,
       STORAGE_THRESHOLD_PERCENTAGE
  FROM QSYS2.ASP_INFO
  ORDER BY ASP_NUMBER;

Disk units by busy percentage

SELECT UNIT_NUMBER, ASP_NUMBER, PERCENT_USED, ELAPSED_PERCENT_BUSY
  FROM QSYS2.SYSDISKSTAT
  WHERE ELAPSED_PERCENT_BUSY > 0
  ORDER BY ELAPSED_PERCENT_BUSY DESC
  FETCH FIRST 10 ROWS ONLY;

Pre-built Tools

The tools/system-health.yaml file provides 8 ready-to-use tools:

| Tool | Description | |------|-------------| | get_system_status | Comprehensive system status: CPU, memory, jobs, partition | | get_system_activity | Real-time CPU utilization rates | | get_memory_pools | Memory pool sizes, threads, and paging metrics | | list_disk_units | Disk unit capacity, usage, type, and I/O stats | | list_asp_info | ASP capacity, thresholds, and balance status | | get_system_limits | System limits with percentage used filtering | | get_tcp_connections | Established TCP/IP connections with transfer stats | | count_remote_connections | Count of remote connections excluding loopback |

ibmi tool <tool_name> --tools "$SKILL_DIR/tools/"          # Execute
ibmi tool <tool_name> --tools "$SKILL_DIR/tools/" --dry-run # Preview SQL
ibmi tools show <tool_name> --tools "$SKILL_DIR/tools/"     # View details

Reference Documentation

• System Health Services Catalog -- Available SQL services
• Example SQL Patterns -- Working query examples
• IBM SYSTEM_STATUS -- Table function documentation
• IBM SYSLIMITS -- View documentation