SysPerf: IRIS Operations Portal (SystemPerformance, PERFMON, live operations)

SysPerf is a set of classes only (no external libraries, no CDN). It has three parts, all reached from one portal with a management-portal style sidebar (SysPerf.UI.Portal.cls):

• SystemPerformance analytics. It loads every ^SystemPerformance / ^pButtons HTML report into persistent classes and runs an analyzer that raises bottlenecks with recommendations. You get day / week / month / custom trends and can drill into every section of every report.
  

• PERFMON analytics. It runs PERFMON timed collections from the portal or from Task Manager, and loads existing PERFMON HTML reports. Every table goes into persistent classes, and an analyzer names the globals, routines, processes and databases that drive the load.

• Live operations for the local instance: a system dashboard, processes, locks, databases, journals, mirror, Task Manager, system logs and license. There are also interoperability views: productions and their items, queues and the event log across every interoperability namespace. All of these views are read-only.

Tested on InterSystems IRIS for Health 2026.1 (Build 235U), the same build as your UAT server. It was tested with your Windows report and with a Linux report generated on the same build. The classes use standard %CSP, %SQL, %DynamicObject and %SYS.Task APIs (IRIS 2021.1+).

1. Install (about 5 minutes)

Run the install from a terminal as a user with %All, or with %Admin_Manage plus %Admin_Secure.

// 1) (optional, recommended) dedicated namespace + database on a data drive
zn "%SYS"
// import once anywhere to get the installer, or create the namespace in the Portal
do $system.OBJ.Load("D:\install\SysPerf.xml","ck")        // e.g. into USER
do ##class(SysPerf.Installer).CreateNamespace("SYSPERF","D:\IRISDB\sysperf\")
// 2) load + compile into the target namespace
zn "SYSPERF"
do $system.OBJ.Load("D:\install\SysPerf.xml","ck")
// 3) security, web application, task, folders, thresholds
do ##class(SysPerf.Installer).Setup("/csp/sysperf","D:\SysPerf\Inbox",6)
//            web app path ----^      inbox folder ----^           ^-- daily task hour (-1 = none)

Setup() is idempotent, so you can re-run it after an upgrade. It creates:

• Resources: SysPerf_Viewer and SysPerf_Admin.
• Roles you assign to users:
  • SysPerfViewer: read-only access to every screen.
  • SysPerfAdmin: upload, acknowledge findings, notes, settings, delete runs and collections, start PERFMON collections.
• Roles the web application adds automatically (MatchRoles). Users never hold them outside the portal:
  • SysPerfPortal is added to every portal user. It grants %DB_IRISSYS:R and %Admin_Operate:U, Read on the globals database of every namespace (for the application error log) and on the routine database of every interoperability namespace, plus SQL SELECT/EXECUTE on the system tables used. The live views need this.
  • SysPerfCollector is added only to SysPerfAdmin users. It grants %DB_IRISSYS:RW, which PERFMON requires in order to run.
• Database access: both roles include RW on the namespace’s database resource and the matching SQL grants (SELECT for viewers, full DML for admins).
• Web application: /csp/sysperf, password authentication, requires SysPerf_Viewer.
• Tasks:
  • SysPerf load reports (SYSPERF), daily at 06:00.
  • SysPerf PERFMON collection (SYSPERF), weekdays at 10:00 for 300 s. This task is created suspended; resume it in Task Manager to collect regularly.
  • Both tasks run as _SYSTEM. Change the user in Task Manager if your policy requires it; the PERFMON task user needs %DB_IRISSYS:RW.
• Folders: Inbox / Archive / Error, and the analyzer threshold table.

Assign the roles to users in System Administration > Security > Users.

Open https://<server>:<port>/csp/sysperf/SysPerf.UI.Portal.cls. This is the portal home, and every screen is reachable from its sidebar.

New namespace later? Run do ##class(SysPerf.Installer).SetupPortalRole() so the portal can read its application errors and, for interoperability namespaces, its productions.

Web gateway upload limit. 24-hour reports are 50–150 MB. If uploads fail with HTTP 413 or the connection resets, raise the request size limit of your web server (IIS maxAllowedContentLength, Apache LimitRequestBody), or use the inbox folder instead.

3. Feeding reports

Duplicates are detected automatically: by SHA-256 of the file, and by Host:Instance:RunId.

| Inbox folder + task | Copy reports into the inbox (e.g. a scheduled copy of each server’s mgr\*.html). The daily task loads them, moves them to Archive or Error, and purges runs older than the retention period. The task fails visibly in Task Manager if a file could not be loaded. IncludeMgrDirectory=1 on the task also picks up this instance’s own daily reports from mgr. |
| Terminal / your own code | do ##class(SysPerf.Loader).LoadFile("D:\perf\x.html",.runId)
do ##class(SysPerf.Loader).LoadDirectory("D:\perf\",1,.summary) write summary |

Collect a report every day: set CPF [Startup] SystemPerformanceDailyReportsOn=1, or schedule do run^SystemPerformance("24hours") in Task Manager on each server. Then point the inbox at the output.

Windows perfmon: your sample’s perfmon section failed with “Access is denied” (logman). Run the profile as a local administrator, or add the IRIS service account to Performance Log Users and restart IRIS. Without perfmon there is no CPU, memory or disk time-series; the analyzer flags this.

4. What is stored (every section → persistent classes)

Configuration: SysPerf.Config.Settings (folders, retention, upload size) and SysPerf.Config.Threshold (rules). Audit: SysPerf_Data.LoadLog. CSV export of any table: SysPerf.UI.Export.cls?id=<run>&t=<Table>.

5. Screens

• Dashboard:

  • System selector and Day / Week / Month / Month-to-date / 90 days / Year / Custom periods, anchored to the latest data.
  • Hourly or daily granularity.
  • KPIs with change vs the previous period.
  • CPU, global refs/updates, physical reads/writes, cache hit, worst disk latency, memory, journal/WIJ, write daemon queue, routine loads and IRIS processes.
  • “Explore any metric”, including per-device disk metrics.
  • A day-of-week × hour heatmap to see when the system is busiest.
  • Health score per run, recurring findings, database growth, the run list and a CSV of hourly data.
    
    
    
    
    

• Runs: filter, compare two runs, re-analyse, delete (admin).

• Run detail: 15 tabs.

  • Findings: severity filter, evidence, recommendations, acknowledge.
  • System summary and notes.
  • mgstat: a chart for every counter with min/max band, a stats table for all counters, full data.
  • OS: CPU, run queue, memory, paging, network, disk, per source.
  • Disks: per-device averages and charts.
  • Processes: busiest processes, activity table, every %SS snapshot.
  • IRIS jobs: physical reads by job, job states.
  • Contention: resource seizes over time, contention %.
  • Databases.
  • Configuration: key parameters and full CPF.
  • All details: every KeyValue.
  • OS processes, routine buffers.
  • Raw OS counters: chart any perfmon/vmstat/iostat/sar column.
  • Report text.

• Compare: key metrics side by side with Δ%, an overlay on elapsed minutes, findings new/resolved/changed, CPF differences.

• Load SystemPerformance Files (upload, inbox scan, load log). Admin (settings, editable thresholds, maintenance, storage).

6. Analyzer rules

All thresholds can be edited on the Admin page; re-analyse to apply them to existing runs. Each finding lists evidence, the peak time, the periods above the threshold (e.g. 09-22 13:00-15:59 (180 min, peak 35.9 at 14:50)) and a concrete recommendation.

Health score = 100 − 15 × critical − 5 × warning.

6a. The portal

Application Error Log. This shows the same data as System Operation > System Logs > Application Error Log in the Management Portal, for all namespaces on one screen. You can filter by period (today / 7 / 30 days / all) and namespace, and there are errors-per-day and most-frequent-error charts. Select an error number to see the full detail: process state and variables, objects, devices and stack. It is read-only; errors are purged as usual in the Management Portal.

Two load pages, one inbox. Each load page accepts only its own report type. A PERFMON file uploaded on the SystemPerformance page is rejected with a pointer to the right page, and the reverse also applies. The inbox folder and the daily task stay shared, and each file is recognised from its contents.

Every table can be filtered, sorted and downloaded as CSV. The top bar shows status chips (uptime, license, journal, alerts, mirror), and there is a light / dark theme. On phones the sidebar collapses into a menu.

6b. PERFMON

Ways to get data in

What is stored (SysPerf_PM.*)

Analyzer rules (thresholds are editable on the Admin page)

Screens

• Collections: list, delete and re-analyse.
• Trends across collections: refs/s, physical reads/s, journal/s, lines/s, health, and the hottest globals over time by references, physical reads, updates or journal.
• Collection detail, with tabs for findings, globals, globals by routine, routines, processes, databases, process list, other tables, notes and the original report (in a sandboxed frame). There are top-12 charts on every tab, and previous / next collection navigation.
• CSV of any PERFMON table: SysPerf.UI.Export.cls?id=<collection>&t=PM.GlobalStat (also PM.RoutineGlobal, PM.RoutineStat, PM.ProcessStat, PM.Process, PM.Finding).

7. Security

• All pages require SysPerf_Viewer (via SECURITYRESOURCE). Admin actions check SysPerf_Admin on the server.
• CSRF token on every POST.
• Output is HTML-escaped on the server. The browser only inserts data with textContent.
• JSON endpoints are read-only, use parameterised SQL, and whitelist tables and columns.
• Uploads accept .html/.htm only. File names are sanitised and size is capped.
• The report parser never executes report content; the $lb() debug snapshot is parsed with a safe tokenizer.
• CSV export neutralises spreadsheet formulas.
• Security headers are set: X-Frame-Options, nosniff, no-store. The original PERFMON report is served with Content-Security-Policy: sandbox inside a sandboxed iframe, so its content cannot run scripts.
• Live and interoperability views are read-only. They only use documented system classes and queries, and there is no kill / suspend / purge button. The extra privileges (SysPerfPortal, SysPerfCollector) exist only inside the portal’s web application.
• Starting a PERFMON collection is checked on the server (SysPerf_Admin plus CSRF) and validated (10–3600 s, one at a time).

8. Operations

• Re-analyse after changing thresholds: Admin page, or do ##class(SysPerf.Loader).Reanalyze().
• Retention: Settings.RetentionDays (default 400). The task purges older runs, and marks stale loads (> 1 day) as failed.
• Size: a 24-hour report at 10 s intervals with perfmon adds about 150k rows and loads in about 7 s. A 2 s interval takes about 35 s in a background job.
• Unit tests: do ##class(SysPerf.Test.Core).Run("D:\sysperf\samples\"). The folder must contain win_sample.html / linux_sample.html, and optionally perfmon_sample.html for the PERFMON tests.
• PERFMON overhead: a collection adds a small overhead while it runs, so prefer 1–5 minute collections at the busy hour. The files are about 0.5–2 MB.
• Uninstall: do ##class(SysPerf.Installer).Uninstall("/csp/sysperf") removes the web app, both tasks and the four roles, and keeps the data. Delete the namespace to remove everything.
• Licensing note: each browser session uses a license unit like any CSP application.