0x 中文文档教程

Question

0x

单命令火焰图分析 ????

使用火焰图发现代码中的瓶颈和热路径。

Visualize Stack Traces

0x 可以使用单个命令为 Node 进程分析和生成交互式火焰图， 在 Node 运行的任何平台上（macOs、Linux、Windows、Android……）。

Support

• Node v12.x and above
• Default usage supports any Operating System that Node runs on!
• Chrome
• Other browsers may open flamegraphs in a degraded, but functional form

Demo

可以在 http://davidmarkclements.github.io/0x-demo/ 查看示例交互式火焰图。

Install

npm install -g 0x

Usage

使用 0x 运行脚本：

0x my-app.js

立即在浏览器中打开火焰图：

0x -o my-app.js

自动对第一个执行分析命令 分析进程打开的端口：

0x -P 'autocannon localhost:$PORT' my-app.js

使用自定义节点可执行文件：将

0x -- /path/to/node my-app.js

自定义参数传递给节点：

0x -- node --zero-fill-buffers my-app.js

Generating

准备好生成火焰图时，发送 SIGINT 或 SIGTERM。

执行此操作的最简单方法是按 CTRL+C。

当 0x 捕获 SIGINT 或 SIGTERM 时，它会处理堆栈并 生成一个配置文件文件夹 (.0x)，其中包含 flamegraph.html。

The UI

flamegraph.html 文件包含 0x UI，这在 文档/ui.md。

Production Servers

一种轻量级、生产服务器友好的方法来生成 docs/production-servers.md 中描述了火焰图。

The Profile Folder

默认情况下，将创建一个配置文件文件夹并以 PID 命名，例如 3866.0x（我们可以使用 --output-dir 标志手动设置此名称）。

配置文件夹在 docs/profile-folder.md 中有更详细的解释

Example

克隆这个 repo，运行 npm i -g并从 repo root run

0x examples/rest-api

在另一个选项卡中运行

npm run stress-rest-example

完成后给其余服务器增加一些负载 使用 ctrl + c 杀死服务器。

Command Line API

--help | -h

打印使用信息。

--open | -o

使用 open 或 xdg-open 在浏览器中打开火焰图（参见 https://www.npmjs.com/package/open 了解详情）。

--on-port | -P

运行给定的命令，然后生成火焰图。 指定的命令可以访问 $PORT 变量。 $PORT 变量根据第一个端口设置 异形过程打开。

例如，这里有一个使用 autocannon 的例子 对过程进行负载测试：

0x -P 'autocannon localhost:$PORT' app.js

当负载测试完成时，分析处理将是 发送 SIGINT，火焰图将自动生成。

请记住使用单引号以避免 bash 插值， 或者转义变量（例如 0x -P "autocannon localhost:$PORT" app.js 不会工作 wheras 0x -P "autocannon localhost:\$PORT" app.js 会）。

注意：在 Windows 上，插值通常发生在 %PORT% 中，但是 在这种情况下，美元前缀 $PORT 是正确的语法 （因为插值不是基于外壳的）。

默认值：''

--name

HTML 文件的名称，不带 .html 扩展名 可以设置为 - 将 HTML 写入 STDOUT（注意 由于 CLI 参数解析的性质，必须使用 = 进行设置， 例如 --name=-)。

如果此标志或 --output-html-file 设置为 - 然后 HTML 将转到 STDOUT。

默认值：flamegraph

---title

设置要在火焰图 UI 中显示的标题。

默认值：0x 运行的启动进程的命令

--output-dir | -D

指定工件输出目录。 这可以在模板中指定 可能的变量为 {pid}、{timestamp}、{name} （基于 --name 标志）和 {outputDir}（变量 必须在没有空格的情况下指定，例如 { pid } 不受支持）。

默认值：{pid}.0x

--output-html | -F

指定生成的火焰图 HTML 文件的目的地。 这可以用可能的变量以模板形式指定 为 {pid}、{timestamp}、{name}（基于 --name 标志）和 {outputDir}（变量必须没有空格指定， 例如 { pid } 不受支持）。 也可以设置为-来 将 HTML 输出发送到 STDOUT（注意 由于 CLI 参数解析的性质，必须使用 = 进行设置， 例如 --output-html=-)。

如果此标志或 --name 设置为 - 然后 HTML 将转到 STDOUT。

默认值：{outputDir}/{name}.html

--kernel-tracing

使用操作系统内核跟踪工具（Linux 上的 perf）。 这将捕获 本机堆栈帧（C++ 模块和 Libuv I/O）， 但可能会由于优化编译器而导致 Node.js 中缺少堆栈。

有关详细信息，请参阅 docs/kernel-tracing.md。

默认值：false

--quiet | -q

限制输出，唯一的输出将是致命错误或 成功生成后到 flamegraph.html 的路径。

默认值：false

--silent | -s

抑制所有输出，致命错误除外。

默认值：false

--collect-only

不生成火焰图，只创建配置文件文件夹， 与相关输出。

默认值：false

--collect-delay

将堆栈的收集延迟相对于第一个条目的指定时间（毫秒）。

默认值：0

--visualize-only

提供配置文件文件夹的路径以构建或重建可视化 从原始堆栈。

默认值：undefined

--visualize-cpu-profile

提供 CPU 配置文件的路径。 有关示例，请参见 examples/cpu-profile。

CPU Profile 输出没有那么多信息，但可以导出从浏览器中的 Chrome Devtools。 还有一个自动化的无头工具可以执行此操作：automated-chrome-profiling。 要在 Node 中创建 Node.js Cpu 配置文件，请参阅 v8-profiler 或 v8-profiler-next。

默认值：undefined

--kernel-tracing-debug

显示 perf(1) 工具的输出。

默认值：false

--tree-debug

将捕获的跟踪输出的中间树表示形式保存到 JSON 文件。

默认值：false

Programmatic API

0x 也可能需要作为 Node 模块并编写脚本：

const zeroEks = require('0x')
const path = require('path')

async function capture () {
  const opts = {
    argv: [path.join(__dirname, 'my-app.js'), '--my-flag', '"value for my flag"'],
    workingDir: __dirname
  }
  try {
    const file = await zeroEks(opts)
    console.log(`flamegraph in ${file}`)
  } catch (e) {
    console.error(e)
  }
}

capture()

编程 API 在 docs/api.md 中有详细说明。

Troubleshooting

Memory Issues

具有大量堆栈的非常复杂的应用程序可能会遇到内存问题。

--stack-size 标志可用于将内存设置为最大 8GB 为了在分析时解决这个问题：

node --stack-size=8024 $(which 0x) my-app.js

在 Chrome 中打开火焰图可能仍然存在问题。 一样的工作 around 可以通过从命令行打开 Chrome 来使用（取决于平台） 并将 --stack-size 标志嵌套在 --js-flags 标志中： <代码>--js-flags="--堆栈大小 8024"。

Debugging

DEBUG=0x* 0x my-app.js

Alternatives

• https://github.com/brendangregg/FlameGraph (perl)
• https://www.npmjs.com/package/stackvis (node)
• https://www.npmjs.com/package/d3-flame-graph (node)

Acknowledgements

由 nearForm 赞助

此工具的灵感来自各种信息和代码源 如果没有以下人员，将会花费更长的时间 他们的开源/信息共享工作：

• Thorsten Lorenz (http://thlorenz.com/)
• Dave Pacheco (http://dtrace.org/blogs/dap/about/)
• Brendan Gregg (http://www.brendangregg.com/)
• Martin Spier (http://martinspier.io/)

License

麻省理工学院