{"id":17222954,"url":"https://github.com/rush/node-jemalloc-tools","last_synced_at":"2025-03-25T16:22:26.465Z","repository":{"id":215735955,"uuid":"739657234","full_name":"Rush/node-jemalloc-tools","owner":"Rush","description":"Node module for controlling jemalloc - extremely useful for native memory leak tracking","archived":false,"fork":false,"pushed_at":"2024-01-07T07:06:40.000Z","size":30,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-30T14:25:31.020Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Rush.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}},"created_at":"2024-01-06T06:10:42.000Z","updated_at":"2024-01-23T19:52:51.000Z","dependencies_parsed_at":"2024-01-07T08:22:34.232Z","dependency_job_id":"97b87e63-cce3-4477-b180-f1b3104e8bf0","html_url":"https://github.com/Rush/node-jemalloc-tools","commit_stats":null,"previous_names":["rush/node-jemalloc-tools"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rush%2Fnode-jemalloc-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rush%2Fnode-jemalloc-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rush%2Fnode-jemalloc-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rush%2Fnode-jemalloc-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Rush","download_url":"https://codeload.github.com/Rush/node-jemalloc-tools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245496409,"owners_count":20624884,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":"2024-10-15T04:06:50.706Z","updated_at":"2025-03-25T16:22:26.438Z","avatar_url":"https://github.com/Rush.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jemalloc-tools\n\n`jemalloc-tools` is a Node.JS module providing a comprehensive interface to control and monitor memory allocation behavior in applications using `jemalloc`, a scalable concurrent malloc implementation. This module wraps the `mallctl` interface of `jemalloc`, offering a variety of functionalities including tuning, profiling, and retrieving detailed memory usage statistics.\n\nSee also this awesome [use case on heap profiling](https://github.com/jemalloc/jemalloc/wiki/Use-Case%3A-Heap-Profiling).\n\n## Why you should use jemalloc with Node.JS?\n\n- Prevent issued with memory fragmentation. In my case, my long running server processes would crash due to OOM. After adopting `jemalloc` the memory usage stabilized.\n- Heap profiling / native memory leak detection. Use the `prof` feature of `jemalloc` and use `jeprof` tools to analyze dumps.\n\n\n## Features of this module\n\n- **Profiling Controls**: Manage profiling of memory allocations, including enabling/disabling profiling, dumping profiles, and adjusting profiling parameters.\n- **Memory Allocation Statistics**: Track various memory allocation metrics.\n- **Tuning Parameters**: Adjust `jemalloc` parameters for optimal performance based on application needs.\n- **Cache Management**: Flush thread-specific caches.\n- **Heap Usage Information**: Provides an overview of the heap usage by the application.\n\n## Installation\n\nYou first you need to have your Node app set up to use `jemalloc`.\n\n### Installing jemalloc on Ubuntu\n\nTo install `jemalloc` on Ubuntu, you can use the package manager:\n\n```bash\nsudo apt-get update\nsudo apt-get install libjemalloc-dev\n```\n\n### Loading jemalloc with LD_PRELOAD\n\nTo use `jemalloc` in your application, you can preload it using the `LD_PRELOAD` environment variable. This can be done by setting the variable before running your application:\n\n```bash\nLD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2 your_application\n```\n\nReplace `/usr/lib/x86_64-linux-gnu/libjemalloc.so.2` with the actual path to the `jemalloc` shared library on your system.\n\n### Node.js Module Installation\n\nInstall the `jemalloc-tools` module using npm or yarn:\n\n```bash\nnpm install jemalloc-tools\n# or\nyarn add jemalloc-tools\n```\n\n## Usage\n\n```typescript\nimport { ctl, version, tuning, prof, decay, stats, arenas, flushThreadCache, getHeapUsage } from 'jemalloc-tools';\n\n// Most functionity will either throw or return undefined/0 if jemalloc is not present.\nconst hasJemalloc = !!version; \n\n// Retrieve the jemalloc version\nconsole.log(`jemalloc version: ${version}`);\n\n// Tuning example (can also be done via MALLOC_CONF and retrieved here)\ntuning.backgroundThread = true; // collect free'd memory in background threads\ntuning.dirtyDecayMs = 30000; // set higher to save CPU usage\ntuning.muzzyDecayMs = 30000;\n\n\nif (prof.enabled) { // it's useful to start the app with prof:true:prof_enabled:false\n  // Profiling example\n  prof.active = true;\n  prof.prefix = `my_node_app`;\n  prof.dump(); // will dump using the prefix above, or the default pefix\n  prof.dump('/tmp/profile_output'); // will dump a prof to this specified file\n  prof.gdump = true;\n  prof.reset();\n}\n\n// Get simple heap usage statistics\nconst heapUsage = getHeapUsage();\nconsole.log(`Heap used: ${heapUsage.used}, Total: ${heapUsage.total}`);\n\n// Flush thread cache (could be used along with process.gc() perhaps)\nflushThreadCache();\n\n// Get arena statistics\nconst arenaStats = arenas.getArenaStats(0);\nconsole.log(`Arena 0 stats:`, arenaStats);\n```\n\nLook at Typescipt bindings and [jemalloc mallctl docs](https://jemalloc.net/jemalloc.3.html#mallctl_namespace).\n\n## API\n\n### `version`\nRetrieves the current version of `jemalloc` and can be used to check if it's being used as the current allocator.\n\n### `ctl`\nDirect mapping to the `mallctl` interface of `jemalloc`. It can be used to implement any missing functionality from this module by hand. Of couse Pull Requests are welcome.\n\n### `tuning`\nAdjustable parameters for tuning `jemalloc` behavior, including `background_thread`, `dirty_decay_ms`, and `muzzy_decay_ms`.\n\n### `prof`\nControls for memory allocation profiling, including enabling/disabling profiling, managing dump files, and resetting profiling statistics.\n\n### `stats`\nAccess various statistics such as the amount of memory allocated, active, resident, and more.\n\n### `arenas`\nInterface for working with `jemalloc` arenas, including retrieving arena statistics.\n\n### `flushThreadCache()`\nFlushes the thread-specific cache.\n\n### `getHeapUsage()`\nProgesses epoch \u0026 returns an object containing information about the heap usage.\n\n### `progressEpoch()`\nProgresses epoch, a pre-requisite to get fresh stats.\n\n## Contributing\n\nContributions to `jemalloc-tools` are welcome. Please submit a MR.\n\n## License\n\nThis module is based on https://github.com/alxvasilev/malloc-tools\n\nThe license is BSD\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frush%2Fnode-jemalloc-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frush%2Fnode-jemalloc-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frush%2Fnode-jemalloc-tools/lists"}