<!--startmeta
custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/go/plugin/ibm.d/modules/as400/README.md"
meta_yaml: "https://github.com/netdata/netdata/edit/master/src/go/plugin/ibm.d/modules/as400/metadata.yaml"
sidebar_label: "IBM i (AS/400)"
learn_status: "Published"
learn_rel_path: "Collecting Metrics/Collectors/Operating Systems"
keywords: ['as400']
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
endmeta-->

# IBM i (AS/400)


<img src="https://netdata.cloud/img/ibm-i.png" width="150"/>


Plugin: ibm.d.plugin
Module: as400

<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />

## Overview

Monitors IBM i (AS/400) systems using SQL services and CL commands to
expose CPU, memory, storage, job, and subsystem activity.

**Dependencies:**
- unixODBC 2.3+ with IBM i Access ODBC driver
- IBM i 7.2 or later with SQL services enabled

**Required Libraries:**
- libodbc.so (provided by unixODBC)
- IBM i Access Client Solutions

**Collection paths**

The collector executes queries in multiple tracks:

- **Fast path (5s)**: lightweight system status queries remain sequential on the main plugin thread.
- **Slow path (10s beat)**: heavier queries (per-queue metrics, subsystems, plan cache, etc.) run in a background worker with bounded concurrency.
- **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.

**CPU Collection Methods:**

The collector uses a hybrid approach for CPU utilization metrics to handle IBM i 7.4+ where
`AVERAGE_CPU_*` columns were deprecated:

1. **Primary Method - TOTAL_CPU_TIME**: Uses the monotonic `TOTAL_CPU_TIME` counter from
   `QSYS2.SYSTEM_STATUS()` to calculate CPU utilization via delta-based calculation. This is
   the most accurate method but requires `*JOBCTL` special authority. TOTAL_CPU_TIME is a
   cumulative counter in nanoseconds representing CPU-seconds consumed, naturally in per-core
   scale.

2. **Fallback Method - ELAPSED_CPU_USED**: If `*JOBCTL` authority is not available, falls back
   to `ELAPSED_CPU_USED` with automatic reset detection. This method tracks when IBM i statistics
   are reset (either manually or via `reset_statistics` configuration) and re-establishes a
   baseline after detecting resets. The values are already in per-core scale.

3. **Legacy Method - AVERAGE_CPU_UTILIZATION**: For IBM i versions before 7.4, uses the now-
   deprecated `AVERAGE_CPU_UTILIZATION` column, which IBM reports in the same per-core scale.

The collector automatically selects the appropriate method based on available permissions and
logs which method is being used.

**CPU Metric Scale:**

CPU utilization is reported using the "100% = 1 CPU core" semantic. This means:
- 100% indicates one CPU core is fully utilized
- 400% indicates four CPU cores are fully utilized
- Values are limited to 100% × ConfiguredCPUs, matching the partition's configured capacity

For shared LPARs, the metrics show absolute CPU consumption in per-core scale, not relative to
entitled capacity. For example, a shared LPAR entitled to 0.20 cores can show 150% utilization
when bursting above entitlement.

**Statistics Reset Behavior:**

The `reset_statistics` configuration option controls whether the collector resets IBM i system
statistics on each query via `SYSTEM_STATUS(RESET_STATISTICS=>'YES')`. When enabled:

- System-level statistics (CPU, memory pools, etc.) are reset after each collection cycle
- Matches legacy behavior but clears global statistics that other tools may rely on
- The ELAPSED_CPU_USED fallback method will detect and handle these resets automatically
- **Caution**: Enabling this affects all users and applications on the IBM i system

Default: `false` (statistics are not reset, using `RESET_STATISTICS=>'NO'`)

**Chart Gaps During Baseline Resets:**

The `as400.system_activity_cpu_rate` and `as400.system_activity_cpu_utilization` charts rely on
delta calculations. When the collector detects that IBM i reset these statistics—or when it is
still establishing the initial baseline—it intentionally skips a sample instead of emitting a zero
or spike. Netdata renders those skipped samples as small gaps, which is expected behaviour.

**Cardinality Management:**

To prevent performance issues from excessive metric creation, the collector enforces cardinality
limits on per-instance metrics (disks, subsystems, job queues, message queues, output queues,
active jobs, network interfaces, HTTP servers).

**How Limits Work:**
- The collector counts instances before collecting metrics
- If count exceeds the configured `max_*` limit, **collection is skipped entirely** for that category
- The collector logs a warning: `"[category] count (X) exceeds limit (Y), skipping collection"`
- No metrics are collected for that category until you adjust the configuration

**Configuration Options:**

Use **both** limit and selector options together to manage high-cardinality environments:

| Option | Purpose | Default |
|--------|---------|---------|
| `max_disks` | Maximum disk units to monitor | 100 |
| `max_subsystems` | Maximum subsystems to monitor | 100 |
| `max_job_queues` | Maximum job queues to monitor | 100 |
| `max_message_queues` | Maximum message queues to monitor | 100 |
| `max_output_queues` | Maximum output queues to monitor | 100 |
| `active_jobs` | Fully qualified active jobs to monitor (`JOB_NUMBER/USER/JOB_NAME`) | `[]` |
| `collect_disks_matching` | Glob pattern to filter disks (e.g., `"001* 002*"`) | `""` (match all) |
| `collect_subsystems_matching` | Glob pattern to filter subsystems (e.g., `"QINTER QBATCH"`) | `""` (match all) |
| `collect_job_queues_matching` | Glob pattern to filter job queues (e.g., `"QSYS/*"`) | `""` (match all) |

Optional batch-path controls:

| Option | Purpose | Default |
|--------|---------|---------|
| `batch_path` | Enables the long-period batch worker for aggregate queries | `false` |
| `batch_path_update_every` | Batch worker cadence (minimum 60s, recommend ≥600s in production) | `60s` |
| `batch_path_max_connections` | Maximum concurrent connections for batch queries | `1` |
| `collect_message_queue_totals` | Enables full-scan counting of all message queues and messages | `auto` (off) |
| `collect_job_queue_totals` | Enables aggregate counting of job queues and queued jobs | `auto` (off) |
| `collect_output_queue_totals` | Enables aggregate counting of output queues and spooled files | `auto` (off) |

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


**Example Workflow:**

1. System has 500 disks, collector skips disk metrics (exceeds default limit of 100)
2. Check logs: `"disk count (500) exceeds limit (100), skipping per-disk metrics"`
3. Two options:
   - **Option A**: Increase limit: `max_disks: 500` (collects all 500 disks)
   - **Option B**: Use selector: `collect_disks_matching: "00[1-5]*"` (cherry-pick specific disks)

**Best Practices:**
- Use selectors to monitor only business-critical objects in large environments
- Set limits based on your Netdata server's capacity (each instance = multiple charts)
- Start with defaults and adjust based on actual usage patterns

**IBM i 7.2–7.3 Behavior Note (Message Queues):**

IBM i 7.4 introduced a message-queue table function that returns only the live backlog. On
7.2–7.3 systems we fall back to the `QSYS2.MESSAGE_QUEUE_INFO` view, which includes *all*
recorded messages (even those already processed/cleared from the queue). Aggregations—especially
`MAX(SEVERITY)`—therefore reflect the historical log, not just the outstanding backlog. This
behaviour is inherent to the IBM SQL service and can lead to higher-than-expected max severity
values on pre-7.4 systems.

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.


The collector connects to IBM i (AS/400) and collects metrics via its monitoring interface.


This collector is supported on all platforms.

This collector supports collecting metrics from multiple instances of this integration, including remote instances.


### Default Behavior

#### Auto-Detection

This integration doesn't support auto-detection.

#### Limits

The default configuration for this integration does not impose any limits on data collection.

#### Performance Impact

The default configuration for this integration is not expected to impose a significant performance impact on the system.

## Setup


### Prerequisites

#### Enable monitoring interface

Ensure the IBM i (AS/400) monitoring interface is accessible.



### Configuration

#### Options

Configuration options for the as400 collector.


<details open><summary>Config options</summary>



| Option | Description | Default | Required |
|:-----|:------------|:--------|:---------:|
| update_every | Data collection frequency. | 1 | no |
| endpoint | Connection endpoint. | dummy://localhost | no |


</details>



#### via File

The configuration file name for this integration is `ibm.d/as400.conf`.


You can edit the configuration file using the [`edit-config`](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#edit-configuration-files) script from the
Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#locate-your-config-directory).

```bash
cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config ibm.d/as400.conf
```

##### Examples

###### Basic

Basic configuration example.

<details open><summary>Config</summary>

```yaml
jobs:
  - name: local
    endpoint: dummy://localhost

```
</details>



## Alerts

There are no alerts configured by default for this integration.


## Metrics

Metrics grouped by *scope*.

The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.



### Per activejob

These metrics refer to activejob instances.

Labels:

| Label      | Description     |
|:-----------|:----------------|
| job_name | Job_name identifier |
| job_status | Job_status identifier |
| subsystem | Subsystem identifier |
| job_type | Job_type identifier |

Metrics:

| Metric | Dimensions | Unit |
|:------|:----------|:----|
| as400.activejob_cpu | cpu | percentage |
| as400.activejob_resources | temp_storage | MiB |
| as400.activejob_time | cpu_time, total_time | seconds |
| as400.activejob_activity | disk_io, interactive_transactions | operations/s |
| as400.activejob_threads | threads | threads |

### Per disk

These metrics refer to disk instances.

Labels:

| Label      | Description     |
|:-----------|:----------------|
| disk_unit | Disk_unit identifier |
| disk_type | Disk_type identifier |
| disk_model | Disk_model identifier |
| hardware_status | Hardware_status identifier |
| disk_serial_number | Disk_serial_number identifier |

Metrics:

| Metric | Dimensions | Unit |
|:------|:----------|:----|
| as400.disk_busy | busy | percentage |
| as400.disk_io_requests | read, write | requests/s |
| as400.disk_space_usage | used | percentage |
| as400.disk_capacity | available, used | gigabytes |
| as400.disk_blocks | read, write | blocks/s |
| as400.disk_ssd_health | life_remaining | percentage |
| as400.disk_ssd_age | power_on_days | days |

### Per httpserver

These metrics refer to httpserver instances.

Labels:

| Label      | Description     |
|:-----------|:----------------|
| server | Server identifier |
| function | Function identifier |

Metrics:

| Metric | Dimensions | Unit |
|:------|:----------|:----|
| as400.http_server_connections | normal, ssl | connections |
| as400.http_server_threads | active, idle | threads |
| as400.http_server_requests | requests, responses, rejected | requests/s |
| as400.http_server_bytes | received, sent | bytes/s |

### Per jobqueue

These metrics refer to jobqueue instances.

Labels:

| Label      | Description     |
|:-----------|:----------------|
| job_queue | Job_queue identifier |
| library | Library identifier |
| status | Status identifier |

Metrics:

| Metric | Dimensions | Unit |
|:------|:----------|:----|
| as400.jobqueue_length | jobs | jobs |

### Per messagequeue

These metrics refer to messagequeue instances.

Labels:

| Label      | Description     |
|:-----------|:----------------|
| library | Library identifier |
| queue | Queue identifier |

Metrics:

| Metric | Dimensions | Unit |
|:------|:----------|:----|
| as400.message_queue_messages | total, informational, inquiry, diagnostic, escape, notify, sender_copy | messages |
| as400.message_queue_severity | max | severity |

### Per networkinterface

These metrics refer to networkinterface instances.

Labels:

| Label      | Description     |
|:-----------|:----------------|
| interface | Interface identifier |
| interface_type | Interface_type identifier |
| connection_type | Connection_type identifier |
| internet_address | Internet_address identifier |
| network_address | Network_address identifier |
| subnet_mask | Subnet_mask identifier |

Metrics:

| Metric | Dimensions | Unit |
|:------|:----------|:----|
| as400.network_interface_status | active | status |
| as400.network_interface_mtu | mtu | bytes |

### Per IBM i (AS/400) instance

These metrics refer to the entire monitored instance.

This scope has no labels.

Metrics:

| Metric | Dimensions | Unit |
|:------|:----------|:----|
| netdata.plugin_ibm.as400_query_latency_fast | count_disks, count_http_servers, count_network_interfaces, detect_ibmi_version_primary, detect_ibmi_version_fallback, disk_instances, disk_instances_enhanced, disk_status, http_server_info, job_info, memory_pools, network_connections, network_interfaces, serial_number, system_name, system_activity, system_model, system_status, temp_storage_named, temp_storage_total, technology_refresh_level, active_job | ms |
| netdata.plugin_ibm.as400_query_latency_slow | analyze_plan_cache, count_subsystems, subsystems, message_queue_aggregates, job_queues, output_queue_info, plan_cache_summary | ms |
| netdata.plugin_ibm.as400_query_latency_batch | message_queue_totals, job_queue_totals, output_queue_totals | ms |

### Per outputqueue

These metrics refer to outputqueue instances.

Labels:

| Label      | Description     |
|:-----------|:----------------|
| library | Library identifier |
| queue | Queue identifier |
| status | Status identifier |

Metrics:

| Metric | Dimensions | Unit |
|:------|:----------|:----|
| as400.output_queue_files | files | files |
| as400.output_queue_writers | writers | writers |
| as400.output_queue_status | released | state |

### Per plancache

These metrics refer to plancache instances.

Labels:

| Label      | Description     |
|:-----------|:----------------|
| metric | Metric identifier |

Metrics:

| Metric | Dimensions | Unit |
|:------|:----------|:----|
| as400.plan_cache_summary | value | value |

### Per queueoverview

These metrics refer to queueoverview instances.

Labels:

| Label      | Description     |
|:-----------|:----------------|
| queue_type | Queue_type identifier |
| item_type | Item_type identifier |

Metrics:

| Metric | Dimensions | Unit |
|:------|:----------|:----|
| as400.queues_count | queues | queues |
| as400.queued_items | items | items |

### Per subsystem

These metrics refer to subsystem instances.

Labels:

| Label      | Description     |
|:-----------|:----------------|
| subsystem | Subsystem identifier |
| library | Library identifier |
| status | Status identifier |

Metrics:

| Metric | Dimensions | Unit |
|:------|:----------|:----|
| as400.subsystem_jobs | active, maximum | jobs |

### Per IBM i (AS/400) instance

These metrics refer to the entire monitored instance.

This scope has no labels.

Metrics:

| Metric | Dimensions | Unit |
|:------|:----------|:----|
| as400.cpu_utilization | utilization | percentage |
| as400.cpu_utilization_entitled | utilization | percentage |
| as400.cpu_configuration | configured | cpus |
| as400.cpu_capacity | capacity | percentage |
| as400.total_jobs | total | jobs |
| as400.active_jobs_by_type | batch, interactive, active | jobs |
| as400.job_queue_length | waiting | jobs |
| as400.main_storage_size | total | bytes |
| as400.temporary_storage | current, maximum | MiB |
| as400.memory_pool_usage | machine, base, interactive, spool | bytes |
| as400.memory_pool_defined | machine, base | bytes |
| as400.memory_pool_reserved | machine, base | bytes |
| as400.memory_pool_threads | machine, base | threads |
| as400.memory_pool_max_threads | machine, base | threads |
| as400.disk_busy_average | busy | percentage |
| as400.system_asp_usage | used | percentage |
| as400.system_asp_storage | total | MiB |
| as400.total_auxiliary_storage | total | MiB |
| as400.system_threads | active, per_processor | threads |
| as400.network_connections | remote, total | connections |
| as400.network_connection_states | listen, close_wait | connections |
| as400.temp_storage_total | current, peak | bytes |
| as400.system_activity_cpu_rate | average | percentage |
| as400.system_activity_cpu_utilization | average, minimum, maximum | percentage |

### Per tempstoragebucket

These metrics refer to tempstoragebucket instances.

Labels:

| Label      | Description     |
|:-----------|:----------------|
| bucket | Bucket identifier |

Metrics:

| Metric | Dimensions | Unit |
|:------|:----------|:----|
| as400.temp_storage_bucket | current, peak | bytes |


