scripts.context.stats

Stats Sub-context

The stats sub-context provides access to process-level and system-wide statistics including memory usage, CPU time, and load averages.

Methods

`get()`

Fetches the current process and system statistics. Returns a stats object or nil if statistics are not available on the current platform.

local stats = context.stats:get()

Call this method each time you need fresh statistics. The values are captured at the moment of the call.

Stats Object Fields

All fields return nil if not available on the current platform.

Process Statistics

Field	Type	Description
`process_rss_bytes`	int?	Process resident set size (memory) in bytes
`process_cpu_millis`	int?	Process CPU time in milliseconds (user + sys)

System Memory

Field	Type	Description
`system_mem_total_bytes`	int?	Total system memory in bytes
`system_mem_available_bytes`	int?	Available system memory in bytes
`system_swap_total_bytes`	int?	Total swap space in bytes
`system_swap_used_bytes`	int?	Used swap space in bytes
`swap_pages_in`	int?	Pages swapped in (cumulative)
`swap_pages_out`	int?	Pages swapped out (cumulative)

System CPU

Field	Type	Description
`system_cpu_count`	int?	Number of CPUs
`system_cpu_active_millis`	int?	System-wide active CPU time in milliseconds
`system_cpu_total_millis`	int?	System-wide total CPU time in milliseconds

Load Averages

Load averages are multiplied by 100 to preserve precision as integers.

Field	Type	Description
`load_1m_x100`	int?	1-minute load average × 100
`load_5m_x100`	int?	5-minute load average × 100
`load_15m_x100`	int?	15-minute load average × 100

Platform Support

Field	Linux	macOS
`process_rss_bytes`	✓	✓
`process_cpu_millis`	✓	✓
`system_mem_total_bytes`	✓	✓
`system_mem_available_bytes`	✓	-
`system_swap_total_bytes`	✓	-
`system_swap_used_bytes`	✓	-
`swap_pages_in`	✓	-
`swap_pages_out`	✓	-
`system_cpu_count`	✓	✓
`system_cpu_active_millis`	✓	-
`system_cpu_total_millis`	✓	-
`load_1m_x100`	✓	✓
`load_5m_x100`	✓	✓
`load_15m_x100`	✓	✓

Example

local context, previous = ...
local stats = context.stats:get()

if not stats then
    return previous
end

-- Log memory usage
local rss_mb = (stats.process_rss_bytes or 0) / 1024 / 1024
context:log("AUTHENTICATION", string.format("Process memory: %.2f MB", rss_mb))

-- Check load average (divide by 100 to get actual value)
local load_1m = (stats.load_1m_x100 or 0) / 100
if load_1m > (stats.system_cpu_count or 1) then
    context:log("AUTHENTICATION", "High load average")
end

-- Calculate system memory usage percentage
local total = stats.system_mem_total_bytes
local available = stats.system_mem_available_bytes
if total and available then
    local pct = (total - available) / total * 100
    context:log("AUTHENTICATION", string.format("System memory: %.1f%% used", pct))
end

-- Calculate CPU utilization over an interval
-- To measure CPU usage, take two snapshots and compute delta:
--   CPU % = (active2 - active1) / (total2 - total1) * 100
-- For instant snapshot (since boot):
local cpu_active = stats.system_cpu_active_millis
local cpu_total = stats.system_cpu_total_millis
if cpu_active and cpu_total and cpu_total > 0 then
    local cpu_pct = cpu_active / cpu_total * 100
    context:log("AUTHENTICATION", string.format("CPU utilization: %.1f%%", cpu_pct))
end

return previous

Parents