{"id":51544954,"url":"https://github.com/robertolima-dev/rust-node-monitor","last_synced_at":"2026-07-09T17:01:48.616Z","repository":{"id":366882540,"uuid":"1278334291","full_name":"robertolima-dev/rust-node-monitor","owner":"robertolima-dev","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-23T18:56:58.000Z","size":65,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-23T19:06:08.219Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robertolima-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-23T17:34:56.000Z","updated_at":"2026-06-23T18:57:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/robertolima-dev/rust-node-monitor","commit_stats":null,"previous_names":["robertolima-dev/rust-node-monitor"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/robertolima-dev/rust-node-monitor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertolima-dev%2Frust-node-monitor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertolima-dev%2Frust-node-monitor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertolima-dev%2Frust-node-monitor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertolima-dev%2Frust-node-monitor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robertolima-dev","download_url":"https://codeload.github.com/robertolima-dev/rust-node-monitor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robertolima-dev%2Frust-node-monitor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35306717,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-09T02:00:07.329Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-09T17:01:47.419Z","updated_at":"2026-07-09T17:01:48.609Z","avatar_url":"https://github.com/robertolima-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rust-node-monitor\n\n**Lightweight Node.js monitoring powered by Rust.**\n\n`rust-node-monitor` is a lightweight monitor for Node.js applications with a\ncore written in Rust, built to collect process metrics — and, in upcoming\nreleases, HTTP metrics — with very low overhead.\n\nIt ships as a prebuilt native addon (via [napi-rs](https://napi.rs/)), so there\nis **no compiler required at install time** on supported platforms.\n\n[![CI](https://github.com/robertolima-dev/rust-node-monitor/actions/workflows/CI.yml/badge.svg)](https://github.com/robertolima-dev/rust-node-monitor/actions/workflows/CI.yml)\n[![npm](https://img.shields.io/npm/v/rust-node-monitor.svg)](https://www.npmjs.com/package/rust-node-monitor)\n![node](https://img.shields.io/badge/node-%3E%3D18-43853d)\n![license](https://img.shields.io/badge/license-MIT-blue)\n\n🌐 **Website:** [rust-node-monitor.vercel.app](https://rust-node-monitor.vercel.app/)\n\n---\n\n## Installation\n\n```bash\nnpm install rust-node-monitor\n```\n\nWorks with both **ESM** and **CommonJS**, and requires **Node.js 18+**.\n\n---\n\n## Quick start\n\n```ts\nimport { snapshot } from \"rust-node-monitor\";\n\nconsole.log(snapshot());\n```\n\n```js\n// CommonJS\nconst { snapshot } = require(\"rust-node-monitor\");\nconsole.log(snapshot());\n```\n\nExample output:\n\n```js\n{\n  pid: 12345,\n  cpuPercent: 12.5,\n  memoryRss: 84520960,\n  memoryVirtual: 312000000,\n  threads: 8,\n  uptimeSeconds: 3600,\n  timestamp: 1710000000\n}\n```\n\n---\n\n## API\n\n### `hello(): string`\n\nA sanity check that confirms the native addon loaded correctly. Returns\n`\"Hello from Rust\"`.\n\n```ts\nimport { hello } from \"rust-node-monitor\";\nconsole.log(hello()); // \"Hello from Rust\"\n```\n\n### `snapshot(): Snapshot`\n\nCollects a point-in-time snapshot of the **current process**.\n\n```ts\nimport { snapshot } from \"rust-node-monitor\";\n\nconst metrics = snapshot();\nconsole.log(metrics.pid);\nconsole.log(metrics.memoryRss);\nconsole.log(metrics.cpuPercent);\n```\n\n| Field            | Type     | Description                                            |\n| ---------------- | -------- | ------------------------------------------------------ |\n| `pid`            | `number` | Process ID                                             |\n| `cpuPercent`     | `number` | Process CPU usage (%). See the CPU note below          |\n| `memoryRss`      | `number` | Resident set size, in bytes                            |\n| `memoryVirtual`  | `number` | Virtual memory, in bytes                               |\n| `threads`        | `number` | OS thread count (best-effort per platform)             |\n| `uptimeSeconds`  | `number` | Seconds since the process started                      |\n| `timestamp`      | `number` | Unix timestamp (seconds) at collection time            |\n\n\u003e **CPU note:** A single `snapshot()` call may report `cpuPercent: 0`. CPU usage\n\u003e requires two samples spaced over time to compute a delta, and an isolated call\n\u003e has no interval to compare against. For continuous, reliable CPU use the\n\u003e [`Monitor`](#monitor) class.\n\n### `Monitor`\n\nA continuous process monitor. Unlike `snapshot()`, it computes `cpuPercent`\nreliably by accumulating process CPU time between samples and dividing by the\nreal elapsed time (aggregated across all cores — it can exceed 100% under\nmulti-threaded load).\n\n```ts\nimport { Monitor } from \"rust-node-monitor\";\n\nconst monitor = new Monitor({\n  intervalMs: 1000,\n  collectCpu: true,\n  collectMemory: true,\n});\n\nmonitor.start();\n\nsetInterval(() =\u003e {\n  console.log(monitor.stats());\n}, 1000);\n\n// later…\nmonitor.stop();\n```\n\n`monitor.stats()` returns a `Snapshot` plus a `samples` counter. The internal\ntimer is `unref`'d, so it will not keep your process alive on its own.\n\n### `prometheus(stats?): string`\n\nRenders a snapshot in the Prometheus text exposition format.\n\n```ts\nimport express from \"express\";\nimport { prometheus, Monitor } from \"rust-node-monitor\";\n\nconst monitor = new Monitor().start();\nconst app = express();\n\napp.get(\"/metrics\", (_req, res) =\u003e {\n  res.type(\"text/plain\").send(prometheus(monitor.stats()));\n});\n```\n\n### `checkAlerts(thresholds, stats?): Alert[]`\n\nSimple, stateless threshold alerts over the process metrics. Pass the thresholds\nyou want to watch; it returns the alerts that fired (a metric **exceeds** its\nthreshold). Only the thresholds you provide are evaluated.\n\n```ts\nimport { Monitor, checkAlerts } from \"rust-node-monitor\";\n\nconst monitor = new Monitor().start();\n\nsetInterval(() =\u003e {\n  const fired = checkAlerts(\n    { cpuPercent: 80, memoryRssBytes: 500_000_000 },\n    monitor.stats(), // pass stats for reliable CPU; defaults to snapshot()\n  );\n  for (const alert of fired) {\n    console.warn(`[alert] ${alert.metric}=${alert.value} \u003e ${alert.threshold}`);\n  }\n}, 5000);\n```\n\nEach `Alert` is `{ metric, value, threshold, severity: \"warning\" }`, where\n`metric` is one of `\"cpuPercent\"`, `\"memoryRssBytes\"`, `\"memoryVirtualBytes\"`.\nBeing stateless, *you* decide when to evaluate and what to do with the result\n(log, page, open an incident, forward to ImmutableLog…).\n\n---\n\n## Framework integrations\n\nThese subpath imports record per-request latency and error counts into a shared\ncollector (or one you provide). The framework packages are **optional peer\ndependencies** — install only what you use.\n\n### Express\n\n```ts\nimport express from \"express\";\nimport { monitorMiddleware, getRequestMetrics } from \"rust-node-monitor/express\";\n\nconst app = express();\napp.use(monitorMiddleware());\n\napp.get(\"/health\", (_req, res) =\u003e res.json({ ok: true }));\napp.get(\"/stats\", (_req, res) =\u003e res.json(getRequestMetrics()));\n```\n\n### Fastify\n\n```ts\nimport Fastify from \"fastify\";\nimport { monitorPlugin } from \"rust-node-monitor/fastify\";\n\nconst fastify = Fastify();\nfastify.register(monitorPlugin);\n```\n\n### NestJS\n\n```ts\nimport { RustNodeMonitorInterceptor } from \"rust-node-monitor/nestjs\";\n\n// In main.ts\napp.useGlobalInterceptors(new RustNodeMonitorInterceptor());\n```\n\n---\n\n## Supported platforms\n\nPrebuilt binaries are published for:\n\n| OS      | Architecture | Triple                       |\n| ------- | ------------ | ---------------------------- |\n| macOS   | arm64        | `aarch64-apple-darwin`       |\n| macOS   | x64          | `x86_64-apple-darwin`        |\n| Linux   | x64 (glibc)  | `x86_64-unknown-linux-gnu`   |\n| Linux   | arm64 (glibc)| `aarch64-unknown-linux-gnu`  |\n| Windows | x64          | `x86_64-pc-windows-msvc`     |\n\n---\n\n## How it works\n\n```\n┌──────────────────────────┐     ┌───────────────────────────┐\n│  Your Node.js app (TS/JS)│────▶│  rust-node-monitor (JS API)│\n└──────────────────────────┘     │  Monitor, prometheus, …    │\n                                  └─────────────┬──────────────┘\n                                                │ N-API (napi-rs)\n                                  ┌─────────────▼──────────────┐\n                                  │  Rust core (.node addon)   │\n                                  │  snapshot(), hello()       │\n                                  │  sysinfo + platform calls  │\n                                  └────────────────────────────┘\n```\n\nThe native core is built with `napi-rs`: the `#[napi]` macro generates the glue\nthat registers Rust functions as ordinary JavaScript functions. `snake_case`\nfield names become `camelCase` in JS automatically, and TypeScript types are\ngenerated into `binding.d.ts`.\n\n---\n\n## Limitations (v0.1.0)\n\n- `snapshot()` reports `cpuPercent: 0` on the first call — use `Monitor` for\n  continuous CPU.\n- `threads` is collected via `/proc` on Linux and Mach APIs on macOS. On other\n  platforms it returns `0` for now (planned for v0.2.0).\n- Metrics are scoped to the **current process** (no child-process aggregation\n  yet).\n\n---\n\n## Roadmap\n\n**Shipped in v0.2.0**\n\n- ✅ Simple threshold alerts (high CPU, high memory) via `checkAlerts(...)`.\n\n**Planned**\n\n- 🔜 Event loop delay tracking (and a \"stalled loop\" alert).\n- 🔜 Full request metrics (total, errors, latency avg/p95/p99) wired natively.\n- 🔜 First-class Prometheus exporter helpers per framework.\n- 🔜 Windows thread count.\n- 🔜 Optional integration with ImmutableLog for health/audit events.\n\n---\n\n## Development\n\n```bash\n# install dependencies\nnpm install\n\n# build the native addon (Rust) + the TypeScript layer\nnpm run build\n\n# run tests\nnpm test\n```\n\nSee [`docs/PASSO-A-PASSO.md`](./docs/PASSO-A-PASSO.md) for a full, step-by-step\nbuild log (in Portuguese) explaining the Rust and napi-rs details.\n\n---\n\n## License\n\n[MIT](./LICENSE) © [Roberto Lima](https://github.com/robertolima-dev)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobertolima-dev%2Frust-node-monitor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobertolima-dev%2Frust-node-monitor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobertolima-dev%2Frust-node-monitor/lists"}