黑匣子工具 NebulaGraph Black Box¶

NebulaGraph Black Box（简称 Nebula-BBox）是一个帮助用户查看和分析黑匣子数据的工具。本文介绍如何在 Linux 系统中使用 Nebula-BBox。

Enterpriseonly

Nebula-BBox 仅在 NebulaGraph 企业版中提供。

Nebula-BBox 的功能¶

Nebula-BBox 提供了以下功能：

通过终端用户界面（Terminal User Interface, TUI）查看黑匣子数据。
将黑匣子数据导出为 CSV 文件。
不同维度查看数据
- 查看一个或多个指标数据。
- 查看某个时间段的数据。
- 查看一个或多个目录/文件的数据，或者同时指定目录和文件查看数据。
支持 Linux、macOS 和 Windows 系统。

版本兼容性¶

NebulaGraph 与 Nebula-BBox 的版本兼容性如下：

NebulaGraph	Nebula-BBox
3.4.3	3.4.0

部署 Nebula-BBox¶

支持多种部署方式，包括 RPM、DEB、TAR、Docker 等。本文以 RPM 部署为例介绍如何部署 Nebula-BBox。

获取 RPM 安装包。

Enterpriseonly

联系我们以获取 Nebula-BBox 的安装包。
使用sudo rpm -i <rpm>命令安装 RPM 包。

例如，sudo rpm -i nebula-bbox-<version>.x86_64.rpm

Nebula-BBox 以二进制文件（文件名为nebula-bbox）的形式安装在默认路径/usr/bin/下。

使用 Nebula-BBox¶

用户可以执行nebula-bbox -h/--help查看 Nebula-BBox 的帮助信息。

Caution

对于安装在非默认路径（默认为/usr/bin/）下的 Nebula-BBox，执行nebula-bbox相关命令时，需指定 Nebula-BBox 的安装路径。例如，Nebula-BBox 安装在/usr/bbox下，则需执行/usr/bbox/nebula-bbox -h。

查看 Nebula-BBox 版本¶

执行nebula-bbox version查看 Nebula-BBox 的版本信息。

查看采集的所有指标¶

执行nebula-bbox metrics命令查看 Nebula-BBox 采集的所有指标。关于指标的详细信息，参见 PROC(5)。

查看黑匣子文件数据¶

通过 Nebula-BBox，用户可以查看黑匣子文件的指标数据。语法如下：

nebula-bbox view [(-o|--output=)tui|csv] [--metrics name[,name ...]] [flags] (FILE | DIRECTORY ...)

参数说明¶

参数	说明
`-o`，`--output`	指定 Nebula-BBox 显示数据的格式。可选值为`tui`和`csv`。未指定时默认值为`tui`。 `tui`：输出格式为终端用户界面（Terminal User Interface, TUI）。 `csv`：输出格式为 CSV 文件。
`--metrics`	指定 Nebula-BBox 输出的指标。可选值为`nebula-bbox metrics`命令输出的指标。未指定时默认值为所有指标。指定多个指标时，用逗号分隔，如`--metrics <name>,<name>...`。
`flags`	可定义其他的参数项： `--output-file`：当`-o`或`--output`值为`csv`时需指定该参数，用于定义 CSV 文件的存储路径及文件名。 `--start-time`：当根据时间段过滤数据时，定义起始时间。 `--end-time`：当根据时间段过滤数据时，定义结束时间，和`--start-time`同时用。 `--duration`：当根据时间段过滤数据时，定义数据采集的时间周期，和`--start-time`同时用。不能和`--end-time`同时使用。

示例¶

以下示例均假设 NebulaGraph 的安装路径为/usr/local/nebula，黑匣子文件的存储路径为/usr/local/nebula/black_box。

Note

指定指标前，需先执行nebula-bbox metrics命令查看 Nebula-BBox 支持的指标。详情参见上文查看采集的所有指标。

场景	示例
查看单个文件的所有指标数据	`nebula-bbox view /usr/local/nebula/black_box/<pid>/black_box.<timestamp>.log`
查看多个文件的所有指标数据	`nebula-bbox view /usr/local/nebula/black_box/<pid>/black_box.<timestamp1>.log /usr/local/nebula/black_box/<pid>/black_box.<timestamp2>.log`
查看所有文件的所有指标数据	`nebula-bbox view /usr/local/nebula/black_box`
查看多个子目录下的所有指标数据	`nebula-bbox view /usr/local/nebula/black_box/<pid1> /usr/local/nebula/black_box/<pid2>`
查看子目录和单个文件的所有指标数据	`nebula-bbox view /usr/local/nebula/black_box/<pid1> /usr/local/nebula/black_box/<pid2> /usr/local/nebula/black_box/<pid3>/black_box.<timestamp>.log`
查看单个文件中指定的指标数据	`nebula-bbox view --metrics <name> /usr/local/nebula/black_box/<pid>/black_box.<timestamp>.log`
在所有文件中查看指定的指标数据	`nebula-bbox view --metrics <name> /usr/local/nebula/black_box`
将所有文件中指定的指标数据导出为 CSV 文件	`nebula-bbox view --metrics <name1>[,<name2> ...] --output csv --output-file <csv_filename>.csv /usr/local/nebula/black_box`
在所有文件中查看多个指定的指标数据	`nebula-bbox view --metrics <name1>[,<name2> ...] /usr/local/nebula/black_box`
查看北京时间 2022 年 9 月 6 日 12：00 起至现在的所有文件数据	`nebula-bbox view --start-time "Tue, 06 Sep 2022 12:00:00 +0800" /usr/local/nebula/black_box` 其中`Tue, 06 Sep 2022 12:00:00 +0800`的格式可替换成`2022-09-06T12:00:00+08:00`、`2022-09-06 04:00:00 +0800`。
查看北京时间 2022 年 9 月 6 日 12：00 起 1 小时内的所有文件数据	`nebula-bbox view --start-time "Tue, 06 Sep 2022 12:00:00 +0800" --duration 1h /usr/local/nebula/black_box`，时间段单位支持`h`、`m`、`s`。
查看北京时间 2022 年 9 月 6 日 12：00 起至 2022 年 9 月 6 日 13：00 内的所有文件数据	`nebula-bbox view --start-time "2022-09-06 04:00:00 +0800" --end-time "2022-09-06 05:00:00 +0800" /usr/local/nebula/black_box`

TUI 界面及快捷键¶

TUI 界面以表格形式显示指标数据。页面首行显示指标采集的时间（Time）、NebulaGraph 服务的进程号（Pid）、服务类型（ServerName）和各指标名称。

TUI_display

当用户使用 TUI 查看指标数据时，可以使用以下快捷键。

快捷键	说明
`F1`	显示帮助。
`Left`	向左移动。
`Right`	向右移动。
`Down`	向下移动。
`Up`	向上移动。
`Ctrl-A`或`Home`	跳转至当前行的首列。
`Ctrl-E`或`End`	跳转至当前行的末尾列。
`Ctrl-T`	跳转至首行。
`Ctrl-B`	跳转至末尾行。
`Enter`	显示选中单元格的详细信息。
`Escape`	退出显示单元格详细信息。

FAQ¶

问：为什么我的 TUI 界面如下显示?

TUI_display_exception

答：遇如上图所示的情况，是因为 Linux 系统字符集不匹配。在命令行中执行export LC_CTYPE="en_US.UTF-8"可解决问题。

最后更新: September 4, 2023