@memprofile/agent-node

Light-weight Node.js heap-snapshot agent for MemProfiler AI
• 9 MB footprint • no code changes • gzip snapshots • 2-minute setup

✨ What it does

1. Hooks the V8 Inspector and records a heap-snapshot every N seconds.
2. Gzips the snapshot and streams it to your MemProfiler AI backend
   (/v1/snapshots, authenticated by x-api-key).
3. Cleans up local files (keeps the three most-recent snapshots).
4. Runs either
   • as a preload (node -r @memprofile/agent-node/register …) or
   • as a stand-alone CLI (memprof-agent) – great for Docker side-cars.

No metrics are sent anywhere else.
The agent touches only: the Inspector socket, your temp folder, and your HTTPS upload endpoint.

🚀 Quick start

1 — Install

npm i -D @memprofile/agent-node

2 — Add secrets

# .env  (do NOT commit)
MEMPROF_API_KEY=sk_test_demo123
MEMPROF_ENDPOINT=https://api.memprofiler.io/v1/snapshots
MEMPROF_INTERVAL=3600           # seconds, default 1 h
MEMPROF_THRESHOLD=10            # % growth to alert, backend side

3 — Preload in dev / prod

// package.json
"scripts": {
  "dev":        "node -r dotenv/config -r @memprofile/agent-node/register node_modules/next/dist/bin/next dev",
  "start":      "node -r dotenv/config -r @memprofile/agent-node/register node_modules/next/dist/bin/next start"
}

Run your app; the console prints:

[memprof] snapshot 1722086400.heapsnapshot (14.2 MB) uploaded

Within two snapshots you’ll get a Slack / e-mail alert from MemProfiler AI, complete with SVG flame-graph and GPT root-cause summary.

🛠️ Configuration

| Env variable | Default | Purpose | | ------------------- | ----------------------------------------- | ---------------------------------------- | | MEMPROF_API_KEY | (none) | Provided by the MemProfiler AI dashboard | | MEMPROF_ENDPOINT | https://api.memprofiler.io/v1/snapshots | Upload URL | | MEMPROF_INTERVAL | 3600 | Seconds between snapshots | | MEMPROF_THRESHOLD | 10 | % heap-growth that the backend flags | | MEMPROF_HOSTNAME | OS hostname | Override if running multi-proc | | MEMPROF_TMP | .snapshots | Where raw files are kept locally |

Set via .env, Docker -e, or k8s ConfigMap – the agent reads on start-up.

🐳 Docker / Kubernetes side-car

services:
  web:
    image: node:20
    command: ["node","app.js"]
    env_file: .env
  memprof-agent:
    image: node:20
    volumes:
      - /proc:/host/proc:ro
    env_file: .env
    command: ["memprof-agent","--target-pid","1"]

--target-pid attaches to the main container via the Inspector without modifying the app image.

🔍 CLI usage

npx memprof-agent --help

memprof-agent [options]

Options:
  --interval <sec>     override MEMPROF_INTERVAL
  --target-pid <pid>   attach to an external Node process
  --once               take a single snapshot then exit

🧪 Reproducing a leak locally

npm i -D autocannon
autocannon -c 50 -d 180 http://localhost:3000/api/data   # hammer endpoint

Watch the agent logs and see Slack fill with SVG flame-graphs.

🆘 Troubleshooting

| Symptom | Fix | | ------------------------------------- | -------------------------------------------------------------------- | | ReferenceError: inspector not found | Your build tool removed Node internals; run on vanilla Node. | | Snapshot >100 MB | Increase interval or run agent in local-diff mode (coming soon). | | 401 Unauthorized from backend | Check MEMPROF_API_KEY; requires org owner scope. | | Behind corporate proxy | Set HTTPS_PROXY env var – the agent uses node-fetch. |

🤝 Contributing

1. git clone https://github.com/memprof/agent-node && cd agent-node
2. npm ci && npm run build && npm test must stay green
3. Open pull-request – we squash & release on tag vX.Y.Z.

📜 License

Apache-2.0 – free for commercial and open-source use.

© 2025 MemProfile AI GmbH – built with ❤️ in Berlin