IBM i/AS400

·

The IBM i/AS400 collector uses IBM i Access ODBC Driver to query Db2 for i SQL Services remotely and collect system, ASP, job, memory pool, subsystem, job queue, and message queue metrics.

Already tested version:

• IBM i 7.4

Configuration¶

Prerequisites¶

Configure the ODBC environment¶

The collector currently runs only on Linux AMD64.

The IBM i/AS400 collector loads IBM i Access ODBC Driver through unixODBC. An existing unixODBC installation and configuration on the Linux collector host can be reused.

First, check the unixODBC installation and configuration file locations:

odbcinst -j

If odbcinst is unavailable, install unixODBC for the Linux distribution:

# Debian/Ubuntu
sudo apt-get update
sudo apt-get install -y unixodbc

# RHEL/Rocky Linux
sudo dnf install -y unixODBC

# SUSE Linux
sudo zypper install unixODBC

Download the ACS Application Package for the collector platform from IBM i Access Client Solutions, then install IBM i Access ODBC Driver according to the package instructions. Select the AMD64 package. The driver libraries must match the collector runtime architecture.

After installation, confirm that unixODBC can discover IBM i Access ODBC Driver:

odbcinst -q -d

The default driver name is IBM i Access ODBC Driver 64-bit. Check the driver with:

odbcinst -q -d -n "IBM i Access ODBC Driver 64-bit"

If the driver is not registered automatically, edit the odbcinst.ini file reported by odbcinst -j. Driver library paths can vary by package. The following is a common configuration:

[IBM i Access ODBC Driver 64-bit]
Description=IBM i Access for Linux 64-bit ODBC Driver
Driver=/opt/ibm/iaccess/lib64/libcwbodbc.so
Setup=/opt/ibm/iaccess/lib64/libcwbodbcs.so
Threading=0
DontDLClose=1
UsageCount=1

Verify that the driver and the collector's ODBC dependency can be loaded:

ldd /opt/ibm/iaccess/lib64/libcwbodbc.so
ldd /usr/local/datakit/externals/ibm_i

Collector Configuration¶

[[inputs.external]]
  daemon = true
  name   = "ibm_i"
  cmd    = "/usr/local/datakit/externals/ibm_i"

  ## Set true to enable election.
  election = true

  args = [
    "--interval", "60s",
    "--host", "<ibm-i-host>",
    "--username", "DKUSER",

    ## Optional: IBM i Access ODBC driver name registered in odbcinst.ini.
    # "--driver", "IBM i Access ODBC Driver 64-bit",

    ## Optional: use a raw ODBC connection string instead of host/username/password/driver.
    # "--dsn", "Driver={IBM i Access ODBC Driver 64-bit};System=<ibm-i-host>;UID=DKUSER;PWD=<password>;",

    ## Optional query and timeout settings.
    # "--query-timeout", "30s",
    # "--job-query-timeout", "240s",
    # "--system-mq-query-timeout", "80s",
    # "--severity-threshold", "50",

    ## Repeat these arguments as needed.
    ## When --query is omitted, all default queries are enabled.
    ## On large systems, start with base queries and enable job detail
    ## queries only when needed.
    # "--query", "disk_usage",
    # "--query", "cpu_usage",
    # "--query", "memory_info",
    # "--query", "subsystem",
    # "--query", "job_queue",

    ## Limit message_queue_info to selected queues to reduce target load.
    # "--message-queue", "QSYSOPR",
    # "--message-queue", "QSYSMSG",
  ]
  envs = [
    "ENV_INPUT_IBM_I_PASSWORD=<password>",
    "LD_LIBRARY_PATH=/opt/ibm/iaccess/lib64:$LD_LIBRARY_PATH",
  ]

  [inputs.external.tags]
    # some_tag = "some_value"
    # more_tag = "some_other_value"

A raw ODBC connection string can be supplied through --dsn. When --dsn is configured, --host, --username, --password, and --driver are not used to build the connection string:

args = [
  "--dsn", "DSN=IBMI;UID=DKUSER;PWD=<password>;",
]

To avoid exposing the password in the configuration or command line, pass it through an environment variable:

envs = [
  "ENV_INPUT_IBM_I_PASSWORD=<password>",
  "LD_LIBRARY_PATH=/opt/ibm/iaccess/lib64:$LD_LIBRARY_PATH",
]

Options¶

All default queries are enabled when --query is omitted. Job detail queries emit metrics per job and can create many time series on IBM i systems with a large number of jobs. In production, you can start with the base queries and enable job detail queries later as needed.

The message_queue_info query scans all message queues by default. On systems with many messages, use --message-queue to restrict collection to the queues you want to monitor, such as QSYSOPR and QSYSMSG.

The following values are supported by --query:

disk_usage
cpu_usage
jobq_job_status
active_job_status
job_memory_usage
memory_info
subsystem
job_queue
message_queue_info

Metric¶

ibm_i¶

collector¶

FAQ¶

How do I verify ODBC?¶

If you need to verify ODBC independently, add a test DSN to the odbc.ini file reported by odbcinst -j:

[IBMI]
Description=IBM i
Driver=IBM i Access ODBC Driver 64-bit
System=10.0.0.10

Then run these commands in order:

odbcinst -j
odbcinst -q -d
ldd /opt/ibm/iaccess/lib64/libcwbodbc.so
isql -v IBMI DKUSER '<password>'

Verify that the driver is registered, all dynamic library dependencies are available, and isql can connect to IBM i.

What should I check on IBM i?¶

TCP/IP and the Database Host Server must be running on IBM i. The collection user must be able to sign on to IBM i and query Db2 for i SQL Services.

Why are no metrics reported?¶

Check the following:

• unixODBC and IBM i Access ODBC Driver can be loaded on the DataKit host.
• odbcinst -q -d lists the configured driver name.
• isql can connect to IBM i with the collection user.
• The IBM i Database Host Server is running and reachable through the network and firewall.
• The collection user can access the Db2 for i SQL Services listed in this document.
• [DataKit installation directory]/externals/ibm_i.log does not contain connection or query errors.