Radiator Server Documentation — v10.34.2

stats

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 and returns a stats object.

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

A field returns nil when the operating system cannot report it.

Process Statistics

FieldTypeDescription
process_rss_bytesint?Process resident set size (memory) in bytes
process_cpu_millisint?Process CPU time in milliseconds (user + sys)

System Memory

FieldTypeDescription
system_mem_total_bytesint?Total system memory in bytes
system_mem_available_bytesint?Memory in bytes that new allocations can get without swapping (see below)
system_swap_total_bytesint?Total swap space in bytes
system_swap_used_bytesint?Used swap space in bytes
swap_pages_inint?Pages swapped in (cumulative)
swap_pages_outint?Pages swapped out (cumulative)

system_mem_available_bytes includes page cache and other memory that the kernel can reclaim. On Linux, the value is MemAvailable from /proc/meminfo. Kernels that do not report MemAvailable report unused memory instead.

System CPU

FieldTypeDescription
system_cpu_countint?Number of CPUs
system_cpu_active_millisint?System-wide active CPU time in milliseconds
system_cpu_total_millisint?System-wide total CPU time in milliseconds

Load Averages

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

FieldTypeDescription
load_1m_x100int?1-minute load average × 100
load_5m_x100int?5-minute load average × 100
load_15m_x100int?15-minute load average × 100

Network Queues

These values help detect overload.

FieldTypeDescription
udp_receive_dropsint?Datagrams dropped because Radiator's UDP socket receive buffers were full
tcp_listen_overflowsint?TCP listen queue overflows on the host (system-wide, cumulative)
tcp_listen_dropsint?Connection attempts dropped by TCP listeners on the host (system-wide, cumulative)

Example

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

-- 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