stats Context Variables

The stats namespace provides read-only access to process and system statistics including memory usage, CPU time, and load averages. These can be used in configuration expressions, logging, and attribute assignments.

Process Statistics

stats.process_rss_bytes

Process resident set size (memory) in bytes.

Type: Integer (unsigned)

Example:

logging {
    application {
        format "%{stats.process_rss_bytes}";
    }
}

stats.process_cpu_millis

Total CPU time used by the process in milliseconds (user + system).

Type: Integer (unsigned)

System Memory

stats.system_mem_total_bytes

Total system memory in bytes.

Type: Integer (unsigned)

stats.system_mem_available_bytes

Available system memory in bytes. Only available on Linux.

Type: Integer (unsigned)

stats.system_swap_total_bytes

Total swap space in bytes. Only available on Linux.

Type: Integer (unsigned)

stats.system_swap_used_bytes

Used swap space in bytes. Only available on Linux.

Type: Integer (unsigned)

stats.swap_pages_in

Cumulative count of pages swapped in from disk. Only available on Linux.

Type: Integer (unsigned)

stats.swap_pages_out

Cumulative count of pages swapped out to disk. Only available on Linux.

Type: Integer (unsigned)

System CPU

stats.system_cpu_count

Number of CPUs available.

Type: Integer (unsigned)

stats.system_cpu_active_millis

System-wide active (non-idle) CPU time in milliseconds. Only available on Linux.

Type: Integer (unsigned)

stats.system_cpu_total_millis

System-wide total CPU time in milliseconds. Only available on Linux.

Type: Integer (unsigned)

Calculating CPU utilization: To calculate CPU utilization percentage, compare stats.system_cpu_active_millis to stats.system_cpu_total_millis:

CPU % = (stats.system_cpu_active_millis / stats.system_cpu_total_millis) * 100

For interval-based measurements, take two snapshots and compute the delta:

CPU % = ((active2 - active1) / (total2 - total1)) * 100

Load Averages

Load averages are multiplied by 100 to preserve precision as integers. Divide by 100 to get the actual load average value.

stats.load_1m_x100

1-minute load average multiplied by 100.

Type: Integer (unsigned)

stats.load_5m_x100

5-minute load average multiplied by 100.

Type: Integer (unsigned)

stats.load_15m_x100

15-minute load average multiplied by 100.

Type: Integer (unsigned)

Platform Support

Variables that are not available on the current platform return an empty value.

Example Usage

Logging Memory Usage

aaa {
    policy "DEFAULT" {
        handler "AUTH" {
            authentication {
                script {
                    lua "LOG_STATS" {
                        # Log memory usage in MB
                        local rss = context.stats.process_rss_bytes
                        if rss then
                            print(string.format("Memory: %.2f MB", rss / 1024 / 1024))
                        end
                        return true
                    }
                }
            }
        }
    }
}