mem
The mem package exposes Go's runtime memory counters and standard pprof profiles. Go's runtime already samples allocations, so importing this package adds no custom instrumentation or continuous work.
import "std:mem"mem.dump(path) -> boolean
Forces a garbage collection, then writes a heap profile to path. Returns true when the complete profile was written and closed successfully, or false otherwise. The garbage collection and file write only run when dump is called. The profile atomically replaces the destination after it has been flushed and closed. A failed dump leaves an existing profile intact and removes its temporary file.
mem.dump("heap.pprof")Show the functions retaining the most live memory:
go tool pprof -top heap.pprofShow the functions responsible for the most total allocated memory instead:
go tool pprof -top -alloc_space heap.pprofCompare a later heap against an earlier baseline to find memory that remained reachable:
go tool pprof -top -base heap-before.pprof heap-after.pprofmem.dumpProfile(name, path) -> boolean
Writes any named runtime profile to path. Returns false if the profile name is unknown or the file cannot be written. Useful names for memory investigations are heap, allocs, and goroutine. Heap and allocation dumps force garbage collection first. Successful dumps replace the destination atomically; failures preserve an existing file.
mem.dumpProfile("goroutine", "goroutines.pprof")mem.stats() -> object
Returns a point-in-time runtime snapshot. Call it at intervals from application code when you need a lightweight time series; it does not start a sampler or retain previous readings.
alloc, heapAlloc
Bytes in reachable heap objects.
totalAlloc
Cumulative bytes allocated since process start.
sys
Bytes obtained from the operating system for the Go runtime. This is not RSS.
mallocs, frees, liveObjects, heapObjects
Object allocation and liveness counts.
heapSys, heapIdle, heapInuse, heapReleased
Heap reservation and release breakdown.
stackInuse, stackSys
Goroutine stack memory.
mspanInuse, mcacheInuse, gcSys, otherSys
Runtime metadata memory.
nextGC, numGC, pauseTotalNs, gcCPUFraction
Garbage collector state and cost.
goroutines
Current goroutine count.
profileRate
Average bytes allocated per heap-profile sample.
mem.gc() -> object
Forces garbage collection and returns the same object as mem.stats(). If heapAlloc keeps growing across comparable post-GC readings, take and compare heap profiles to find the roots.
mem.setProfileRate(bytes) -> number
Sets the average bytes allocated per heap-profile sample and returns the previous rate. The default is normally 524288 bytes. Set it once, as early as possible: smaller values improve profile resolution but add overhead, 1 records every allocation, and 0 disables profiling.
mem.serve(address) -> boolean
Starts the standard Go pprof HTTP endpoints on address and returns whether listening started. Bind to localhost unless the endpoint is protected; profiles can contain sensitive process data. Header reads time out after 10 seconds. The idle endpoint adds no custom sampling loop.
Open the interactive heap viewer:
Capture comparable snapshots and a goroutine profile:
The endpoint also exposes CPU profiles and runtime traces through the standard pprof paths.
mem.address() -> string
Returns the pprof listener's bound address. This includes the operating system assigned port when mem.serve("127.0.0.1:0") is used. Returns an empty string when the server is stopped.
mem.stop() -> boolean
Closes the pprof listener and its active HTTP connections. Returns false when no server is active.
Last updated