runtime
Facts about the running program: the system, the memory, the uptime and the build options.
import runtime
The runtime package answers questions about the running program and the machine under it: which system and processor, how many cores, how much memory, how long the program has been up and how it was compiled. It is what a /health route, a startup log line or a benchmark guard needs.
It gathers facts from os.platform and adds the uptime and the build flags. For details such as the host name or the kernel version, use os.platform directly; for the program's own allocation counts, mem; for timing a piece of code, time or the timers in debug.
Where the numbers come from:
| System | CpuCount | TotalMemory | AvailableMemory, UsedMemory |
|---|---|---|---|
| Linux | a system call | reads /proc/meminfo | reads /proc/meminfo |
| Windows | the NUMBER_OF_PROCESSORS variable | runs PowerShell | runs PowerShell |
| macOS, BSD | runs sysctl | runs sysctl | minus one |
The things people get wrong:
- The memory functions are not free everywhere. On Linux they read a small file, but on Windows each call starts PowerShell and takes a good part of a second. Cache the numbers, or refresh them on a timer, instead of reading them on every request.
- Every number can be minus one when the system does not report it. Check before you do arithmetic.
- The memory figures are for the whole machine, not this program. In a container you see the host's memory, not the container's limit.
- The uptime counts from
MarkStart. Without it the clock starts at the firstUptimeMscall, so the first health check reports 0. It uses the wall clock, so changing the system time moves it.
A /health route
A load balancer, Docker's HEALTHCHECK or a monitoring service calls a health route every few seconds to see whether the program is alive. Call MarkStart first thing in main, so the uptime counts from the start of the program and not from the first request, and answer with a small JSON object built from the runtime facts.
import runtime
import net.http
import net.router
import conv
import str
func health(ctx: i64):
mut body := `{"status": "ok", "os": "` + runtime.OS() + `", "arch": "` + runtime.Arch() + `"`
body = body + `, "cpus": ` + conv.FormatInt(runtime.CpuCount() as i64)
body = body + `, "uptime_ms": ` + conv.FormatInt(runtime.UptimeMs())
body = body + `, "used_memory": ` + conv.FormatInt(runtime.UsedMemory())
body = body + `, "build": "` + runtime.BuildFlags() + `"}`
http.Json(ctx, body)
end
func main:
runtime.MarkStart()
mut r := router.NewRouter()
router.Get(r, "/health", health)
mut s := http.NewServer(19734)
http.Use(s, r)
println http.RunBackground(s)
res := http.Get("http://127.0.0.1:19734/health")
body := http.Body(res)
println http.Status(res), http.GetHeader(res, "content-type")
println str.StartsWith(body, `{"status": "ok"`), str.Contains(body, `"uptime_ms": `)
endThe example starts the server in the background with net.http and calls its own route, so it runs without anything else. The numbers in the body change on every run, so it prints only the status, the content type and two checks. A real body looks like {"status": "ok", "os": "linux", "arch": "x64", "cpus": 8, "uptime_ms": 5412, "used_memory": 6442450944, "build": "release"}.
Report memory in a readable way
TotalMemory and AvailableMemory return bytes, and minus one where the system does not report them. UsedMemory is the difference, or minus one when either is missing. Turn the bytes into MiB for people, and handle the minus one before doing any arithmetic, or a percentage of a negative number ends up on a dashboard.
import runtime
import conv
func mib(bytes: i64): str:
if bytes < 0: ret "unknown" end
ret conv.FormatInt(bytes / (1024 * 1024)) + " MiB"
end
func memory_line(total: i64, available: i64): str:
if total < 0 or available < 0:
ret "memory: not reported on this system"
end
percent := (total - available) * 100 / total
ret "memory: " + mib(total - available) + " of " + mib(total) + " in use (" + conv.FormatInt(percent) + "%)"
end
func main:
println memory_line(8589934592, 2147483648)
println memory_line(17179869184, 15032385536)
println memory_line(0 - 1, 0 - 1)
line := memory_line(runtime.TotalMemory(), runtime.AvailableMemory())
println line.Len() > 0
used := runtime.UsedMemory()
println used <= runtime.TotalMemory()
endThe first three lines use fixed numbers so the output is the same everywhere; the last two call the real functions.
Size a worker pool from the core count
A server or a batch job often starts one worker per core. CpuCount gives the cores that are online, but a sensible rule also lets the operator override it, puts a ceiling on very large machines and falls back to a small number when the count is unknown. Summary puts the main facts in one line, which is handy to log once at startup.
import runtime
import str
func pick_workers(cpus: int, configured: int): int:
if configured > 0: ret configured end
if cpus < 1: ret 2 end
if cpus > 16: ret 16 end
ret cpus
end
func main:
println "8 cores, nothing configured:", pick_workers(8, 0)
println "64 cores, nothing configured:", pick_workers(64, 0)
println "core count unknown:", pick_workers(0 - 1, 0)
println "configured by hand:", pick_workers(8, 3)
workers := pick_workers(runtime.CpuCount(), 0)
println "here:", workers >= 1 and workers <= 16
line := runtime.Summary()
println str.Contains(line, " cpus="), str.Contains(line, " build=")
endA real Summary line looks like linux/x64 cpus=8 uptime_ms=3 build=release.
Know how the program was built
BuildFlags returns release for a --release build, or the checks that are compiled in, joined with commas: safe for the default development build with bounds checks, mem_debug and asan for the memory checking builds. IsSafeBuild, IsMemDebugBuild and IsAsanBuild test each one. These are fixed when the program is compiled, so checking them costs nothing.
import runtime
func check_benchmark_build(): bool:
flags := runtime.BuildFlags()
if flags == "release":
ret true
end
println "warning: this is a", flags, "build, so the timings would be too slow"
if runtime.IsSafeBuild():
println " bounds checks are on; build with --release"
end
if runtime.IsAsanBuild() or runtime.IsMemDebugBuild():
println " memory checking is on; build without --asan or -DSALAM_MEM_DEBUG"
end
ret false
end
func main:
if check_benchmark_build() == false:
println "skipping the benchmark"
ret
end
println "running the benchmark"
endsalam run makes a development build, which is why this example warns. Build it with salam build file.salam --release and the same program runs the benchmark. The same check is useful at startup of a server, to log a warning when a debug build reaches production by mistake.
Functions
OS
func OS(): strlinux, windows, mac, freebsd, wasm or unknown.import runtime
func main:
runtime.MarkStart()
println runtime.OS().Len() > 0, runtime.Arch().Len() > 0, runtime.CpuCount() >= 1
free := runtime.AvailableMemory()
used := runtime.UsedMemory()
println runtime.TotalMemory() > 0, free > 0 or free == -1, used >= 0 or used == -1
println runtime.UptimeMs() >= 0, runtime.UptimeSeconds() >= 0.0
println runtime.IsAsanBuild(), runtime.IsMemDebugBuild()
println runtime.IsSafeBuild() or not runtime.IsSafeBuild()
println runtime.BuildFlags().Len() >= 0, runtime.Summary().Len() > 0
endArch
func Arch(): strThe example for this item is shown with the ones above: runtime-Summary.salam
CpuCount
func CpuCount(): intThe example for this item is shown with the ones above: runtime-Summary.salam
TotalMemory
func TotalMemory(): i64The example for this item is shown with the ones above: runtime-Summary.salam
AvailableMemory
func AvailableMemory(): i64The example for this item is shown with the ones above: runtime-Summary.salam
UsedMemory
func UsedMemory(): i64The example for this item is shown with the ones above: runtime-Summary.salam
MarkStart
func MarkStart()main. Later calls do nothing.The example for this item is shown with the ones above: runtime-Summary.salam
UptimeMs
func UptimeMs(): i64MarkStart, by the wall clock. If MarkStart was never called, the first call starts the count.The example for this item is shown with the ones above: runtime-Summary.salam
UptimeSeconds
func UptimeSeconds(): f64The example for this item is shown with the ones above: runtime-Summary.salam
IsAsanBuild
func IsAsanBuild(): boolThe example for this item is shown with the ones above: runtime-Summary.salam
IsMemDebugBuild
func IsMemDebugBuild(): bool-DSALAM_MEM_DEBUG or --asan).The example for this item is shown with the ones above: runtime-Summary.salam
IsSafeBuild
func IsSafeBuild(): bool--release.The example for this item is shown with the ones above: runtime-Summary.salam
BuildFlags
func BuildFlags(): strrelease, or the checks that are compiled in joined with commas: safe, mem_debug, asan.The example for this item is shown with the ones above: runtime-Summary.salam
Summary
func Summary(): strlinux/x64 cpus=8 uptime_ms=3 build=release.The example for this item is shown with the ones above: runtime-Summary.salam