| 1 | name: as400 |
| 2 | display_name: IBM i (AS/400) |
| 3 | description: | |
| 4 | Monitors IBM i (AS/400) systems using SQL services and CL commands to |
| 5 | expose CPU, memory, storage, job, and subsystem activity. |
| 6 | |
| 7 | **Dependencies:** |
| 8 | - unixODBC 2.3+ with IBM i Access ODBC driver |
| 9 | - IBM i 7.2 or later with SQL services enabled |
| 10 | |
| 11 | **Required Libraries:** |
| 12 | - libodbc.so (provided by unixODBC) |
| 13 | - IBM i Access Client Solutions |
| 14 | |
| 15 | **Collection paths** |
| 16 | |
| 17 | The collector executes queries in multiple tracks: |
| 18 | |
| 19 | - **Fast path (5s)**: lightweight system status queries remain sequential on the main plugin thread. |
| 20 | - **Slow path (10s beat)**: heavier queries (per-queue metrics, subsystems, plan cache, etc.) run in a background worker with bounded concurrency. |
| 21 | - **Batch path (≥60s beat)**: optional long-period worker used for expensive aggregate queries such as queue totals. Disabled by default unless queue totals are explicitly enabled. |
| 22 | |
| 23 | **CPU Collection Methods:** |
| 24 | |
| 25 | The collector uses a hybrid approach for CPU utilization metrics to handle IBM i 7.4+ where |
| 26 | `AVERAGE_CPU_*` columns were deprecated: |
| 27 | |
| 28 | 1. **Primary Method - TOTAL_CPU_TIME**: Uses the monotonic `TOTAL_CPU_TIME` counter from |
| 29 | `QSYS2.SYSTEM_STATUS()` to calculate CPU utilization via delta-based calculation. This is |
| 30 | the most accurate method but requires `*JOBCTL` special authority. TOTAL_CPU_TIME is a |
| 31 | cumulative counter in nanoseconds representing CPU-seconds consumed, naturally in per-core |
| 32 | scale. |
| 33 | |
| 34 | 2. **Fallback Method - ELAPSED_CPU_USED**: If `*JOBCTL` authority is not available, falls back |
| 35 | to `ELAPSED_CPU_USED` with automatic reset detection. This method tracks when IBM i statistics |
| 36 | are reset (either manually or via `reset_statistics` configuration) and re-establishes a |
| 37 | baseline after detecting resets. The values are already in per-core scale. |
| 38 | |
| 39 | 3. **Legacy Method - AVERAGE_CPU_UTILIZATION**: For IBM i versions before 7.4, uses the now- |
| 40 | deprecated `AVERAGE_CPU_UTILIZATION` column, which IBM reports in the same per-core scale. |
| 41 | |
| 42 | The collector automatically selects the appropriate method based on available permissions and |
| 43 | logs which method is being used. |
| 44 | |
| 45 | **CPU Metric Scale:** |
| 46 | |
| 47 | CPU utilization is reported using the "100% = 1 CPU core" semantic. This means: |
| 48 | - 100% indicates one CPU core is fully utilized |
| 49 | - 400% indicates four CPU cores are fully utilized |
| 50 | - Values are limited to 100% × ConfiguredCPUs, matching the partition's configured capacity |
| 51 | |
| 52 | For shared LPARs, the metrics show absolute CPU consumption in per-core scale, not relative to |
| 53 | entitled capacity. For example, a shared LPAR entitled to 0.20 cores can show 150% utilization |
| 54 | when bursting above entitlement. |
| 55 | |
| 56 | **Statistics Reset Behavior:** |
| 57 | |
| 58 | The `reset_statistics` configuration option controls whether the collector resets IBM i system |
| 59 | statistics on each query via `SYSTEM_STATUS(RESET_STATISTICS=>'YES')`. When enabled: |
| 60 | |
| 61 | - System-level statistics (CPU, memory pools, etc.) are reset after each collection cycle |
| 62 | - Matches legacy behavior but clears global statistics that other tools may rely on |
| 63 | - The ELAPSED_CPU_USED fallback method will detect and handle these resets automatically |
| 64 | - **Caution**: Enabling this affects all users and applications on the IBM i system |
| 65 | |
| 66 | Default: `false` (statistics are not reset, using `RESET_STATISTICS=>'NO'`) |
| 67 | |
| 68 | **Chart Gaps During Baseline Resets:** |
| 69 | |
| 70 | The `as400.system_activity_cpu_rate` and `as400.system_activity_cpu_utilization` charts rely on |
| 71 | delta calculations. When the collector detects that IBM i reset these statistics—or when it is |
| 72 | still establishing the initial baseline—it intentionally skips a sample instead of emitting a zero |
| 73 | or spike. Netdata renders those skipped samples as small gaps, which is expected behaviour. |
| 74 | |
| 75 | **Cardinality Management:** |
| 76 | |
| 77 | To prevent performance issues from excessive metric creation, the collector enforces cardinality |
| 78 | limits on per-instance metrics (disks, subsystems, job queues, message queues, output queues, |
| 79 | active jobs, network interfaces, HTTP servers). |
| 80 | |
| 81 | **How Limits Work:** |
| 82 | - The collector counts instances before collecting metrics |
| 83 | - If count exceeds the configured `max_*` limit, **collection is skipped entirely** for that category |
| 84 | - The collector logs a warning: `"[category] count (X) exceeds limit (Y), skipping collection"` |
| 85 | - No metrics are collected for that category until you adjust the configuration |
| 86 | |
| 87 | **Configuration Options:** |
| 88 | |
| 89 | Use **both** limit and selector options together to manage high-cardinality environments: |
| 90 | |
| 91 | | Option | Purpose | Default | |
| 92 | |--------|---------|---------| |
| 93 | | `max_disks` | Maximum disk units to monitor | 100 | |
| 94 | | `max_subsystems` | Maximum subsystems to monitor | 100 | |
| 95 | | `max_job_queues` | Maximum job queues to monitor | 100 | |
| 96 | | `max_message_queues` | Maximum message queues to monitor | 100 | |
| 97 | | `max_output_queues` | Maximum output queues to monitor | 100 | |
| 98 | | `active_jobs` | Fully qualified active jobs to monitor (`JOB_NUMBER/USER/JOB_NAME`) | `[]` | |
| 99 | | `collect_disks_matching` | Glob pattern to filter disks (e.g., `"001* 002*"`) | `""` (match all) | |
| 100 | | `collect_subsystems_matching` | Glob pattern to filter subsystems (e.g., `"QINTER QBATCH"`) | `""` (match all) | |
| 101 | | `collect_job_queues_matching` | Glob pattern to filter job queues (e.g., `"QSYS/*"`) | `""` (match all) | |
| 102 | |
| 103 | Optional batch-path controls: |
| 104 | |
| 105 | | Option | Purpose | Default | |
| 106 | |--------|---------|---------| |
| 107 | | `batch_path` | Enables the long-period batch worker for aggregate queries | `false` | |
| 108 | | `batch_path_update_every` | Batch worker cadence (minimum 60s, recommend ≥600s in production) | `60s` | |
| 109 | | `batch_path_max_connections` | Maximum concurrent connections for batch queries | `1` | |
| 110 | | `collect_message_queue_totals` | Enables full-scan counting of all message queues and messages | `auto` (off) | |
| 111 | | `collect_job_queue_totals` | Enables aggregate counting of job queues and queued jobs | `auto` (off) | |
| 112 | | `collect_output_queue_totals` | Enables aggregate counting of output queues and spooled files | `auto` (off) | |
| 113 | |
| 114 | > **Warning:** queue totals require scanning IBM i catalog views and can be very expensive on large systems. Leave these options disabled unless aggregate counts are absolutely necessary. |
| 115 | |
| 116 | |
| 117 | **Example Workflow:** |
| 118 | |
| 119 | 1. System has 500 disks, collector skips disk metrics (exceeds default limit of 100) |
| 120 | 2. Check logs: `"disk count (500) exceeds limit (100), skipping per-disk metrics"` |
| 121 | 3. Two options: |
| 122 | - **Option A**: Increase limit: `max_disks: 500` (collects all 500 disks) |
| 123 | - **Option B**: Use selector: `collect_disks_matching: "00[1-5]*"` (cherry-pick specific disks) |
| 124 | |
| 125 | **Best Practices:** |
| 126 | - Use selectors to monitor only business-critical objects in large environments |
| 127 | - Set limits based on your Netdata server's capacity (each instance = multiple charts) |
| 128 | - Start with defaults and adjust based on actual usage patterns |
| 129 | |
| 130 | **IBM i 7.2–7.3 Behavior Note (Message Queues):** |
| 131 | |
| 132 | IBM i 7.4 introduced a message-queue table function that returns only the live backlog. On |
| 133 | 7.2–7.3 systems we fall back to the `QSYS2.MESSAGE_QUEUE_INFO` view, which includes *all* |
| 134 | recorded messages (even those already processed/cleared from the queue). Aggregations—especially |
| 135 | `MAX(SEVERITY)`—therefore reflect the historical log, not just the outstanding backlog. This |
| 136 | behaviour is inherent to the IBM SQL service and can lead to higher-than-expected max severity |
| 137 | values on pre-7.4 systems. |
| 138 | |
| 139 | Network interface metrics have a fixed internal limit of 50 instances, and HTTP server metrics are capped at 200 instances; these limits are currently not configurable. |
| 140 | icon: ibm-i.png |
| 141 | categories: |
| 142 | - data-collection.operating-systems |
| 143 | link: https://www.ibm.com/products/power-systems |
| 144 | keywords: |
| 145 | - ibm i |
| 146 | - as400 |
| 147 | - system i |
| 148 | - os400 |
| 149 | - power systems |