Process resources

Read node.stats.resources for process CPU, memory, thread, and handle measurements. cpu and memory also remain available in the top-level node statistics. Resource counters describe the whole process, including other Node.js engines or application memory in embedded mode.

players.active counts allocated guild players. playback.activeSessions counts sources in active states, including paused and stopping sources. Neither is a thread count. players.available is remaining allocation capacity, clamped at zero.

The resource snapshot includes collection time, sample interval, collection duration, and open handles. Older servers may omit it. Use local process discovery to inspect the same statistics without RPC credentials.

Memory accountingCopy Anchor Link

All memory counters are bytes, independent and nonadditive. Null means unsupported, inaccessible, or not yet sampled. No counter substitutes for another.

Linux rollup collection requires kernel support and permission. Losing access makes USS and PSS null while status can still supply RSS. These counters describe the process inside its current namespace, not cgroup usage or a container memory limit. Private hugetlb accounting is not added to the stated clean/dirty metric.

MacOS footprint includes platform-specific ledger accounting and compressed memory. It is not USS. The collector does not infer private resident memory from Mach's internal counter or subtract shared libraries from RSS. A reliable USS/PSS counter is unavailable through the implemented task snapshot, so these fields remain null.

Windows EX2 private working set needs a sufficiently recent Windows release. If EX2 fails, the collector falls back to EX for RSS, peak RSS, and private commit, leaving private resident null. Reserved virtual addresses are not resident RAM. Other target operating systems return null memory fields until a native backend is implemented. Available parallelism remains available where Rust supports it.

CPU and samplingCopy Anchor Link

cpu.processPercent is the difference in cumulative process user + system CPU milliseconds divided by elapsed wall milliseconds, multiplied by 100. 100% is one logical CPU and multithreaded processes can exceed 100%. It is null until two samples exist. userTimeMs and systemTimeMs are cumulative milliseconds. availableParallelism is Rust's platform estimate. threadCount counts actual OS threads, including the short-lived collector when it samples itself. loadAverage1m is the Unix system load average, not process utilization. Unsupported platform counters are null. openHandles counts Unix descriptors or Windows process handles. Linux excludes the collector's own directory enumeration handle.

A process-wide cache refreshes on demand after 1000 ms. Every caller immediately gets the previous completed snapshot while at most one background collector runs. The first call may return a snapshot with null timestamp and counters. Infrequent requests produce longer CPU measurement intervals. There is no periodic collector when nobody requests statistics. Sampling timestamps and duration make staleness and collection cost visible. Expensive OS queries run off Tokio and audio workers.

Embedded modeCopy Anchor Link

import { Remedia } from '@remedia/node';

const remedia = await Remedia.create();
try {
  const resources = remedia.processResources();
  console.log(resources.memory.privateResidentBytes, resources.memory.footprintBytes);
} finally {
  await remedia.close();
}

This synchronous method reads the native cache and schedules refresh without blocking JavaScript on collection. Embedded client node snapshots use it when the native addon supports it. Older addons retain empty CPU/memory objects and null resources. Every embedded instance in one Node.js process shares the process measurements, including memory owned by JavaScript, libraries, and other instances. They are not measurements of an individual Remedia engine or JavaScript heap.