Registry / observability / gcstats.js

gcstats.js

JSON →
library1.0.0jsnpmunverified

gcstats.js is a Node.js package that provides granular statistics about V8 garbage collection events. It exposes a native binding that emits 'stats' events whenever a garbage collection cycle completes, detailing various heap metrics before and after the GC, including `totalHeapSize`, `usedHeapSize`, `totalHeapExecutableSize`, `heapSizeLimit`, `totalPhysicalSize`, and the `gctype` (Scavenge, Mark/Sweep/Compact, or both). The current stable version is 1.0.0. While there isn't a stated release cadence, updates are typically driven by compatibility requirements with new Node.js V8 engine versions or bug fixes. Its key differentiator is direct access to low-level V8 GC information, which is otherwise difficult to obtain without `--expose-gc` flags and manual polling, making it invaluable for performance monitoring and debugging memory-intensive Node.js applications.

npm install gcstats.js
INSTALL
IMPORT
SIG · GCSTATS.JS
G
gcstats.js
observabilityjavascriptv1.0.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

gcStats
✓ const gcStats = require('gcstats.js');
✗ import gcStats from 'gcstats.js';
This package uses native C++ addons and is primarily designed for CommonJS. Direct ESM `import` is not supported without a wrapper or bundler configuration. The `gcStats` instance is an EventEmitter from which you subscribe to 'stats' events.

Demonstrates how to initialize gcstats.js and subscribe to 'stats' events, logging detailed garbage collection metrics including type, pause duration, and heap usage before/after. It includes a robust memory allocation simulation to reliably trigger and showcase GC events.

const gcStats = require('gcstats.js'); gcStats.on('stats', function(stats) { const gctypeMap = { 1: 'Scavenge (Minor GC)', 2: 'Mark/Sweep/Compact (Major GC)', 3: 'All GC Types' }; console.log('--- GC Happened ---'); console.log(`Type: ${gctypeMap[stats.gctype] || 'Unknown'}`); console.log(`Pause: ${(stats.pause / 1_000_000).toFixed(2)} ms`); console.log(`Heap Used Before: ${(stats.before.usedHeapSize / (1024 * 1024)).toFixed(2)} MB`); console.log(`Heap Used After: ${(stats.after.usedHeapSize / (1024 * 1024)).toFixed(2)} MB`); console.log(`Total Heap Size: ${(stats.after.totalHeapSize / (1024 * 1024)).toFixed(2)} MB`); console.log('-------------------\n'); }); // Simulate some memory usage to trigger GC events periodically let data = []; setInterval(() => { // Allocate new data const allocationSizeMB = Math.random() * 5 + 5; // 5-10 MB data.push(Buffer.alloc(Math.floor(allocationSizeMB * 1024 * 1024))); // Periodically dereference old data to allow GC to reclaim memory if (data.length > 10) { data.splice(0, Math.floor(data.length / 2)); // Remove half of the old data } // Keep some data around to simulate a working application console.log(`Current data array size: ${data.length}, total simulated memory: ${(data.reduce((sum, buf) => sum + buf.length, 0) / (1024 * 1024)).toFixed(2)} MB`); }, 500); // Trigger allocations every 500ms console.log('gcstats.js initialized. Simulating memory usage...');
Debug
Known issues
breakingThis package relies on native C++ addons, which must be compiled for your specific Node.js version and architecture during installation. Compatibility can break with new major Node.js releases (especially those with V8 ABI changes), requiring a re-install or an update to a compatible package version.
fix
After updating Node.js, run `npm rebuild gcstats.js` or `npm install gcstats.js` to recompile the native module. Always consult the project's `compatibility.md` for specific Node.js version support and known issues.
affects: >=1.0.0
gotchaInstallation may fail if necessary build tools are not present on the system (e.g., Python 2.x/3.x, C++ compiler, `make`). `node-gyp` is used for compilation, which has specific system requirements.
fix
Ensure you have the required build tools for `node-gyp` installed on your operating system. For Windows, consider `npm install --global windows-build-tools`. For Linux/macOS, ensure development packages like `build-essential` (Debian/Ubuntu) or Xcode Command Line Tools (macOS) are installed.
affects: >=1.0.0
gotchaThe npm package name is `gcstats.js`, but internal documentation and some references (e.g., in `compatibility.md`) might refer to the native module component as `gc-stats`. Always use `gcstats.js` for `require()` statements and npm commands.
fix
Strictly use `require('gcstats.js')` in your code and `npm install gcstats.js` for package management to avoid module resolution errors.
affects: >=1.0.0
Errors
Common errors & fixes
Error: The `gcstats.js` module was compiled against a different Node.js version than the one you are currently running. This may cause runtime errors or segfaults.
The native C++ addon was compiled for a Node.js Application Binary Interface (ABI) that does not match your current Node.js runtime environment. This commonly occurs after upgrading or downgrading Node.js.
fix
Execute `npm rebuild gcstats.js` or `npm install gcstats.js` in your project directory to recompile the native module against your current Node.js version. Ensure `node-gyp` prerequisites are met.
Error: Cannot find module 'gcstats.js'
The native addon failed to compile during the `npm install` process, or the package was not installed correctly, leading to the absence of the compiled binary.
fix
Review the installation logs carefully for `node-gyp` errors. Ensure all required build tools are installed. Try running `npm install gcstats.js` again, potentially with `--force` or clearing npm cache.
Error: `node-gyp` failed to rebuild.
This error message (or similar `gyp` errors in install logs) indicates a problem with the `node-gyp` compilation process, often due to missing C++ compilers, Python, or other development tools on the system.
fix
Install the necessary build tools as per `node-gyp`'s documentation for your operating system. Common solutions include `npm install --global windows-build-tools` on Windows, or installing `build-essential` on Linux and Xcode Command Line Tools on macOS.
Upgrade
Version history
1.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
9 hits · last 30 days
node
6
OpenAI (training)
2
Resources
gcstats.js — npm install gcstats.js · libregistry