IBM i

Overview Copied

The IBM i Collection Agent plugin collects metrics from the IBM i (AS/400) systems using JTOpen APIs. The plugin publishes metrics into Geneos as Dynamic Entity data and does not require any additional software to be installed on the monitored IBM i host.

The plugin enhances Geneos enterprise monitoring by providing native visibility into IBM i system, subsystem, and memory pool metrics, enabling consistent monitoring alongside on-premise, cloud, and hybrid environments.

The IBM i Collection Agent plugin allows you to:

Monitor IBM i systems using a standard Geneos Collection Agent deployment.
Combine IBM i metrics with metrics from other platforms in a single Geneos view.
Use Dynamic Entity mappings to reduce Gateway configuration effort.
Detect performance and capacity issues using Geneos rules and alerts.

Monitored services Copied

You can use the IBM i plugin to monitor different IBM i services by using the following services within the Collection Agent configuration:

IBMi/System Copied

The IBMi/System service collects system-level metrics, including:

CPU utilisation and processor attributes
System uptime and partition information
Memory usage
Disk and ASP usage
- Disk usage
- ASP capacity and utilisation
- Storage thresholds
Hardware attributes

Disk metrics are collected using a tiered approach to maximise compatibility:

Native IBM i program calls.
SQL-based system views.
Legacy aggregate ASP metrics.

IBMi/Subsystem Copied

The IBMi/Subsystem service collects subsystem-level metrics, including:

Subsystem status
Active job counts
Assigned memory pools
Subsystem attributes (this can be filtered by library, name, and status).

IBMi/Pool Copied

The IBMi/Pool service collects memory pool metrics, including:

Pool size and reserved size
Activity level and max active threads
Database and non-database faults/pages.
Transition rates (active-to-wait, wait-to-ineligible, active-to-ineligible)
Pool attributes (name, shared flag, paging option)
System totals: pool count, total auxiliary storage, system ASP and utilisation, partition ID

Prerequisites Copied

Geneos environment Copied

The IBM i Collection Agent plugin requires the following Geneos components:

Gateway and Netprobe 7.1.x or higher.
Collection Agent 5.x or higher.

Java must be available in the Collection Agent runtime environment.

IBM i environment Copied

The IBM i plugin requires:

A valid IBM i user profile.
Authority to query system, subsystem, and memory pool information.

*ALLOBJ special authority is recommended to ensure full metric coverage.

Network connectivity Copied

The Collection Agent must be able to connect to the IBM i host servers on the following JTOpen host service ports:

Non-TLS — TCP 446, 449, 8470–8476
TLS — TCP 448, 9470-9476

Security and TLS Copied

TLS is enabled when tlsConfig is provided in the collection-agent.yml file. The IBM i connection uses SecureAS400 with the supplied certificates. The connection uses plaintext if tlsConfig is omitted.

This is an example of the tlsConfig using environment variables:

tlsConfig:
  certFile: ${env:CERT_FILE}
  keyFile: ${env:KEY_FILE}
  trustChainFile: ${env:TRUST_CHAIN_FILE}

The trustChainFile should contain the CA certificates used by the IBM i server. Specify the certFile and keyFile to enable mutual TLS when required by the server.

Converting a private key to PKCS#8 format Copied

The keyFile must be in PKCS#8 format (BEGIN PRIVATE KEY). Traditional RSA or EC key formats are not supported. Run the following command to convert an existing key:

openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in key.pem -out key-pkcs8.pem

Configure Geneos to deploy the IBM i plugin Copied

The IBM i plugin supports Collection Agent publication into Geneos using Dynamic Managed Entities. Setting up this plugin in Geneos involves the following steps:

Set up your Collection Agent plugin.
Configure your mappings.
Configure other Dynamic Entities in the Gateway, see Create Dynamic Entities in Collection Agent setup for a more detailed procedure.

Set up your Collection Agent plugin Copied

You can configure the IBM i plugin by adding the following configuration to the collection-agent.yml file. Set up your collector in the Gateway Setup Editor by adding the following configuration in Dynamic Entities > Collectors. For more information, see Collectors in Dynamic Entities.

collectors:
- name: ibmiCollector
  type: plugin
  className: IbmiCollector

  # Interval between collections (optional, default = 60000 ms)
  collectionInterval: 60000

  # IBM i connection details (required)
  systemName: ibmi.example.com
  username: cecuser
  password: ${env:IBMI_PASSWORD}

  # Connection timeout in seconds (optional, default = 20)
  connectionTimeout: 20

  # TLS configuration (optional).
  # When specified, the connection uses SecureAS400 with the supplied certificates.
  # If omitted, the connection uses plaintext (insecure).
  tlsConfig:
    # Path to the PEM file containing trusted CA certificates (required for TLS)
    trustChainFile: ${env:TRUST_CHAIN_FILE}

    # Path to the PEM file containing the client certificate (optional, for mutual TLS)
    certFile: ${env:CERT_FILE}

    # Path to the PEM file containing the client private key in PKCS#8 format (optional, for mutual TLS)
    keyFile: ${env:KEY_FILE}

  # Collection-level defaults (optional).
  # Applied to all services that support the setting, unless overridden per-service.
  defaults:
    maxRows: 20

  # Which services to enable (optional).
  # If omitted or empty, all services are enabled.
  enabledServices:
  - IBMi/System
  - IBMi/Subsystem
  - IBMi/Pool

  # Per-service settings (optional).
  # Only needed when a service has configurable parameters.
  # Per-service values take precedence over collection-level defaults.
  serviceConfigs:
    subsystem:
      filters:
        library: "*ALL"
        name: "*ALL"
        status:
        - ACTIVE
        - ENDING
        - INACTIVE
        - RESTRICTED
        - STARTING
        maxRows: 20

All services are enabled by default when enabledServices is omitted or empty. When enabledServices is provided, only the listed services are enabled.

Subsystem filtering Copied

Subsystem monitoring supports filtering to reduce data volume. Configure filters in the serviceConfigs.subsystem.filters block.

Default values:

library: *ALL
name: *ALL
status: ACTIVE, ENDING, INACTIVE, RESTRICTED, STARTING
maxRows: 20 (can be overridden by defaults.maxRows)

The maxRows value is resolved using this cascade:

serviceConfigs.subsystem.filters.maxRows — per-service override (highest priority).
defaults.maxRows — collection-level default.
Internal default (20) — used when neither is specified.

Example:

serviceConfigs:
  subsystem:
    filters:
      library: "*ALLUSR"
      name: "QC*"
      status:
      - ACTIVE
      - STARTING
      maxRows: 50

Configure your mappings Copied

To display metrics in Geneos, Dynamic Entity mappings must be configured and attached to the Netprobe receiving data from the Collection Agent.

You can configure mappings using one of the following options:

Adding templates/ibmi_mapping.xml as an include file in your Gateway.
Setting up a custom mapping in Dynamic Entities > Mapping. For more information, see Mapping and mapping group in Dynamic Entities.

The provided mapping template creates Dynamic Entities for IBM i systems, subsystems, and memory pools.

Example dataview Copied

Once the plugin and mappings are configured, IBM i metrics are displayed in Geneos dataviews for systems, subsystems, and memory pools.

These are examples of dataviews for IBMi/System metrics. For CPU metrics:

IBMi/System CPU metrics

For disk metrics:

IBMi/System disk metrics

For hardware metrics:

IBMi/System hardware metrics

This is an example of a dataview for IBMi/Subsystem metrics:

IBMi/Subsystem metrics

These are examples of dataviews for IBMi/Pool metrics. For pool metrics:

IBMi/Pool metrics

For pool ID metrics:

IBMi/Pool pool ID metrics

Previous article Next article