DOCA Ngauge

本文档提供有关 ngauge 工具用法的说明。

ngauge 工具用于分析、可视化和调试单节点上的网络性能。该工具旨在探测 NIC 硬件计数器，并将收集的数据与相关元数据一起以 HDF5 格式存储，以便后续处理。此外，该工具还在 CLI 上直接提供图形化的进度更新和测量摘要，从而实时洞察测量过程。

• BlueField-3 或 ConnectX-7 及更高版本，固件版本为 xx.43.1000 或更高

• 主机上安装了 fwctl 驱动程序

  操作系统	命令
  基于 Deb 的 1	搜索软件包 复制 已复制！ apt-cache search fwctl 安装软件包 复制 已复制！ sudo apt install <package-name>
  基于 RPM	搜索软件包 复制 已复制！ dnf search fwctl 安装软件包 复制 已复制！ sudo dnf install <package-name>

  1. 在 Ubuntu 20.04 上，fwctl 驱动程序在系统启动时不会自动加载。要加载它，请在每次重启后运行命令 modprobe mlx5_fwctl。    

安装 Ngauge

通过运行 sudo apt-get install ngauge 或 sudo dnf install ngauge（在 x86 或 Arm 64 主机上）安装 ngauge。对于 DPU，软件包名称为 ngauge-dpu。

ngauge 的所有配置都在输入 YAML 文件中定义。

1. 从 /usr/share/doc/ngauge/examples/settings 复制示例配置文件。

2. 使用设备的 PCIe 地址指定要运行的设备。例如

   复制

   已复制！

               
   
               
   device: "0000:03:00.0"
           

3. 配置输出路径和文件前缀（两者都是必需的）

   复制

   已复制！

               
   
               
   output:
     path: /path/to/output/directory
     prefix: "ngauge_data_"
     silent: false
           

   • 输出文件以格式 /path/to/output/directory/ngauge_data_<DATE>_<TIME>.h5 保存。

   • 每次运行后都会打印确切的文件名。

   • 如果将 silent 选项设置为 true，则命令行上的进度指示将被抑制（默认值：false）。

4. 配置应用程序运行时行为的参数

   复制

   已复制！

               
   
               
   params:
     mode: repetitive  # [repetitive, single]
     period_us: 1e2    # Sampling period in microseconds (e.g., "1e2" = 100 μs)
           

   信息

   接受十进制或科学计数法表示的数字。在示例中，1e2 表示 100 微秒。

5. 定义要测量的计数器。id（数据 ID）是唯一必填字段。其他字段是可选的

   复制

   已复制！

               
   
               
   counters:
     - id: 0x1020000100000000  # Data ID (mandatory)
       desc: RX bytes port 0   # Description (optional)
       unit: RX port           # Unit type (optional)
       accumulating: false     # Whether the counter accumulates values (optional)
       normalizer: time        # Normalizer ('time' or a number, optional)
           

   信息

   所有支持的性能计数器都可以在“支持的数据 ID”部分下找到。

解析输出

一个名为 simple-plot 的示例插件已提供并安装在 /usr/share/doc/ngauge/examples/plugins 下。

此插件演示了如何打开 ngauge 生成的输出 HDF5 文件并绘制数据。虽然它侧重于绘图，但数据也可以用于各种类型的分析。此插件是一个基本演示，不适用于高级用途。

要绘制 ngauge 输出文件中的数据，请使用以下命令

            

            
/usr/share/doc/ngauge/examples/plugins/simple_plot.py <ngauge output .h5 file> <counter ID> [<counter ID> ...]
        

简单绘图示例

另一个插件 simple_text_plot.py 在终端中生成基于文本的绘图。虽然分辨率较低，但当图形输出不可用或到服务器的网络连接速度较慢时，此方法非常有用。

使用语法与图形绘图插件相同

            

            
/usr/share/doc/ngauge/examples/plugins/simple_text_plot.py <ngauge output .h5 file> <counter ID> [<counter ID> ...]
        

简单文本绘图示例

            

            
                                                RX bytes port 0                                    
             ┌─────────────────────────────────────────────────────────────────────────────────────┐
24864860578.2┤                                   ▗▐██▄▄▙▙▙█▄▙▄▄██▄▟██▄▟█▟▙▄█▟▄▙█▄▙▄▄▟▄▄█▟▄▄▄▟▙▄▄▟▟▙│
             │                                   ▐█▛                                               │
             │                                   ▐█                                                │
             │                                   ▝                                                 │
20720717148.5┤                                                                                     │
             │                                                                                     │
             │                                                                                     │
             │                                                                                     │
16576573718.8┤                                   ▝                                                 │
             │                                                                                     │
             │                                                                                     │
             │                                                                                     │
12432430289.1┤                                   ▝                                                 │
             │                                                                                     │
             │                                   ▝                                                 │
             │                                                                                     │
 8288286859.4┤                                                                                     │
             │                                                                                     │
             │                                                                                     │
             │                                   ▝                                                 │
 4144143429.7┤                                                                                     │
             │                                                                                     │
             │                                                                                     │
             │                                   ▗                                                 │
          0.0┤▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▟                                                 │
             └┬────────────────────┬────────────────────┬────────────────────┬────────────────────┬┘
             0.0                  4.2                  8.4                 12.6                16.8 
                                                Approx. time (s)
        

要运行 ngauge

            

            
ngauge <configuration YAML file>
        

输出以 HDF5 文件 (.h5) 形式保存在配置 YAML 中指定的路径中。

在运行期间，将显示每个计数器的进度条。这些条形图提供有关计数器活动的视觉反馈，并使用颜色编码来指示值级别

• 蓝色 – 表示相对于同一计数器的其他值而言较低的值

• 红色 – 表示相对于同一计数器的其他值而言较高的值

• 中间颜色（渐变）– 介于低值和高值之间的值，从蓝色过渡到红色

• 实心灰色条 – 表示运行期间此计数器的值没有变化

这种可视化表示有助于实时跟踪计数器活动，从而立即洞察系统行为。