IBM i

Overview Copied

The IBM i Collection Agent plugin collects metrics from 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 health, subsystem activity, memory pools, message queues, jobs, physical file members, and IFS log files. Use it for consistent monitoring alongside on-premises, 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 configuring the following service namespaces within the Collection Agent configuration:

IBMi/System Copied

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

• CPU utilization, processing capacity, interactive performance, DB capability, shared processor pool usage, uncapped CPU capacity, number of processors, and processor sharing attributes.
• Per-disk total space, free space, percent used, percent busy, unit number, disk name, and disk type.
• Hardware attributes such as system identifier, OS version, country/language, processor feature, model, serial number, timezone, main storage size, permanent and temporary address usage, and uptime.

Disk metrics are collected through IBM i program-call list APIs, including QYASPOL, QGYGTLE, and QGYCLST.

IBMi/Subsystem Copied

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

• Number of subsystem rows matching the configured filters.
• Subsystem status (ACTIVE, ENDING, INACTIVE, RESTRICTED, STARTING, or runtime fallback UNKNOWN).
• Active job counts and maximum active jobs.
• Number of assigned memory pools.
• Subsystem attributes such as name and library.

Results 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 such as name, shared flag, and paging option.
• System totals such as pool count, inactive pools skipped, total auxiliary storage, system ASP size and usage, and partition ID.

IBMi/Queue Copied

The IBMi/Queue service discovers message queues and collects per-queue message counts, including:

• Number of message queues matching configured filters.
• Per-queue message count.

Queue discovery can be filtered by library and queue name using wildcards.

IBMi/Message Copied

The IBMi/Message service monitors message queues and emits log events for individual messages, including:

• Messages emitted as log events in the current collection run.
• Messages matching filters in the current collection run.
• Per-message log events containing key, ID, severity, type, text, and sender metadata.

Use IBMi/Queue when you need queue-depth metrics. IBMi/Message focuses on filtered message event streaming and cycle counts.

Messages can be filtered by:

• Minimum severity.
• Sender job name regex.
• Sender job user regex.

The optional readFromBeginning setting determines where reading starts and how backlog is handled. The collector tracks its position in memory per queue across collection cycles.

IBMi/Job Copied

The IBMi/Job service collects job-level headline metrics and per-job log events, including:

• Total jobs, total active jobs, max jobs, total batch jobs.
• Number of jobs matching configured filters.
• Per-job log events with job number, user, type, status, subsystem, priority, timestamps, end reason, elapsed time, and optional CPU statistics.

Jobs can be filtered by status, type, user, subsystem, and name. Job name filtering supports Java regex mode or pipe-separated IBM i wildcard segments.

IBMi/MemberRecord Copied

The IBMi/MemberRecord service monitors physical file member record usage, including:

• Current record count
• Record capacity
• Percent usage

Monitored files are specified as QSYS paths, such as:

• /QSYS.LIB/<LIB>.LIB/<FILE>.FILE
• /QSYS.LIB/<LIB>.LIB/<FILE>.FILE/<MEMBER>
• /QSYS.LIB/<LIB>.LIB/<FILE>.FILE/<MEMBER>.MBR

Member paths without .MBR are normalized automatically.

IBMi/FileMember Copied

The IBMi/FileMember service monitors physical file member counts and capacity, including:

• Current member count
• Member capacity
• Percent usage

Monitored files are specified as QSYS file paths: /QSYS.LIB/<LIB>.LIB/<FILE>.FILE.

IBMi/LogReader Copied

The IBMi/LogReader service tails IFS log files and streams lines as log events, including:

• Number of active monitored log file streams.
• Per-file status (OK, FILE_NOT_FOUND, READ_ACCESS_DENIED, FILE_IO_ERROR, INITIALISING).
• Cumulative messages received per file since service start.
• Per-line log events with raw log text.

File names support * and ? wildcards. The rewind option forces reads from the start of the file. File position tracking can be enabled to persist read offsets across restarts.

Prerequisites Copied

Geneos environment Copied

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

• Gateway and Netprobe 7.1.x or higher for Dynamic Entity publication.
• Collection Agent 6.0.0 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, memory pool, job, message queue, physical file member, and IFS file information.

*ALLOBJ special authority is recommended to ensure full metric coverage. Alternatively, a custom authority profile with equivalent access to the required APIs can be used.

Network connectivity Copied

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

Security and TLS Copied

TLS is enabled when at least one field in tlsConfig is provided in the collection-agent.yml file. The IBM i connection uses SecureAS400 with the supplied certificates. The connection uses plain text if tlsConfig is omitted.

Note

For a plain text connection, omit the whole tlsConfig key. Blank TLS file path values are invalid and prevent collector startup.

This is an example of the tlsConfig using environment variables:

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

Note

Specify certFile and keyFile together to enable mutual TLS when required by the server. The trustChainFile is optional but when provided, it must point to a valid and readable PEM trust chain file.

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:

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

Set up your Collection Agent plugin Copied

Use one of the following options to configure the plugin:

• 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.
• Add the following configuration to the collection-agent.yml file on your local machine.

Minimum configuration Copied

This is the minimum configuration to begin collecting IBM i system metrics:

collectors:
  - name: ibmiCollector
    type: plugin
    className: IbmiCollector
    systemName: ibmi.example.com
    username: ibmiuser
    password: ${env:IBMI_PASSWORD}
    services:
      - name: IBMi/System

Full configuration Copied

This is a full configuration template:

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

    # Interval between collections in milliseconds (optional, default: 60000)
    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; secure mode when any field is set)
    tlsConfig:
      trustChainFile: ${env:TRUST_CHAIN_FILE}
      certFile: ${env:CERT_FILE}
      keyFile: ${env:KEY_FILE}

    # Services to enable (required; at least one recognized service must be listed)
    services:
      - name: IBMi/System

      - name: IBMi/Pool

      - name: IBMi/Subsystem
        config:
          filters:
            library: "*ALL"
            name: "*ALL"
            status:
              - ACTIVE
              - ENDING
              - INACTIVE
              - RESTRICTED
              - STARTING

      - name: IBMi/Queue
        config:
          filters:
            - library: "*ALL"
              name: "*ALL"

      - name: IBMi/Message
        config:
          queues:
            - queuePath: "/QSYS.LIB/QSYSOPR.MSGQ"
              filter:
                severity: 0
                senderJobName: ""
                senderJobUser: ""
              readFromBeginning: false

      - name: IBMi/Job
        config:
          filters:
            status: ""
            type: ""
            user: ""
            subsystem: ""
            name: ""
            nameUseRegex: true
          enableCpuStatistics: true

      - name: IBMi/MemberRecord
        config:
          filePaths:
            - "/QSYS.LIB/QUSRSYS.LIB/MYFILE.FILE"

      - name: IBMi/FileMember
        config:
          filePaths:
            - "/QSYS.LIB/MYLIB.LIB/MYFILE.FILE"

      - name: IBMi/LogReader
        config:
          files:
            - filename: /www/myapp/logs/access.log
            - filename: /QOpenSys/var/log/app_*.log
            - filename: /tmp/debug.log
              rewind: true
          workerPoolSize: 10
          filePositionEnabled: true
          filePositionMaxInactiveDays: 7

Collector configuration settings Copied

Service configuration settings Copied

Configure the services under services[].config.

Each service is listed under services with a name and an optional config block. For IBMi/System and IBMi/Pool, include only the name field as no config block is required.

IBMi/Subsystem Copied

For example, to monitor only active subsystems in user libraries starting with QC:

- name: IBMi/Subsystem
  config:
    filters:
      library: "*ALLUSR"
      name: "QC*"
      status:
        - ACTIVE
        - STARTING

IBMi/Queue Copied

For example, to monitor queues in a specific library:

- name: IBMi/Queue
  config:
    filters:
      - library: "MYLIB"
        name: "*ALL"

IBMi/Message Copied

For example, to monitor QSYSOPR with severity filter:

- name: IBMi/Message
  config:
    queues:
      - queuePath: "/QSYS.LIB/QSYSOPR.MSGQ"
        filter:
          severity: 40
        readFromBeginning: false
      - queuePath: "/QSYS.LIB/MYLIB.LIB/MYQUEUE.MSGQ"
        filter:
          severity: 0
          senderJobName: "QPADEV.*"

IBMi/Job Copied

For example, to monitor only active batch jobs:

- name: IBMi/Job
  config:
    filters:
      status: "ACTIVE"
      type: "BATCH"
    enableCpuStatistics: true

IBMi/MemberRecord Copied

For example:

- name: IBMi/MemberRecord
  config:
    filePaths:
      - "/QSYS.LIB/QUSRSYS.LIB/QAYPUSR.FILE"
      - "/QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MEMBER1.MBR"

IBMi/FileMember Copied

For example:

- name: IBMi/FileMember
  config:
    filePaths:
      - "/QSYS.LIB/MYLIB.LIB/MYFILE.FILE"
      - "/QSYS.LIB/PRODLIB.LIB/ORDERS.FILE"

IBMi/LogReader Copied

For example:

- name: IBMi/LogReader
  config:
    files:
      - filename: /www/myapp/logs/access.log
      - filename: /QOpenSys/var/log/app_*.log
      - filename: /tmp/debug.log
        rewind: true
    workerPoolSize: 5
    filePositionEnabled: true
    filePositionMaxInactiveDays: 14

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:

• Add the provided ibmi_mapping.xml as an include file in your Gateway.
• Set 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 and includes an FKM sampler (ibmi-logs-fkm) for log event streaming from message queues, jobs, and IFS log files. The FKM sampler categorizes log events by severity:

• CRITICAL and ERROR events mapped to fail severity.
• WARN and INFO events mapped to warning severity.

Example dataview Copied

Once the plugin and mappings are configured, IBM i metrics are displayed in Geneos dataviews. These are dataview examples for metrics collected per service.

IBMi/System dataview Copied

System metrics which can be monitored by other services will be displayed in their respective services. For example, maxJobs will be monitored by Job service.

IBMi/Subsystem dataview Copied

Subsystems matching filter shows the number of subsystem entities matching the configuration filter.

IBMi/Job dataview Copied

Jobs matching filter shows the number of job data streams matching the configuration filter. These streams are monitored through the FKM.

IBMi/Pool dataview Copied

This view shows the storage pools and its corresponding metrics by pool ID.

IBMi/Queue dataview Copied

Queues matching filter shows the number of queue entities matching the configuration filter.

IBMi/Message dataview Copied

This view shows the number of messages being monitored based on the configuration. Message streams are monitored through the FKM.

In this example, only one message is streamed from /QSYS.LIB/QUSRSYS.LIB/QLWISVR.MSGQ.

IBMi/MemberRecord dataview Copied

This view shows the physical file member record usage metrics.

IBMi/FileMember dataview Copied

This view shows the physical file member count and capacity metrics.

IBMi/LogReader dataview Copied

This view shows the number of log files being monitored based on the configuration. Log file streams are monitored through the FKM.

Metrics Copied

All service data points include the data point property service=<service namespace>. The global dimension ibmi_system identifies the IBM i system. Service-specific dimensions, such as disk_id, subsystem_key, message_queue_path, job_name, file_path, member, and log_file_path, identify lower-level entities.

IBMi/System metrics Copied

IBMi/Subsystem metrics Copied

IBMi/Pool metrics Copied

IBMi/Queue metrics Copied

IBMi/Message metrics Copied

IBMi/Job metrics Copied

IBMi/MemberRecord metrics Copied

IBMi/FileMember metrics Copied

IBMi/LogReader metrics Copied

Connection behavior Copied

The plugin uses one IBM i connection manager per collector instance.

• On startup, the plugin validates the configuration and attempts an initial connection health check.
• If the initial connection fails, the collector still starts and retries on subsequent collection cycles.
• Before each collection cycle, the connection health is verified. If unhealthy, the plugin disconnects once and reconnects.
• If the reconnection also fails, that collection cycle is skipped. Later cycles continue retrying until the connection becomes healthy.
• TLS validation failures (invalid paths, malformed PEM files, unsupported key formats) fail startup before any collection begins.
• Unknown values for services[].name are logged and dropped at collector validation. At least one recognized IBM i service must remain.

Validation behavior Copied

• Collector-level validation failures (systemName, username, password, services, connectionTimeout, collectionInterval, tlsConfig) prevent collector startup.
• Service-level validation failures skip only the affected service entry, while other services continue.
• For list-based configs (queues, filters, filePaths, files), invalid entries are removed with a warning. If no valid entries remain, that service is skipped.
• If all services are skipped, the collector startup fails.
• String values are trimmed before validation unless explicitly defined as raw text or regex.