LTavarez

Posted on Oct 19

I Built container-memory-watch: Monitoring Memory Pressure in Node.js Containers 🦀

#docker #monitoring #node #rust

Memory management is one of the challenges of running Node.js applications in Docker, Kubernetes, and cloud environments.

A Node.js application can have relatively low V8 heap usage while its container is approaching its memory limit.

That's why I developed container-memory-watch, an experimental open-source tool that combines Node.js memory metrics with Linux cgroup v2 evidence using a Rust-based collector.

🔧 Key Features

Container memory pressure detection.
Node.js RSS, V8 heap, external memory, and ArrayBuffer monitoring.
Linux cgroup v2 memory measurements.
Configurable memory pressure thresholds.
OOM kill counter tracking.
Bounded diagnostic history.
Structured JSON logs.
Optional diagnostic report exports.
Native Node.js and Rust integration.

📦 Installation

npm install container-memory-watch

⚡ Quick Start

Start monitoring memory in your Node.js application:

import { startMemoryWatch } from 'container-memory-watch';

const memory = await startMemoryWatch();

console.log('Memory monitoring started');

// Call this during graceful shutdown.
await memory.stop();

By default, the monitor samples memory every five seconds, retains up to 120 samples, and uses an 80% pressure threshold.

Node.js metrics work without the Rust collector. Container-level evidence requires Linux cgroup v2 and the compiled collector.

📊 Generate Diagnostic Reports

import {
  startMemoryWatch,
  writeDiagnosticReport
} from 'container-memory-watch';

const memory = await startMemoryWatch();

const report = memory.report();

if (report) {
  console.log(JSON.stringify(report, null, 2));

  await writeDiagnosticReport(
    './memory-report.json',
    report
  );
}

await memory.stop();

Diagnostic reports can help investigate memory behavior over a bounded observation window.

🐳 Why It Matters

When operating containerized applications, memory pressure may originate from more than JavaScript objects.

Monitoring V8 heap usage alone may overlook other contributors to container memory consumption.

container-memory-watch brings these signals together to support more informed troubleshooting.

It does not automatically identify memory leaks, prevent OOM kills, or replace established observability platforms.

🔗 Source Code & Installation

GitHub Repository:

https://github.com/uppy19d0/container-memory-watch

Main Branch:

https://github.com/uppy19d0/container-memory-watch/tree/main

npm Package:

https://www.npmjs.com/package/container-memory-watch

README & Documentation:

https://github.com/uppy19d0/container-memory-watch/blob/main/README.md

💬 Feedback Welcome

The project is open source and currently experimental.

I'd appreciate feedback on memory monitoring strategies, Node.js observability, Rust integration, and container diagnostics.

How do you currently investigate memory pressure and OOMKilled containers in production?

Contributions and suggestions are welcome!

node #rust #opensource #kubernetes

DEV Community