{"id":13447816,"url":"https://github.com/sfninja/thetool","last_synced_at":"2025-03-22T01:31:24.086Z","repository":{"id":46937188,"uuid":"186057844","full_name":"sfninja/thetool","owner":"sfninja","description":"thetool is a CLI tool to capture different cpu, memory and other profiles for your node app in Chrome DevTools friendly format","archived":false,"fork":false,"pushed_at":"2023-01-03T21:45:35.000Z","size":355,"stargazers_count":222,"open_issues_count":14,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-15T03:18:05.597Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sfninja.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}},"created_at":"2019-05-10T21:44:07.000Z","updated_at":"2024-10-08T18:52:39.000Z","dependencies_parsed_at":"2023-02-01T10:31:26.145Z","dependency_job_id":null,"html_url":"https://github.com/sfninja/thetool","commit_stats":null,"previous_names":["ak239/thetool"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfninja%2Fthetool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfninja%2Fthetool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfninja%2Fthetool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfninja%2Fthetool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sfninja","download_url":"https://codeload.github.com/sfninja/thetool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244893450,"owners_count":20527594,"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-07-31T05:01:27.556Z","updated_at":"2025-03-22T01:31:23.789Z","avatar_url":"https://github.com/sfninja.png","language":"JavaScript","funding_links":[],"categories":["Packages","JavaScript","Repository","包","目录","others","Using DevTools frontend with other platforms"],"sub_categories":["Debugging / Profiling","Performance Profiling/Analysis","调试 / 分析","调试/分析","Browser Adapters","调试"],"readme":"# thetool\n\n\u003c!-- [START badges] --\u003e\n[![Build Status](https://img.shields.io/travis/com/ak239/thetool/master.svg)](https://travis-ci.com/ak239/thetool)\n[![NPM thetool package](https://img.shields.io/npm/v/thetool.svg)](https://npmjs.org/package/thetool)\n\u003c!-- [END badges] --\u003e\n\n\u003e thetool is a CLI tool to capture different cpu, memory and other profiles for your node app in Chrome DevTools friendly format.\n\n## Quick start\n```bash\nnpx thetool -o . -t memorysampling npm run test\n# .. open DevTools frontend and do three clicks to get:\n```\n\u003cimg width=\"1059\" alt=\"Screen Shot 2019-05-27 at 2 10 14 AM\" src=\"https://user-images.githubusercontent.com/426418/58388239-f9d25580-8024-11e9-8d35-a7ce4f6a4137.png\"\u003e\n\n## Getting Started\n\n\u003e thetool works only with Node \u003e= 10.x.\n\nthetool interface is simple as 1-2-3.\n1. Specify **output folder using `-o`** flag, e.g. `-o .` to put output in current folder.\n2. Specify **tool using `-t`**, available tools: [cpu](https://github.com/ak239/thetool#cpu-profiler), [memorysampling](https://github.com/ak239/thetool#sampling-memory-profiler), [memoryallocation](https://github.com/ak239/thetool#allocation-memory-profiler), [coverage](https://github.com/ak239/thetool#coverage-profiler), [type](https://github.com/ak239/thetool#type-profiler), [heapsnapshot](https://github.com/ak239/thetool#heap-snapshot-tool).\n3. Specify **any command to start node**, e.g. `node index.js` or `npx thetool` or `npm run test`.\n\nWhen report is ready, thetool will dump `thetool\u003e Report captured in ...` message in terminal with a hint how to analyze it.\n\n## Why not to use Chrome DevTools directly?\n- it can be used in environments where it is not possible to run Chrome DevTools, e.g., on the server, run `thetool \u003cyourapp\u003e` there, send report back and analyze it locally,\n- it supports child processes and workers,\n- it supports some other tools, e.g., node tracing and type profiler.\n\n## Tool selector\n\n| Problem | Tool | Insight | DevTools tab |\n|-|-|-|-|\n| my app is slow | [cpu](https://github.com/ak239/thetool#cpu-profiler) | where in code does app spend most time? | Performance |\n| my app requires too much memory | [memorysampling](https://github.com/ak239/thetool#sampling-memory-profiler) | where in code does app allocate most memory? | Memory |\n| my app requires too much memory | [memoryallocation](https://github.com/ak239/thetool#allocation-memory-profiler) | most precise version of memorysampling with much bigger overhead | Memory |\n| my app requires too much memory | [heapsnapshot](https://github.com/ak239/thetool#heap-snapshot-tool) | what is inside the heap right now? | Memory |\n| my app package is too big | [coverage](https://github.com/ak239/thetool#coverage-profiler) | what code was executed and how many times? | |\n| my app needs type annotations | [type](https://github.com/ak239/thetool#type-profiler) | what are the types of function arguments and returns? | |\n\n## On-demand tooling\n\nYou can use `--ondemand` flag to profile only part of your app:\n1. Add `--ondemand` flag to the list of thetool arguments.\n2. Call `startTheTool/stopTheTool` from your Node scripts (thetool will add these methods to Node context).\n\n`startTheTool/stopTheTool` methods are asynchronous, so you should await them or chain them using `promise.then`\n\nCouple examples:\n```js\nasync function main() {\n  await startTheTool();\n  // code of your app\n  await stopTheTool();\n}\n// .. or using promises..\nfunction main() {\n  startTheTool().then(() =\u003e {\n    // code of your app\n  }).then(() =\u003e stopTheTool());\n}\n```\n\n## CPU: Profiler\n\n```bash\nthetool -o . -t cpu npm run test\n```\n\nTo analyze: open Chrome DevTools, to to Performance tab, click load button, select file with data.\n\n\u003cimg width=\"1059\" alt=\"Screen Shot 2019-05-27 at 2 10 14 AM\" src=\"https://user-images.githubusercontent.com/426418/58388318-f55a6c80-8025-11e9-9826-6432b588ed84.png\"\u003e\n\n## Memory: Sampling Profiler\n\n```bash\nthetool -o . -t memorysampling npm run test\n```\n\nTo analyze: open Chrome DevTools, go to Memory tab, click load button, select file with data.\n\n`--samplingInterval` option is available: average sample interval in bytes, poisson distribution is used for the intervals. The default value is 32768 bytes\n\n\u003cimg width=\"1059\" alt=\"Screen Shot 2019-05-27 at 2 10 14 AM\" src=\"https://user-images.githubusercontent.com/426418/58388239-f9d25580-8024-11e9-8d35-a7ce4f6a4137.png\"\u003e\n\n## Memory: Allocation Profiler\n\n```bash\nthetool -o . -t memoryallocation npm run test\n```\n\nTo analyze: open Chrome DevTools, go to Memory tab, click load button, select file with data.\n\n\u003cimg width=\"1059\" alt=\"Screen Shot 2019-05-27 at 2 10 14 AM\" src=\"https://user-images.githubusercontent.com/426418/58388341-4cf8d800-8026-11e9-9ac5-429a33523ea0.png\"\u003e\n\n## Memory: Heap Snapshot\n\n```bash\nthetool -o . -t heapsnapshot node -e \"captureTheTool.then(captureTheTool).then(captureTheTool)\"\n```\n\nGiven command will capture three heap snapshots.\nTo analyze: open Chrome DevTools, go to Memory tab, click load button, select file with data. You can load multiple snapshots and compare them from DevTools UI.\n\n\u003cimg width=\"1059\" alt=\"Screen Shot 2019-05-27 at 2 10 14 AM\" src=\"https://user-images.githubusercontent.com/426418/58388382-c264a880-8026-11e9-92c9-b455d05b89c4.png\"\u003e\n\n## Tracing\n\n```bash\nthetool -o . -t tracing --recordMode recordAsMuchAsPossible --includedCategories node,v8 npm run test\n```\n\nTo analyze: open Chrome DevTools, go to Performance tab, click load button, select file with data.\n\n`--recordMode` controls how the trace buffer stores data (recordUntilFull, recordContinuously, recordAsMuchAsPossible)\n`--includedCategories` please take a look on different available categories on https://nodejs.org/api/tracing.html\n\nE.g. you can capture V8 sampling profiler using following command:\n```bash\nthetool -o . -t tracing --recordMode recordAsMuchAsPossible --includedCategories v8.execute,v8.cpu_profiler,v8.cpu_profiler.hires npm run test\n```\n\n\u003cimg width=\"1059\" alt=\"Screen Shot 2019-05-27 at 2 10 14 AM\" src=\"https://user-images.githubusercontent.com/426418/58388415-1ec7c800-8027-11e9-9299-165a24dd6cdb.png\"\u003e\n\n## Coverage Profiler\n\n```bash\nthetool -o . -t coverage npm run test\n```\n\nTo analyze: in current folder create ./coverage/tmp folder and move files with data to this folder, run [c8](https://www.npmjs.com/package/c8): `npx c8 report`. Please take a look at c8 README.md to see what output formats are supported.\n\n\u003cimg width=\"1059\" alt=\"Screen Shot 2019-05-27 at 2 10 14 AM\" src=\"https://user-images.githubusercontent.com/426418/58388465-e2e13280-8027-11e9-9a75-e2d278d984c7.png\"\u003e\n\n## Type Profiler\n\n```bash\nthetool -o . -t type npm run test\n```\n\nTo analyze: no tool yet.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsfninja%2Fthetool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsfninja%2Fthetool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsfninja%2Fthetool/lists"}