#IBM i (AS/400)

Plugin: ibm.d.plugin Module: as400

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

Config options

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

#via File

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

You can edit the configuration file using the edit-config script from the Netdata config directory.

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

#Examples

#Basic

Basic configuration example.

Config

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

#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