Skip to main content

PERFORM Library

Overview​

The PERFORM Library provides a lightweight and consistent way to monitor CPU usage, wall-clock execution time, and Lua memory utilization inside IguanaX components.

It's built for developers who want precise visibility into component performance without using external profilers.

Key Features​

  • CPU Tracking — Measure CPU effort .

  • Memory Profiling — Capture current heap usage and memory growth (Δ+).

  • Flexible Reporting — Output metrics to trace, Iguana Info Log, or directly onto the component card.

  • Self-contained — No external dependencies or global variables.

  • Baseline Snapshot — Get a one-line performance summary for the entire component.

Usage Overview​

local PER = require "PERFORM.PERmetrics"   
   
-- 1. Initialize Baseline (reset timer + set options)   
PER.PERset{ gc = "none", cores = 4 }   
   
-- 2. Start and stop named performance sections   
PER.PERbegin("db.query")   
-- run your operation   
PER.PERend("db.query")   
   
-- 3. Generate a report   
local report = PER.PERreport()        -- return as string   
PER.PERreport("log")                  -- log to Iguana Info Log   
PER.PERreport("status")               -- post to component card

Functions​

Function

Description

PERset({gc, cores})

Configures garbage collection mode (none, collect, or step) and CPU core count. Also resets the baseline window for "Baseline" metrics.

  • "none" (default): No GC before sampling — shows real-time heap usage including temporary objects.

  • "collect": Runs a full GC cycle — provides clean, stable memory readings of retained objects.

  • "step": Runs a small incremental GC step — lighter than full GC, reduces buildup while maintaining smoother readings.

PERbegin(name)

Starts measuring a named section. Captures CPU, wall time, and memory baseline.

PERend(name)

Stops measurement for a section, accumulating deltas into the report. If the section name is reused, metrics aggregate.

PERreport(reportType)

Returns a formatted report string. Optional reportType values: "log" (Iguana Info Log), "status" (component card), "json" (returns JSON string), or undefined (return only).

Report Example​

cpu.busy~300ms           exeTime:   0s  cpu~:  7.5%  mem:0.26MB (mem Δ+ 0.09MB)   
mixed.small              exeTime:   0s  cpu~:  2.0%  mem:0.24MB (mem Δ+ 0.00MB)   
mem.grow~1.5MB           exeTime:   0s  cpu~:  0.2%  mem:0.35MB (mem Δ+ 0.09MB)   
sleep~1200ms             exeTime:   1s  cpu~:  0.1%  mem:0.35MB (mem Δ+ 0.00MB)

Field meanings:

Field

Description

exeTime

Wall-clock duration (seconds) for this section.

cpu

CPU utilization percent (normalized across configured cores).

mem

Current Lua heap memory at the end of the section.

mem Δ+

Net positive memory growth (ignores temporary decreases).

Output Modes​

Report Type

Behavior

(undefined)

Returns the report string to the caller.

"log"

Sends the report to Iguana Info Log via iguana.logInfo().

"status"

Converts report to HTML (&nbsp;, <br />) and sends to component card via component.setStatus{data=...}.

"json"

Returns the report string as a JSON-formatted string to the caller.

Best Practices​

  • Call PERset() at the beginning of main(Data) to reset the baseline.

  • Wrap meaningful code blocks with PERbegin / PERend.

  • Keep section names short and descriptive (e.g., api.call, file.load).

  • Use "status" mode to show live metrics on the component card in production.

  • Avoid using os.time() for sub-second accuracy; metrics intentionally stay coarse for performance.

File

Purpose

PERFORM/PERmetrics.lua

Core performance tracking logic

PERFORM/PERUtils.lua

Shared helper functions (memory, formatting, CPU%)