黑匣子工具 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.0	3.4.0

部署 Nebula-BBox

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

1. 获取 RPM 安装包。

   Enterpriseonly

   联系我们以获取 Nebula-BBox 的安装包。

2. 使用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 查看指标数据时，可以使用以下快捷键。

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

FAQ

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

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

---

最后更新: July 6, 2023