{"id":13393457,"url":"https://github.com/davidmarkclements/0x","last_synced_at":"2025-10-19T08:43:53.376Z","repository":{"id":37390974,"uuid":"52283973","full_name":"davidmarkclements/0x","owner":"davidmarkclements","description":"🔥 single-command flamegraph profiling 🔥","archived":false,"fork":false,"pushed_at":"2024-11-18T16:33:13.000Z","size":12170,"stargazers_count":3371,"open_issues_count":1,"forks_count":109,"subscribers_count":32,"default_branch":"master","last_synced_at":"2025-05-08T23:34:10.025Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davidmarkclements.png","metadata":{"files":{"readme":"readme.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2016-02-22T15:39:40.000Z","updated_at":"2025-05-07T21:02:45.000Z","dependencies_parsed_at":"2022-07-12T12:49:36.009Z","dependency_job_id":"c8186772-96c9-4595-8a1b-9cb729462709","html_url":"https://github.com/davidmarkclements/0x","commit_stats":{"total_commits":452,"total_committers":40,"mean_commits":11.3,"dds":0.4845132743362832,"last_synced_commit":"8d34f06bce33c287e6e50ee602ef4b1b55175101"},"previous_names":[],"tags_count":80,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidmarkclements%2F0x","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidmarkclements%2F0x/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidmarkclements%2F0x/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidmarkclements%2F0x/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidmarkclements","download_url":"https://codeload.github.com/davidmarkclements/0x/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254442854,"owners_count":22071877,"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-30T17:00:53.261Z","updated_at":"2025-10-19T08:43:53.370Z","avatar_url":"https://github.com/davidmarkclements.png","language":"JavaScript","readme":"# 0x\n\n\u003cimg alt=0x src=assets/0x-logo.png width=350\u003e\n\n🔥 single-command flamegraph profiling 🔥\n\nDiscover the bottlenecks and hot paths in your code, with flamegraphs.\n\n## Visualize Stack Traces\n\n`0x` can profile and generate an interactive flamegraph for a Node process with a single command,\non any platform which Node runs on (macOs, Linux, Windows, Android...).\n\n## Support\n\n* Node v20.x and above\n* Default usage supports any Operating System that Node runs on!\n* Chrome\n  * Other browsers may open flamegraphs in a degraded, but functional form\n\n## Install\n\n```sh\nnpm install -g 0x\n```\n\n## Usage\n\nUse `0x` to run a script:\n\n```sh\n0x my-app.js\n```\n\nImmediately open the flamegraph in the browser:\n\n```sh\n0x -o my-app.js\n```\n\nAutomatically execute profiling command against the first\nport opened by profiled process:\n\n```sh\n0x -P 'autocannon localhost:$PORT' my-app.js\n```\n\nUse a custom node executable:\n\n```sh\n0x -- /path/to/node my-app.js\n```\n\nPass custom arguments to node:\n\n```sh\n0x -- node --zero-fill-buffers my-app.js\n```\n\n\u003e for pwsh users, switch to CMD at first or run with `npx` \n\u003e \n```\nnpx 0x -o my-app.js\n```\n\n## Generating\n\nWhen ready to generate a flamegraph, send a SIGINT or a SIGTERM.\n\nThe simplest way to do this is pressing CTRL+C.\n\nWhen `0x` catches the SIGINT or the SIGTERM, it process the stacks and\ngenerates a profile folder (`\u003cpid\u003e.0x`), containing `flamegraph.html`.\n\n## The UI\n\nThe `flamegraph.html` file contains the 0x UI, which is explained in\n[docs/ui.md](docs/ui.md).\n\n## Production Servers\n\nA lightweight, production server friendly, approach to generating a\nflamegraph is described in [docs/production-servers.md](docs/production-servers.md).\n\n## The Profile Folder\n\nBy default, a Profile Folder will be created and named after the PID, e.g.\n`3866.0x` (we can set this name manually using the `--output-dir` flag).\n\nThe Profile Folder is explained in more detail in [docs/profile-folder.md](docs/profile-folder.md)\n\n## Example\n\nClone this repo, run `npm i -g` and from the repo root run\n\n```sh\n0x examples/rest-api\n```\n\nIn another tab run\n\n```sh\nnpm run stress-rest-example\n```\n\nTo put some load on the rest server, once that's done\nuse ctrl + c to kill the server.\n\n## Command Line API\n\n### --help | -h\n\nPrint usage info.\n\n### --open | -o\n\nOpen the flamegraph in the browser using `open` or `xdg-open` (see\nhttps://www.npmjs.com/package/open for details).\n\n### --on-port | -P\n\nRun a given command and then generate the flamegraph.\nThe command as specified has access to a `$PORT` variable.\nThe `$PORT` variable is set according to the first port that\nprofiled process opens.\n\nFor instance, here's an example of using [autocannon](http://npm.im/autocannon)\nto load-test the process:\n\n```sh\n0x -P 'autocannon localhost:$PORT' app.js\n```\n\nWhen the load-test completes, the profiled processed will be\nsent a SIGINT and the flamegraph will be automatically generated.\n\nRemember to use single quotes to avoid bash interpolation,\nor else escape variable (e.g. `0x -P \"autocannon localhost:$PORT\" app.js`\nwon't work wheras `0x -P \"autocannon localhost:\\$PORT\" app.js` will).\n\nNote: On Windows interpolation usually occurs with `%PORT%`, however\nin this case the dollar-prefix `$PORT` is the correct syntax\n(because the interpolation is not shell based).\n\nDefault: ''\n\n### --name\n\nThe name of the HTML file, without the .html extension\nCan be set to - to write HTML to STDOUT (note\ndue to the nature of CLI argument parsing, this must be set using `=`,\ne.g. `--name=-`).\n\nIf either this flag or `--output-html-file` is set to `-`\nthen the HTML will go to STDOUT.\n\nDefault: flamegraph\n\n### ---title\n\nSet the title to display in the flamegraph UI.\n\nDefault: the command that 0x ran to start the process\n\n### --output-dir | -D\n\nSpecify artifact output directory. This can be specified in template\nform with possible variables being `{pid}`, `{timestamp}`, `{name}`\n(based on the `--name` flag) and `{outputDir}`(variables\nmust be specified without whitespace, e.g. `{ pid }` is not supported).\n\nDefault: `{pid}.0x`\n\n### --output-html | -F\n\nSpecify destination of the generated flamegraph HTML file.\nThis can be specified in template form with possible variables\nbeing `{pid}`, `{timestamp}`, `{name}` (based on the `--name` flag) and\n`{outputDir}` (variables must be specified without whitespace,\ne.g. `{ pid }` is not supported). It can also be set to `-` to\nsend the HTML output to STDOUT (note\ndue to the nature of CLI argument parsing, this must be set using `=`,\ne.g. `--output-html=-`).\n\nIf either this flag or `--name` is set to `-`\nthen the HTML will go to STDOUT.\n\nDefault: `{outputDir}/{name}.html`\n\n### --kernel-tracing\n\nUse an OS kernel tracing tool (perf on Linux). This will capture\nnative stack frames (C++ modules and Libuv I/O),\nbut may result in missing stacks from Node.js due to the optimizing compiler.\n\nSee [docs/kernel-tracing.md](docs/kernel-tracing.md) for more information.\n\nDefault: false\n\n### --quiet | -q\n\nLimit output, the only output will be fatal errors or\nthe path to the `flamegraph.html` upon successful generation.\n\nDefault: false\n\n### --silent | -s\n\nSuppress all output, except fatal errors.\n\nDefault: false\n\n### --collect-only\n\nDon't generate the flamegraph, only create the Profile Folder,\nwith relevant outputs.\n\nDefault: false\n\n### --collect-delay\n\nDelay the collection of stacks by a specified time(ms) relative to the first entry.\n\nDefault: 0\n\n### --visualize-only\n\nSupply a path to a profile folder to build or rebuild visualization\nfrom original stacks.\n\nDefault: undefined\n\n### --visualize-cpu-profile\n\nSupply a path to a CPU profile (`.cpuprofile`). See `examples/cpu-profile` for examples.\n\n[CPU Profile](https://developers.google.com/web/tools/chrome-devtools/rendering-tools/js-execution) output does not have as much information but it can be exported from Chrome Devtools in the browser. There's also an automated headless tool for doing so: [automated-chrome-profiling](https://github.com/paulirish/automated-chrome-profiling). For creating Node.js Cpu Profiles in Node see [v8-profiler](https://github.com/node-inspector/v8-profiler) or [v8-profiler-next](https://github.com/hyj1991/v8-profiler-next). They can also be generated from Node.js 12 and above using the command-line flag [`--cpu-prof`](https://github.com/nodejs/node/commit/e0e308448240260c207958dfc3dd9245d903af85).\n\nDefault: undefined\n\n### --kernel-tracing-debug\n\nShow output from perf(1) tools.\n\nDefault: false\n\n### --tree-debug\n\nSave the intermediate tree representation of captured trace output to a JSON\nfile.\n\nDefault: false\n\n## Programmatic API\n\n0x can also be required as a Node module and scripted:\n\n```js\nconst zeroEks = require('0x')\nconst path = require('path')\n\nasync function capture () {\n  const opts = {\n    argv: [path.join(__dirname, 'my-app.js'), '--my-flag', '\"value for my flag\"'],\n    workingDir: __dirname\n  }\n  try {\n    const file = await zeroEks(opts)\n    console.log(`flamegraph in ${file}`)\n  } catch (e) {\n    console.error(e)\n  }\n}\n\ncapture()\n\n```\n\nThe Programmatic API is detailed in [docs/api.md](docs/api.md).\n\n## Troubleshooting\n\n### Memory Issues\n\nVery complex applications with lots of stacks may hit memory issues.\n\nThe `--stack-size` flag can be used to set the memory to the maximum 8GB\nin order to work around this when profiling:\n\n```\nnode --stack-size=8024 $(which 0x) my-app.js\n```\n\nThere may still be a problem opening the flamegraph in Chrome. The same work\naround can be used by opening Chrome from the command line (platform dependent)\nand nesting the `--stack-size` flag within the `--js-flags` flag:\n`--js-flags=\"--stack-size 8024\"`.\n\n## Debugging\n\n`DEBUG=0x* 0x my-app.js`\n\n## Alternatives\n\n* \u003chttps://github.com/brendangregg/FlameGraph\u003e (perl)\n* \u003chttps://www.npmjs.com/package/stackvis\u003e (node)\n* \u003chttps://www.npmjs.com/package/d3-flame-graph\u003e (node)\n\n## Acknowledgements\n\nThe original sponsor of this work was [nearForm](http://nearform.com)\n\nThis tool is inspired from various info and code sources\nand would have taken much longer without the following people and\ntheir Open Source/Info Sharing efforts:\n\n* Thorsten Lorenz (\u003chttp://thlorenz.com/\u003e)\n* Dave Pacheco (\u003chttp://dtrace.org/blogs/dap/about/\u003e)\n* Brendan Gregg (\u003chttp://www.brendangregg.com/\u003e)\n* Martin Spier (\u003chttp://martinspier.io/\u003e)\n\n## License\n\nMIT\n","funding_links":[],"categories":["Packages","JavaScript","Repository","包","目录","Test tools","Debugging / Profiling","The Web Backend","Profiling"],"sub_categories":["Debugging / Profiling","Performance Profiling/Analysis","调试 / 分析","调试/分析","Utils","调试"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidmarkclements%2F0x","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidmarkclements%2F0x","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidmarkclements%2F0x/lists"}