# easy-exporter

**Repository Path**: yunsilicon/easy-exporter

## Basic Information

- **Project Name**: easy-exporter
- **Description**: 支持云脉芯联全系列网卡的监控exporter，可对接Prometheus，支持秒级采集。
- **Primary Language**: C
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-11-18
- **Last Updated**: 2026-02-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Easy-Exporter

# 介绍
Easy-Exporter可以以极低的系统资源开销实现最高秒级的监控数据采集，可用于采集云脉芯联或Nvidia网卡的网络监控统计信息，包括以太类（例如各个优先级的发送、接收字节数、报文数等）和RDMA类（例如丢包、乱序、QP个数等）等的统计数据，并支持将数据输出到Prometheus系统，可灵活指定采集项列表、数据更新周期，并可以捕获采集对象的动态变化（例如由于卸载、安装驱动引起的设备删除和创建）。

# 软件架构

## 目录结构说明
1. config：配置文件目录
   - easy-exporter.ini：配置文件，指定监听端口，计数器白名单等，各配置子项定义如后文描述；
   - easy-exporter_logrotate：logrotate配置文件，配合Linux的logrotate服务，用于自动定期归档、删除log文件；
   - easy-exporter.service：服务描述文件，本Exporter在Linux系统下是以后台服务进程形态运行的。
2. deb：将代码编译打包成deb安装包的必要配置描述文件。
3. grafana_config：Granfana前端配置文件，包括数据列表和展示面板的配置。
4. k8s：
   - make_yaml.sh：生成K8S交付件的脚本。
5. project：工程目录，包括代码和编译脚本等。
   - build.sh：编译脚本。
   - src：源代码目录。
     - app：主要逻辑代码。
     - include：内部共用头文件。
     - lib：内部共用数据结构和接口。
   - third_party：第三方源代码。
6. rpm：将代码编译打包成rpm安装包的必要配置描述文件。
7. version.ini：版本号描述。

## 主要模块及关系

Object：所有的采集对象，例如以太设备eth0、ens1，以及IB设备xscale_0、mlx5_0等，都被抽象为object。由于本项目支持采集对象的动态变化，因此会对object进行周期性扫描，以及时发现object的销毁和创建。

Probe：即采集器，由一组回调函数组成，可在其关注的object创建、销毁时做出相应动作。同一个object可能存在多个probe（例如以太设备同时被采集收发报文的信息和温度信息，IB设备也会同时被采集RDMA的数据和QP个数信息）。可以认为object是被采集的对象，其产生的多种各类数据被对应的probe收集。

<img src="./assets/1.png" alt="image-1" width="50%" />

Object与Probe的关系如上图所示，系统中同时存在多个object与probe，当probe作用在object上时，产生实例instance，监控数据来自instance。

多线程：收集数据和上报数据都是比较耗时的过程，尤其是当数据需要上报给Prometheus系统时，因此本项目采用多线程模型设计。Easy-Exporter内部有两个线程：收集线程和上报线程。收集线程用于定期收集数据，并将数据以特定的个数写在一个buffer中，上报线程负责监听和接收Prometheus的pull请求，当需要向Prometheus上报数据时，上报线程从buffer中取出数据，对数据做快速压缩后发送给Prometheus。压缩过程需要持有数据buffer的锁，在压缩结束前buffer是不能被用来写入收集数据的。因此此处存在短暂的数据竞争，但经过我们长时间测试，认为并没有对采集的实时性造成影响。

<img src="./assets/2.png" alt="image-2" width="50%" />

## 配置文件说明

配置文件位于目录config/easy-exporter.ini，使用ini格式组织，文件中包含多个section（main、ys和mlx），每个section下包含多个key。所有key的作用如下表：

| **段名** |          **键名**           |                           **说明**                           |
| :------: | :-------------------------: | :----------------------------------------------------------: |
|   main   |         report_diff         |   是否上报差值，配置为1时计算差值并上报，为0时上报原始值。   |
|   main   |         scan_period         | 监视对象扫描周期，单位为秒。用于实时发现支持动态创建、删除的采集对象。 |
|   main   |        update_period        |               采集数据的间隔时间，以秒为单位。               |
|   main   |         output_mode         | 配置为0时，将数据打印在屏幕终端上；配置为1时，通过socket被Prometheus采集。 |
|   main   |   prometheus_listen_port    |          Prometheus采集数据的监听端口号，用于IPv4.           |
|   main   | prometheus_listen_port_ipv6 |          Prometheus采集数据的监听端口号，用于IPv6.           |
|   main   | prometheus_compress_output  | 配置为‘Y’时，监控数据压缩后再上报给被Prometheus，配置为‘N’时不压缩。 |
|   main   |  prometheus_listen_on_ipv6  |     配置为‘Y’时开启IPv6监听，配置为‘N’时不开启IPv6监听。     |
|    ys    |        eth_cntr_list        |     在**Yunsilicon**网卡上需要采集的ethtool监控项列表。      |
|    ys    |        ib_cntr_list         | 在**Yunsilicon**网卡上需要采集的infiniband设备监控项列表，来自文件：/sys/class/infiniband/xxx/counters/counters。 |
|    ys    |     ib_global_cntr_list     | 在**Yunsilicon**网卡上需要采集的网卡级全局监控项列表，来自文件：/sys/class/infiniband/xxx/global_counters/counters。 |
|   mlx    |        eth_cntr_list        | 在**Nvidia**网卡上需要采集的ethtool监控项列表，来自ethtool -S xxx。 |
|   mlx    |        ib_cntr_list         | 在**Nvidia**网卡上需要采集的infiniband设备监控项列表，来自目录：/sys/class/infiniband/mlx5_0/ports/1/counters/。 |
|   mlx    |       ib_hw_cntr_list       | 在**Nvidia**网卡上需要采集的infiniband设备硬件监控项列表，来自目录：/sys/class/infiniband/xxx/ports/1/hw_counters/。 |

## 使用说明

### 编译依赖

```
$sudo apt install cmake build-essential
```

cmake需要**2.8**或更高版本。

### 编译

切换到project目录下，执行build.sh脚本开始编译：

```
$ cd project
$ ./build.sh
```

编译将很快完成，生成的文件位于project/build/output目录下。

### 打包

在工程根目录下执行pack.sh以进行打包操作，打包后将生成rpm文件（用于redhat系列Linux发行版）和deb文件（用于debian系列Linux发行版）。

### 安装

成功打包后生成rpm文件或deb包，使用对应的包管理程序进行安装：

rpm包安装：

```
$ sudo yum install easy-exporter_1.0-1_x86-64.rpm
```

deb包安装：

```
$ sudo dpkg -i easy-exporter_1.0-1_amd64.deb
```

### 运行时文件

软件被安装后，将自动创建一些文件，各文件的用途说明见下表：

| 说明                                          | 文件路径          |
| --------------------------------------------- | ----------------- |
| /bin/easy-exporter                            | 主可执行文件      |
| /etc/easy-exporter.ini                        | 配置文件          |
| /etc/logrotate.d/easy-exporter_logrotate      | logrotate配置文件 |
| /usr/lib/systemd/system/easy-exporter.service | 系统服务描述文件  |
| /var/log/easy-exporter.log*                   | 运行时log文件     |
| /var/run/easy-exporter.pid                    | 保存主进程PID     |

结束。