Getting Started

RPG Metrics analyses RPG source locally without requiring you to upload source code to the RPG Metrics web application.

One Agent, two deployment options. Run RPG Metrics directly on IBM i/PASE, or on a Windows, Linux or macOS computer/server using exported RPG source files. In either mode, source remains in your environment.

IBM i / PASE

Run the Agent directly on IBM i and watch an IFS folder for RPG source stream files.

  • RPG source is scanned locally on IBM i
  • XLSX reports are generated locally on IBM i
  • Source can be submitted using PDM, change control or scripts
  • Dashboard sync is optional
  • IBM i completion messages can optionally be enabled
PC / Local-Folder Mode

The same Agent can run on Windows, Linux or macOS and watch a local folder containing RPG source files that have already been exported or copied from IBM i.

  • RPG source is scanned locally on the PC/server
  • XLSX reports are generated locally on the PC/server
  • Source remains inside your own environment
  • Dashboard sync is optional
  • The same RPG Metrics analysis engine is used
Important: PC mode does not connect to IBM i and extract source automatically. The RPG source files must already exist in the configured local scan folder.

Request the RPG Metrics Agent

The same RPG Metrics Agent supports IBM i/PASE and PC/local-folder operation. To request the current Agent package, use the Feedback option below.

Log in or create an account to request the RPG Metrics Agent.

Please let us know whether you intend to run the Agent on IBM i/PASE or on a Windows, Linux or macOS PC/server.

RPG Metrics requires Python 3.9 or later. Python 3.9 is the recommended version.

IBM i

A typical IBM i installation places the Agent in:

/home/metrics-agent

Create the source, report and log folders:

mkdir -p /home/devuser/metrics-sources
mkdir -p /home/devuser/metrics-sources/sent
mkdir -p /home/devuser/metrics-sources/unsent
mkdir -p /home/metrics-agent/reports
mkdir -p /home/metrics-agent/logs

Create the Python virtual environment:

cd /home/metrics-agent
/QOpenSys/pkgs/bin/python3.9 -m venv .venv
source .venv/bin/activate
python -m pip install --progress-bar off -r requirements.txt
Windows

A typical Windows installation can use:

C:\rpg-metrics-agent

Create the virtual environment and install the requirements:

cd C:\rpg-metrics-agent
py -3.9 -m venv .venv
.\.venv\Scripts\python -m pip install -r requirements.txt

Linux and macOS use the same PC/local-folder mode with the appropriate Python virtual-environment commands for the platform.

Create your local agent.conf from the supplied example.

IBM i
cd /home/metrics-agent
cp agent.conf.example agent.conf

Typical IBM i settings:

[agent]
PLATFORM_MODE=auto
DASHBOARD_SYNC=false
SCAN_PATH=
IBMI_IFS_PATH=/home/devuser/metrics-sources
REPORTS_PATH=/home/metrics-agent/reports
TEAM_NAME=Personal
POLL_INTERVAL=60
IBMI_MESSAGE_ENABLED=false
Windows / PC

Create the configuration file:

cd C:\rpg-metrics-agent
Copy-Item .\agent.conf.example .\agent.conf

Typical PC settings:

[agent]
PLATFORM_MODE=pc
DASHBOARD_SYNC=false
SCAN_PATH=C:/rpg-metrics-agent/sources
REPORTS_PATH=C:/rpg-metrics-agent/reports
TEAM_NAME=Personal
POLL_INTERVAL=60
IBMI_MESSAGE_ENABLED=false
SCAN_PATH is the platform-neutral source-folder setting. When it is set, it takes precedence over IBMI_IFS_PATH. IBMI_IFS_PATH remains available for existing IBM i installations.

Local-only mode

Set:

DASHBOARD_SYNC=false

The Agent will scan source and generate XLSX reports locally without connecting to the RPG Metrics dashboard.

No Agent token is required for local-only operation.

Dashboard sync

Set:

DASHBOARD_SYNC=true

When dashboard sync is enabled, only calculated metrics are sent to RPG Metrics. Source code is not transmitted.

Generate your Agent token from the RPG Metrics Profile page and add it to:

AUTH_REFRESH_TOKEN=<your token>

The Agent uses the refresh token to obtain short-lived access tokens. Your RPG Metrics password is not stored in the Agent.

IBM i

The Agent watches the configured IFS folder for RPG source stream files. A source member can be converted using CPYTOSTMF.

CPYTOSTMF
  FROMMBR('/qsys.lib/&l.lib/&f.file/&n.mbr')
  TOSTMF('/home/devuser/metrics-sources/&l_&f_&n.&t')
  STMFOPT(*REPLACE)
  CVTDTA(*AUTO)
  DBFCCSID(*FILE)
  STMFCCSID(*STDASCII)

This can be triggered manually, from PDM, from a script, or automatically from a change-control process.

PC / Local Folder

In PC mode, place RPG source files that have already been exported from IBM i into the folder configured by SCAN_PATH.

The Agent does not extract IBM i source directly when running in PC mode.

Filename format

Personal scans:

LIBRARY_SOURCEFILE_MEMBER.TYPE

Example:

KEV_QRPGLESRC_BFSALES.RPGLE

Team scans:

TEAM_LIBRARY_SOURCEFILE_MEMBER.TYPE

Example:

SETT5_KEV_QRPGLESRC_BFSALES.RPGLE

Supported source types include:

  • RPG
  • SQLRPG
  • RPGLE
  • SQLRPGLE
  • RPGFREE

Run manually on IBM i
cd /home/metrics-agent
source .venv/bin/activate
python agent.py
Run manually on Windows
cd C:\rpg-metrics-agent
.\.venv\Scripts\python agent.py

Or use:

.\run-agent.bat

Successfully processed source files are moved to sent/. Files that cannot be processed are moved to unsent/.

XLSX reports are written beneath the configured REPORTS_PATH and organised by team, library and source file.

Depending on your subscription, reports can include:

  • Summary metrics
  • Source-line analysis
  • Cyclomatic complexity hotspots
  • RPG Free compatibility findings
Your source stays local. In IBM i mode the source and reports remain on IBM i. In PC mode they remain on the local PC/server. Only calculated metrics are sent when dashboard sync is enabled.

RPG Metrics can be integrated into existing IBM i development and change-control workflows.

Any process capable of creating the source stream file after a development or promotion step can trigger an Agent scan automatically.

Typical workflow:

  1. Developer changes RPG source
  2. Source is promoted through change control
  3. A post-promotion command runs CPYTOSTMF
  4. The stream file appears in the Agent scan folder
  5. RPG Metrics automatically analyses the program
  6. The XLSX report is generated locally
  7. Calculated metrics are optionally added to dashboard history

This can be used with MDCMS or other change-control systems capable of executing a command as part of the promotion process.