{"id":41727246,"url":"https://github.com/blueconic/node-oom-heapdump","last_synced_at":"2026-02-23T12:20:20.474Z","repository":{"id":25701462,"uuid":"105307083","full_name":"blueconic/node-oom-heapdump","owner":"blueconic","description":"Create a V8 heap snapshot right before an \"Out of Memory\" error occurs, or create a heap snapshot or CPU profile on request.","archived":false,"fork":false,"pushed_at":"2026-01-30T09:42:55.000Z","size":374,"stargazers_count":100,"open_issues_count":0,"forks_count":11,"subscribers_count":3,"default_branch":"master","last_synced_at":"2026-01-31T01:56:00.371Z","etag":null,"topics":["cpu-profile","cpu-profiling","devtools-protocol","heap-dump","heap-size","memory","memory-leak","memory-snapshot","nodejs","out-of-memory"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/blueconic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2017-09-29T18:57:07.000Z","updated_at":"2026-01-30T09:41:54.000Z","dependencies_parsed_at":"2022-07-27T05:16:33.404Z","dependency_job_id":"ad2f8a07-0d88-45b8-aec9-68d38f7ff0dc","html_url":"https://github.com/blueconic/node-oom-heapdump","commit_stats":{"total_commits":97,"total_committers":6,"mean_commits":"16.166666666666668","dds":0.08247422680412375,"last_synced_commit":"8992ffe3e252ec4605c1aca2c06a55855bb2e4f5"},"previous_names":[],"tags_count":75,"template":false,"template_full_name":null,"purl":"pkg:github/blueconic/node-oom-heapdump","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blueconic%2Fnode-oom-heapdump","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blueconic%2Fnode-oom-heapdump/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blueconic%2Fnode-oom-heapdump/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blueconic%2Fnode-oom-heapdump/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blueconic","download_url":"https://codeload.github.com/blueconic/node-oom-heapdump/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blueconic%2Fnode-oom-heapdump/sbom","scorecard":{"id":244451,"data":{"date":"2025-08-11","repo":{"name":"github.com/blueconic/node-oom-heapdump","commit":"bbf6af0bf7fc0800eb70b9e42b5ecfeeae4c14a3"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.9,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":3,"reason":"4 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 3","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/publish-native-assets-to-github-releases.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Code-Review","score":1,"reason":"Found 3/25 approved changesets -- score normalized to 1","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish-native-assets-to-github-releases.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/blueconic/node-oom-heapdump/publish-native-assets-to-github-releases.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish-native-assets-to-github-releases.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/blueconic/node-oom-heapdump/publish-native-assets-to-github-releases.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/publish-native-assets-to-github-releases.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/blueconic/node-oom-heapdump/publish-native-assets-to-github-releases.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/publish-native-assets-to-github-releases.yml:36: update your workflow using https://app.stepsecurity.io/secureworkflow/blueconic/node-oom-heapdump/publish-native-assets-to-github-releases.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish-native-assets-to-github-releases.yml:49: update your workflow using https://app.stepsecurity.io/secureworkflow/blueconic/node-oom-heapdump/publish-native-assets-to-github-releases.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/publish-native-assets-to-github-releases.yml:59: update your workflow using https://app.stepsecurity.io/secureworkflow/blueconic/node-oom-heapdump/publish-native-assets-to-github-releases.yml/master?enable=pin","Warn: npmCommand not pinned by hash: .github/workflows/publish-native-assets-to-github-releases.yml:33","Warn: npmCommand not pinned by hash: .github/workflows/publish-native-assets-to-github-releases.yml:55","Info:   0 out of   3 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   3 third-party GitHubAction dependencies pinned","Info:   0 out of   2 npmCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Signed-Releases","score":0,"reason":"Project has not signed or included provenance with any releases.","details":["Warn: release artifact 3.7.1 not signed: https://api.github.com/repos/blueconic/node-oom-heapdump/releases/229690451","Warn: release artifact 3.7.0 not signed: https://api.github.com/repos/blueconic/node-oom-heapdump/releases/223008751","Warn: release artifact 3.6.0 not signed: https://api.github.com/repos/blueconic/node-oom-heapdump/releases/217898242","Warn: release artifact 3.4.0 not signed: https://api.github.com/repos/blueconic/node-oom-heapdump/releases/190288864","Warn: release artifact 3.3.1 not signed: https://api.github.com/repos/blueconic/node-oom-heapdump/releases/161029980","Warn: release artifact 3.7.1 does not have provenance: https://api.github.com/repos/blueconic/node-oom-heapdump/releases/229690451","Warn: release artifact 3.7.0 does not have provenance: https://api.github.com/repos/blueconic/node-oom-heapdump/releases/223008751","Warn: release artifact 3.6.0 does not have provenance: https://api.github.com/repos/blueconic/node-oom-heapdump/releases/217898242","Warn: release artifact 3.4.0 does not have provenance: https://api.github.com/repos/blueconic/node-oom-heapdump/releases/190288864","Warn: release artifact 3.3.1 does not have provenance: https://api.github.com/repos/blueconic/node-oom-heapdump/releases/161029980"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":2,"reason":"SAST tool is not run on all commits -- score normalized to 2","details":["Warn: 2 commits out of 10 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-17T07:18:05.486Z","repository_id":25701462,"created_at":"2025-08-17T07:18:05.486Z","updated_at":"2025-08-17T07:18:05.486Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29742459,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-23T07:44:07.782Z","status":"ssl_error","status_checked_at":"2026-02-23T07:44:07.432Z","response_time":90,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cpu-profile","cpu-profiling","devtools-protocol","heap-dump","heap-size","memory","memory-leak","memory-snapshot","nodejs","out-of-memory"],"created_at":"2026-01-24T23:16:36.075Z","updated_at":"2026-02-23T12:20:20.382Z","avatar_url":"https://github.com/blueconic.png","language":"JavaScript","readme":"[![Build status](https://github.com/blueconic/node-oom-heapdump/actions/workflows/publish-native-assets-to-github-releases.yml/badge.svg)](https://github.com/blueconic/node-oom-heapdump/actions/workflows/publish-native-assets-to-github-releases.yml)\n\n# node-oom-heapdump\nNode module which will create a V8 heap snapshot right before an \"Out of Memory\" error occurs.\n\nIt can also create heapdumps and CPU profiles on request like 'v8-profiler', but does this off-process so it doesn't interfere with execution of the main process.\n\nTested on Node.js 10.x, 11.x, 12.x, 13.x, 14.x, 15.x, 16.x, 17.x, 18.x, 20.x, 22.x and 24.x.\nNo support for Node.js \u003c 10.x at the moment in version 3.0.0, use version 2.2.0 for if needed.  \n\nAlso comes with prebuilt binaries (hosted on Github releases), thanks to Stuart Miller (https://github.com/spmiller).\nFrom 3.1.0, prebuilt binaries are only shipped for Node.js 16.x and upwards.\nFrom 3.2.3, prebuilt binaries are only shipped for Node.js 18.x and upwards.\nIn 3.7.0, prebuilt binaries for node 24.x were added.\n\n## Node 22.x\nSince node 22.x, there is a new CLI flag for generating heapdumps. This one is supplied by V8 (not Node.js) and is more reliant and efficient in creating the heapdumps than Node.js' `--heapsnapshot-near-heap-limit`.\nMore information: https://github.com/nodejs/node/issues/50711#issuecomment-2149559816\n\n```\nnode --heap-snapshot-on-oom index.js\n```\nSince node 22.x we had issues with no heapdumps being created in production sometimes (via `--heapsnapshot-near-heap-limit`), which did work when using V8's `--heap-snapshot-on-oom`.\nThe only disadvantage i encountered is that the filename of the heapdump file does not include a process ID, just the timestamp.\n\n## Node.js 14.18.x\nhttps://github.com/nodejs/node/pull/33010 landed in Node.js 14.18.0, which makes this module no longer needed for heapdumps on out of memory.\nOne can use the `--heapsnapshot-near-heap-limit` Node.js CLI option as an alternative.\nSee https://nodejs.org/dist/latest-v14.x/docs/api/cli.html#cli_heapsnapshot_near_heap_limit_max_count.\n\n# Why?\nWhen running nodejs processes in a low memory environment, every out of memory that occurs is interesting.\nTo figure out why a process went out of memory, a heap snapshot (e.g. heapdump) can help a lot.\nThis module creates a heap snapshot right before an out of memory error occurs (by leveraging 'SetOOMErrorHandler' of the V8 engine).\nIt shows what the heap was filled with right before the out of memory error occured and can be opened with Chrome DevTools (Memory tab).\n\nThere are several modules around which can create heapdumps (v8-profiler, node-heapdump), but these run in the same process as the one going out of memory. Often, creating heapdump won't work when the node process is already struggling.\nThis module creates the heap snapshot from a separate process, which solves this issue.\nAlso, these modules are not able to create a heapdump when an out of memory occurs.\n\n# What?\nBased on the work of 'trevnorris' (https://github.com/trevnorris/node-ofe/), this module uses 'isolate.SetOOMErrorHandler' (https://v8docs.nodesource.com/node-8.9/d5/dda/classv8_1_1_isolate.html#a08fd4087f39c33b4ac1c20ad953ce4e3) of the V8 engine, and then creates a heapdump when an actual Out of Memory occurs. To make this happen, a native C++ add-on is used. \nNode-gyp is needed to compile this add-on.\n\nWhen creating a heapdump of CPU profile on request, the DevTools protocol is used to create these files (no native add-on).\nThe --inspect node.js flag is needed to make this work (which is validated on startup).\n\n# Example\nJust run \"npm test\" to see it in action. It creates a heapdump named \"my_heapdump.heapsnapshot\" in the 'tests' directory of this module.\n\n# Usage\n\n```javascript\nnpm install node-oom-heapdump\n```\n\nJust add the following snippet to your node process.\n\n```javascript\nlet path = require('path');\nrequire('node-oom-heapdump')({\n    path: path.resolve(__dirname, 'my_heapdump')\n});\n```\n\nTo make heapdumps and CPU profiles on request, your node process should at least be started with the \"--inspect\" (or --inspect=port) flag. When the module is loaded, the configured port is verified. If it doesn't respond correctly, a console warning will be shown.\n\nWhen running in a low memory environment, the following flags are advised:\n\n* --max_old_space_size=60 - this will limit your heapsize on 60MB\n* --optimize_for_size - keep memory as low as possible (GC more often than usual)\n* --always_compact - keep memory as low as possible (do compactions each GC)\n\nThese might impact performance though.\nOn Node.js 12.x the latter two flags seem to cause some stability issues (see https://github.com/nodejs/node/issues/27552#issuecomment-542695931). So, if you encounter issues on Node.js 12.x in combination with those flags, please refrain from using these.\n\n# Options\n* heapdumpOnOOM - boolean whether to create a heapdump when an out of memory occurs. Default true.\n* OOMImplementation - Only \"NATIVE_HOOK\" is supported starting from 3.0.0\n\"NATIVE_HOOK\" relies on the native v8 hook and makes sure that the heapdump is actually created when the OoM occurs. It's more impacted by the OoMKiller of Unix systems though, when being run in memory restricted environments like Docker. \n* path - the path where the heapdump ends up when an out of memory error occurs. '.heapsnapshot' is automatically appended. Defaults to this modules' directory.\n* addTimestamp - add a timestamp to the out of memory heapdump filename, to make it unique. Default is false.\n* port - optionally, the alternative DevTools protocol port. Defaults to 9229. Should map on the port given to the --inspect arg.\n\n# API\nBesides creating heapdumps when an out of memory error occurs, there also is an API for creating heapdumps and CPU profiles on request. See below for the currently available API.\n\nNotice that you cannot create a heapdump while a CPU profile is being generated and vice versa; an Error will be thrown if this is the case.\n\n```javascript\nlet nodeOomHeapdump = require(\"node-oom-heapdump\")({\n  heapdumpOnOOM: false\n});\n\n/**\n  * Returns the path to the created heap snapshot in a promise, or rejects on error\n  * @param {String} snapshotPath - path of the snapshot\n  * @return {Promise} Promise containing the heap snapshot path on success or error on rejection\n  */\nnodeOomHeapdump.createHeapSnapshot(\"myheapsnapshotpath\").then((snapshotPath) =\u003e {\n  // do something with heap snapshot\n\n  // and delete again from disk\n  nodeOomHeapdump.deleteHeapSnapshot(snapshotPath);\n}).catch((err) =\u003e {\n  // handle error\n});\n\n/**\n  * Deletes all previously created heapsnapshots from disk\n  */\nnodeOomHeapdump.deleteAllHeapSnapshots();\n\n/**\n  * Deletes a particular snapshot from disk\n  * @param {String} snapshotPath - path of the heap snapshot to delete\n  * @return {Promise}\n  */\nnodeOomHeapdump.deleteHeapSnapshot(snapshotPath);\n\n/**\n  * Returns the path to the created CPU profile in a promise, or rejects on error\n  * @param {String} cpuProfilePath - path of the CPU profile\n  * @param {number} duration - the duration of the CPU profile in ms (default: 30000ms)\n  * @return {Promise} the CPU profile path on success or error on rejection\n  */\nnodeOomHeapdump.createCpuProfile(\"mycpuprofilepath\", 10000).then((cpuProfilePath) =\u003e {\n  // do something with CPU profile\n\n  // and delete again from disk\n  nodeOomHeapdump.deleteCpuProfile(cpuProfilePath);\n}).catch((err) =\u003e {\n  // handle error\n});\n\n/**\n  * Deletes all previously created CPU profiles from disk\n  */\nnodeOomHeapdump.deleteAllCpuProfiles();\n\n/**\n  * Deletes a particular CPU profile from disk\n  * @param {String} cpuProfilePath - path to the CPU profile to delete from disk\n  * @return {Promise}\n  */\nnodeOomHeapdump.deleteCpuProfile(cpuProfilePath);\n```\n\n# Known issues and limitations\n\n## Memory usage\nWhen creating a heapdump on request, it's notorious for using a lot of memory. This is caused by a bug in V8/DevTools protocol and is reported here (https://bugs.chromium.org/p/chromium/issues/detail?id=768355); the protocol has no backpressure mechanism, which causes the heapdump to be pushed faster than the DevTools client can handle, causing in-memory buffering.\n\nThis is not a problem if your server/machine has memory to spare, but can cause issues in memory restricted environments like a Docker container. Once the process exceeds the container memory threshold, it will be killed by OoMKiller (if enabled). This leads to an empty heapsnapshot file (0 bytes).\n\nPlease vote for that issue to be fixed!\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblueconic%2Fnode-oom-heapdump","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblueconic%2Fnode-oom-heapdump","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblueconic%2Fnode-oom-heapdump/lists"}