@memprofile/agent-node/README.md

Lightweight Node.js heap-snapshot agent for MemProfiler AI

# @memprofile/agent-node

[![npm](https://img.shields.io/npm/v/@memprofile/agent-node.svg?logo=npm)](https://www.npmjs.com/package/@memprofile/agent-node)
[![license](https://img.shields.io/github/license/memprof/agent-node.svg)](LICENSE)

> **Light-weight Node.js heap-snapshot agent for [MemProfiler AI](https://memprof.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

```bash
npm i -D @memprofile/agent-node
````

### 2 — Add secrets

```bash
# .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

```jsonc
// 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

```yaml
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

```bash
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

```bash
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