IBM i quickstart guide

This quickstart guide helps you configure and validate IBM i Collection Agent plugin services using minimal sample configurations.

Start with a basic IBM i server connection, verify connectivity with IBMi/System, and then enable additional monitoring services one at a time. Each section includes a small working example, placeholder values to replace, and the metrics or events you should expect to see.

This guide focuses on common monitoring scenarios and initial validation. For complete configuration details and service reference information, refer to the IBM i user guide.

How to use this guide Copied

1. Use one section at a time. Start with IBM i server connection.
2. Confirm that the collector can connect by enabling IBMi/System.
3. Add one monitoring service at a time.
4. Replace the sample host, user, password, queue names, file paths, and log paths with your IBM i values.

The following placeholders appear throughout this guide:

Important

Keep service names exactly as shown. For example, use IBMi/System, not ibmi/system.

IBM i server connection Copied

The collector needs IBM i connection details before any service can collect data.

Use a user profile that has authority to read the IBM i resources you want to monitor. For an initial setup, start with IBMi/System because it does not require extra service configuration.

Basic connection without TLS Copied

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

This example does the following:

• Connects to ibmi.example.com.
• Uses ibmiuser as the IBM i user profile.
• Collects data every 60 seconds.
• Enables only IBMi/System as a basic connectivity test.

Connection with TLS Copied

Use TLS when the IBM i host servers are configured for secure connections.

collectors:
  - name: ibmiCollectorTls
    type: plugin
    className: IbmiCollector
    systemName: ibmi.example.com
    username: ibmiuser
    password: ${env:IBMI_PASSWORD}
    collectionInterval: 60000
    connectionTimeout: 20
    tlsConfig:
      trustChainFile: /secure/certs/ibmi-trust-chain.pem
    services:
      - name: IBMi/System

Connection with mutual TLS Copied

Use mutual TLS when the IBM i server requires a client certificate.

collectors:
  - name: ibmiCollectorMtls
    type: plugin
    className: IbmiCollector
    systemName: ibmi.example.com
    username: ibmiuser
    password: ${env:IBMI_PASSWORD}
    collectionInterval: 60000
    connectionTimeout: 20
    tlsConfig:
      trustChainFile: /secure/certs/ibmi-trust-chain.pem
      certFile: /secure/certs/client-cert.pem
      keyFile: /secure/certs/client-key-pkcs8.pem
    services:
      - name: IBMi/System

Connection notes Copied

• Store the password value in an environment variable or secret.
• Non-TLS IBM i host servers typically use TCP ports 8470 through 8476.
• TLS IBM i host servers typically use TCP ports 9470 through 9476.
• You must also configure keyFile if you configure certFile.
• The keyFile value must be a PKCS#8 PEM private key.

Monitoring IBMi/System metrics Copied

Use IBMi/System to monitor general IBM i health.

This service collects system-level metrics such as CPU usage, disk capacity, disk busy percentage, main storage size, system attributes, and uptime.

Use cases:

• First connection test.
• CPU and disk monitoring.
• Basic IBM i system inventory.
• High-level system health dashboards.

Sample configuration Copied

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

Example output:

• percentProcessingUnitUsed
• mainStorageSize
• upTime
• totalSpace
• freeSpace
• percentUsed
• percentBusy
• systemModel
• systemSerialNo

Important

If this service does not publish data, verify the host, credentials, network ports, and IBM i user authority before you test other services.

Monitoring IBMi/Job metrics Copied

Use IBMi/Job to monitor IBM i job counts and publish details for jobs that match the configured filter.

This service collects total jobs, active jobs, maximum jobs, batch jobs, a count of jobs that match the filter, and per-job event payloads.

Use cases:

• Monitoring active batch jobs.
• Watching jobs for a specific application user.
• Finding jobs in a specific subsystem.
• Sending job details as log events.

Sample configuration Copied

The following is a sample configuration for active batch jobs for one application.

collectors:
  - name: ibmiJobMetrics
    type: plugin
    className: IbmiCollector
    systemName: ibmi.example.com
    username: ibmiuser
    password: ${env:IBMI_PASSWORD}
    collectionInterval: 60000
    connectionTimeout: 20
    services:
      - name: IBMi/Job
        config:
          filters:
            status: "ACTIVE"
            type: "BATCH"
            name: "APP.*"
            nameUseRegex: true
            user: "APPUSER"
            subsystem: "QBATCH"
          enableCpuStatistics: true

Change these values:

• APP.* to the job name pattern you want.
• APPUSER to the IBM i user that owns the jobs.
• QBATCH to the subsystem to monitor.

Example output:

• totalJobs
• totalActiveJobs
• maxJobs
• totalBatchJobs
• jobsMatchingFilter
• jobData

Note

If no jobs match, temporarily set status, type, name, user, and subsystem to empty strings, and then add filters back one at a time.

Monitoring IBMi/Pool metrics Copied

Use IBMi/Pool to monitor IBM i storage pools.

This service collects pool count, pool size, reserved size, activity levels, page and fault counters, transition counters, system ASP values, and pool attributes.

Use cases:

• Storage pool dashboards.
• Memory and paging investigations.
• Detecting pressure through fault and page counters.
• Monitoring system ASP usage.

Sample configuration Copied

collectors:
  - name: ibmiPoolMetrics
    type: plugin
    className: IbmiCollector
    systemName: ibmi.example.com
    username: ibmiuser
    password: ${env:IBMI_PASSWORD}
    collectionInterval: 60000
    connectionTimeout: 20
    services:
      - name: IBMi/Pool

Example output:

• pools
• inactivePoolsSkipped
• totalAuxiliaryStorage
• systemASP
• percentageSystemASPUsed
• size
• databaseFaults
• nonDatabaseFaults
• pagingOption

Important

If system metrics work but pool rows are missing, verify that the IBM i user can read pool information and that the pools are active.

Monitoring IBMi/Subsystem metrics Copied

Use IBMi/Subsystem to monitor subsystem status and active job counts.

This service collects subsystem status, active jobs, maximum active jobs, pool count, subsystem name, and subsystem library.

Use cases:

• Alerting when a subsystem is inactive.
• Watching batch or application subsystems.
• Tracking active jobs per subsystem.
• Confirming subsystem state during operations.

Sample configuration Copied

The following is a sample configuration for monitoring active application subsystems.

collectors:
  - name: ibmiSubsystemMetrics
    type: plugin
    className: IbmiCollector
    systemName: ibmi.example.com
    username: ibmiuser
    password: ${env:IBMI_PASSWORD}
    collectionInterval: 60000
    connectionTimeout: 20
    services:
      - name: IBMi/Subsystem
        config:
          filters:
            library: "*ALL"
            name: "APP*"
            status:
              - ACTIVE
              - STARTING
              - ENDING

Change these values:

• APP* to your subsystem name or pattern.
• Keep library: "*ALL" during initial setup unless you know the exact subsystem library.

Example output:

• subsystemsMatchingFilter
• status
• activeJobs
• maxActiveJobs
• pools
• name
• library

Note

If no subsystems match, set name to "*ALL" and include all statuses, and then narrow the filter.

Monitoring IBMi/Queue metrics Copied

Use IBMi/Queue to monitor message queue depth.

This service discovers message queues and publishes the current number of messages in each matching queue. It does not publish the message text. Use IBMi/Message when you need the message content.

Use cases:

• Queue depth dashboards.
• Detecting growing message queues.
• Watching operator or application queues.

Sample configuration Copied

The following is a sample configuration for monitoring application message queues.

collectors:
  - name: ibmiQueueMetrics
    type: plugin
    className: IbmiCollector
    systemName: ibmi.example.com
    username: ibmiuser
    password: ${env:IBMI_PASSWORD}
    collectionInterval: 60000
    connectionTimeout: 20
    services:
      - name: IBMi/Queue
        config:
          filters:
            - library: "QUSRSYS"
              name: "APP*"
            - library: "MYLIB"
              name: "ERROR*"

Change these values:

• QUSRSYS, MYLIB to the libraries that contain your queues.
• APP*, ERROR* to the message queue names or patterns.

Example output:

• queuesMatchingFilter
• messageCount

Note

If no queues match, start with library: "*ALL" and name: "*ALL", and then narrow the filter after queues appear.

Monitoring IBMi/Message events Copied

Use IBMi/Message to read messages from specific IBM i message queues and publish matching messages as log events. This service returns message content. If you only need queue depth, use IBMi/Queue.

Use cases:

• Reading QSYSOPR messages.
• Publishing severe operator messages as events.
• Capturing messages from application jobs or users.
• Avoiding backlog replay while still tailing new messages.

Sample configuration Copied

The following is a sample configuration for monitoring severe QSYSOPR messages.

collectors:
  - name: ibmiMessageEvents
    type: plugin
    className: IbmiCollector
    systemName: ibmi.example.com
    username: ibmiuser
    password: ${env:IBMI_PASSWORD}
    collectionInterval: 60000
    connectionTimeout: 20
    services:
      - name: IBMi/Message
        config:
          queues:
            - queuePath: "/QSYS.LIB/QSYSOPR.MSGQ"
              filter:
                severity: 40
                senderJobName: ""
                senderJobUser: ""
              readFromBeginning: false

Change these values:

• queuePath to the message queue you want to read.
• severity: 40 to the minimum message severity you care about.
• senderJobName and senderJobUser if you only want messages from specific senders.

Example output:

• messagesEmitted
• messagesMatchingFilter
• messageData

Note

For this setup, keep readFromBeginning: false so that older queue messages are not replayed on the first run.

Monitoring IBMi/MemberRecord metrics Copied

Use IBMi/MemberRecord to monitor record usage inside IBM i database file members.

This service collects current records, record capacity, and percent usage per member.

Use cases:

• Monitoring whether file members are close to record capacity.
• Watching growth of important physical file members.
• Capacity dashboards for application files.

Sample configuration Copied

The following is a sample configuration for monitoring all members in a file.

collectors:
  - name: ibmiMemberRecordMetrics
    type: plugin
    className: IbmiCollector
    systemName: ibmi.example.com
    username: ibmiuser
    password: ${env:IBMI_PASSWORD}
    collectionInterval: 60000
    connectionTimeout: 20
    services:
      - name: IBMi/MemberRecord
        config:
          filePaths:
            - "/QSYS.LIB/MYLIB.LIB/ORDERS.FILE"

Change these values:

• MYLIB to the library that contains the file.
• ORDERS to the file you want to monitor.

Example paths for initial setups:

/QSYS.LIB/MYLIB.LIB/ORDERS.FILE
/QSYS.LIB/MYLIB.LIB/ORDERS.FILE/ORDERS2026.MBR

Example output:

• currentRecords
• recordCapacity
• percentUsage

Note

If no rows appear, verify that the file path is correct and that the IBM i user has authority to read the file and member details.

Monitoring IBMi/FileMember metrics Copied

Use IBMi/FileMember to monitor how many members are currently in a database file.

This service collects current member count, member capacity, and percent usage at the file level.

Use cases:

• Monitoring file member capacity.
• Alerting when a file is close to its member limit.
• Checking application files that create members over time.

Sample configuration Copied

collectors:
  - name: ibmiFileMemberMetrics
    type: plugin
    className: IbmiCollector
    systemName: ibmi.example.com
    username: ibmiuser
    password: ${env:IBMI_PASSWORD}
    collectionInterval: 60000
    connectionTimeout: 20
    services:
      - name: IBMi/FileMember
        config:
          filePaths:
            - "/QSYS.LIB/MYLIB.LIB/ORDERS.FILE"
            - "/QSYS.LIB/MYLIB.LIB/CUSTOMER.FILE"

Change these values:

• MYLIB to your library.
• ORDERS and CUSTOMER to your file names.

Use only file-level paths:

/QSYS.LIB/<LIBRARY>.LIB/<FILE>.FILE

Example output:

• currentMembers
• memberCapacity
• percentUsage

Note

If the path includes a member name such as .MBR, use IBMi/MemberRecord instead.

Monitoring IBMi/LogReader events Copied

Use IBMi/LogReader to tail IFS log files and publish each new line as a log event.

This service reads IFS files, supports wildcard file names, stores file positions, and can follow newly rotated files.

Use cases:

• Tailing web server logs.
• Tailing application logs.
• Following rotated log files.
• Publishing raw log lines as events.

Sample configuration Copied

The following is a sample configuration for reading application logs.

collectors:
  - name: ibmiLogReaderEvents
    type: plugin
    className: IbmiCollector
    systemName: ibmi.example.com
    username: ibmiuser
    password: ${env:IBMI_PASSWORD}
    collectionInterval: 60000
    connectionTimeout: 20
    services:
      - name: IBMi/LogReader
        config:
          files:
            - filename: "/QOpenSys/var/log/app_*.log"
              rewind: false
          workerPoolSize: 10
          filePositionEnabled: true
          filePositionMaxInactiveDays: 7

Change these values:

• filename to the IFS log path you want to monitor.
• Use * or ? only when you need wildcard matching.

Example output:

• totalStreams
• status
• totalMessagesReceived
• logData

Note

For this setup, keep rewind: false so that older log content is not replayed on the first run.

Small setup bundles Copied

Use these configurations when you want a slightly broader setup after you test individual services.

Basic health setup Copied

collectors:
  - name: ibmiBasicHealthSetup
    type: plugin
    className: IbmiCollector
    systemName: ibmi.example.com
    username: ibmiuser
    password: ${env:IBMI_PASSWORD}
    collectionInterval: 60000
    connectionTimeout: 20
    services:
      - name: IBMi/System
      - name: IBMi/Pool

Operations setup Copied

collectors:
  - name: ibmiOperationsSetup
    type: plugin
    className: IbmiCollector
    systemName: ibmi.example.com
    username: ibmiuser
    password: ${env:IBMI_PASSWORD}
    collectionInterval: 60000
    connectionTimeout: 20
    services:
      - name: IBMi/System
      - name: IBMi/Subsystem
        config:
          filters:
            library: "*ALL"
            name: "*ALL"
            status:
              - ACTIVE
              - STARTING
              - ENDING
              - INACTIVE
              - RESTRICTED
      - name: IBMi/Queue
        config:
          filters:
            - library: "QSYS"
              name: "QSYSOPR"
      - name: IBMi/Message
        config:
          queues:
            - queuePath: "/QSYS.LIB/QSYSOPR.MSGQ"
              filter:
                severity: 40
                senderJobName: ""
                senderJobUser: ""
              readFromBeginning: false

Application setup Copied

collectors:
  - name: ibmiApplicationSetup
    type: plugin
    className: IbmiCollector
    systemName: ibmi.example.com
    username: ibmiuser
    password: ${env:IBMI_PASSWORD}
    collectionInterval: 60000
    connectionTimeout: 20
    services:
      - name: IBMi/System
      - name: IBMi/Job
        config:
          filters:
            status: "ACTIVE"
            type: "BATCH"
            name: "APP.*"
            nameUseRegex: true
            user: "APPUSER"
            subsystem: "QBATCH"
          enableCpuStatistics: true
      - name: IBMi/Message
        config:
          queues:
            - queuePath: "/QSYS.LIB/QSYSOPR.MSGQ"
              filter:
                severity: 30
                senderJobName: "APP.*"
                senderJobUser: "APPUSER"
              readFromBeginning: false
      - name: IBMi/LogReader
        config:
          files:
            - filename: "/QOpenSys/var/log/app_*.log"
              rewind: false
          workerPoolSize: 10
          filePositionEnabled: true
          filePositionMaxInactiveDays: 7

Next steps Copied

After you validate connectivity and basic monitoring:

• Add additional IBM i services as needed.
• Tune filters to reduce unnecessary data collection.
• Configure rules and alerts in Geneos.
• Secure credentials using environment variables or a secret manager.
• Refer to the IBM i user guide for full configuration details.