Unexpected Canister Memory Growth When Sending Emails via HTTP Outcalls

Developers
7

The memory size reported by canister settings is probably not want you want to monitor since it reflects the memory the canister has requested from the system and will generally only grow over time.

This AI generated summary of the runtime stats available to Motoko might be more useful.

Motoko rts_ Functions

The rts_ (Runtime System) functions in Motoko provide introspection into the canister’s memory and performance statistics. They are accessible via the Prim pseudo-library:

import Prim "mo:prim";

// Example usage
Prim.rts_memory_size()

Available rts_ Functions

Function Description
rts_version Returns the runtime system version as Text
rts_memory_size Total memory size in bytes
rts_heap_size Current heap size in bytes
rts_total_allocation Total amount of memory allocated over the canister’s lifetime, in bytes
rts_reclaimed Amount of memory reclaimed by the garbage collector, in bytes
rts_max_live_size Maximum live (in-use) heap size observed, in bytes
rts_mutator_instructions Approximate IC instruction cost of the last completed message due to computation/mutation
rts_collector_instructions Approximate IC instruction cost of the last completed message due to garbage collection

[Prim functions; forum]

Extended Runtime Information

A more comprehensive privileged query function is also available:

__motoko_runtime_information : () -> {
    compilerVersion : Text;
    rtsVersion : Text;
    garbageCollector : Text;
    sanityChecks : Nat;
    memorySize : Nat;
    heapSize : Nat;
    totalAllocation : Nat;
    reclaimed : Nat;
    maxLiveSize : Nat;
    stableMemorySize : Nat;
    logicalStableMemorySize : Nat;
    maxStackSize : Nat;
    callbackTableCount : Nat;
    callbackTableSize : Nat;
}

This function (__motoko_runtime_information()) is only authorized to canister controllers and self-calls of the canister. [Motoko changelog]

Important Notes

  • rts_memory_size vs rts_heap_size: rts_memory_size reflects the total Wasm memory allocated (in pages), while rts_heap_size reflects only the live heap objects. For example, an array of 1,000,000 Nat8 values may show rts_heap_size ≈ 4,000,052 bytes because Motoko uses a uniform array representation to support generics. [forum post]
  • rts_mutator_instructions / rts_collector_instructions: These report stats for the last completed message, not the current one, making them useful for post-hoc profiling. [Motoko changelog]
  • The Prim module is not officially intended for end-user use and its API may change. Use with discretion. [Prim functions; forum]