开发手册

• 1: 采集模式
• 2: 自定义指标
• 3: 自定义事件
• 4: 自定义追踪
• 5: 集成测试

1 - 采集模式

为帮助用户全面深入洞察系统的运行状态，HUATUO 提供三种数据采集: metrics, event, autotracing. 用户可以根据具体场景和需求实现自己的观测数据采集。

模式

指标

• 类型：指标采集。
• 功能：采集内核各子系统指标数据。
• 特点：
  • 通过 Procfs 或 eBPF 方式采集。
  • Prometheus 格式输出，最终集成到 Prometheus/Grafana。
  • 主要采集系统的基础指标，如 CPU 使用率、内存使用率、网络等。
  • 适合用于监控系统运行状态，支持实时分析和长期趋势观察。
• 已集成：
  • CPU sys, usr, util, load, nr_running …
  • Memory vmstat, memory_stat, directreclaim, asyncreclaim …
  • IO d2c, q2c, freeze, flush …
  • Networking arp, socket mem, qdisc, netstat, netdev, socketstat …

事件

• 类型：Linux 内核事件采集。
• 功能：常态运行，事件触发并在达到预设阈值时，获取内核运行上下文。
• 特点：
  • 常态运行，异常事件触发，支持阈值设定。
  • 数据实时存储 ElasticSearch、物理机本地文件。
  • 适合用于常态监控和实时分析，捕获系统更多异常行为观测数据。
• 已集成：
  • 软中断异常 softirq
  • 内存异常分配 oom
  • 软锁定 softlockup
  • D 状态进程 hungtask
  • 内存回收 memreclaim
  • 异常丢包 dropwatch
  • 网络入向延迟 net_rx_latency

自动追踪

• 类型：系统异常追踪
• 功能：自动跟踪系统异常状态，并在异常发生时触发工具抓取现场信息。
• 特点：
  • 系统出现异常时自动触发，捕获。
  • 数据实时存储 ElasticSearch、物理机本地文件。
  • 适用于获取现场时性能开销较大、指标突发的场景。
• 已集成：
  • CPU 异常追踪
  • 进程 D 状态追踪
  • 容器内外争抢
  • 内存突发分配
  • 磁盘异常追踪

2 - 自定义指标

只需实现 Collector 接口并完成注册即可。

type Collector interface {
    Update() ([]*Data, error)
}

创建

在 core/metrics/your-new-metric 目录创建 Collector 接口的结构体：

type exampleMetric struct{}

注册

func init() {
    tracing.RegisterEventTracing("example", newExample)
}

func newExample() (*tracing.EventTracingAttr, error) {
    return &tracing.EventTracingAttr{
        TracingData: &exampleMetric{},
        Flag: tracing.FlagMetric, // 标记为 Metric 类型
    }, nil
}

实现 Update

func (c *exampleMetric) Update() ([]*metric.Data, error) {
    // do something
    return []*metric.Data{
        metric.NewGaugeData("example", value, "description of example", nil),
    }, nil
}

框架提供的丰富底层接口，包括 eBPF, Procfs, Cgroups, Storage, Utils, Pods 等。

3 - 自定义事件

只需实现 ITracingEvent 接口并完成注册即可。

type ITracingEvent interface {
    Start(ctx context.Context) error
}

创建

type exampleTracing struct{}

注册

func init() {
    tracing.RegisterEventTracing("example", newExample)
}

func newExample() (*tracing.EventTracingAttr, error) {
    return &tracing.EventTracingAttr{
        TracingData: &exampleTracing{},
        Internal:    10, // 再次开启 tracing 的间隔时间，单位秒
        Flag:        tracing.FlagTracing, // 标记为 tracing 类型；tracing.FlagMetric（可选）
    }, nil
}

实现 Start

func (t *exampleTracing) Start(ctx context.Context) error {
    // do something
    ...

    // 存储数据到 ES 和 本地
    storage.Save("example", ccontainerID, time.Now(), tracerData)
}

此外，可同时实现接口 Collector 并以 Prometheus 格式输出 （可选）

func (c *exampleTracing) Update() ([]*metric.Data, error) {
    // from tracerData to prometheus.Metric 
    ...

    return data, nil
}

4 - 自定义追踪

AutoTracing 与 Event 类型在框架实现上没有区别，只是针对不同的场景进行应用区分。

type ITracingEvent interface {
    Start(ctx context.Context) error
}

5 - 集成测试

集成测试用于验证 huatuo-bamai在使用模拟的 /proc 和 /sys 文件系统时，能够正确启动并对外暴露符合预期的Prometheus指标。

测试运行的是真实的可执行文件，并通过校验 /metrics 接口的输出结果，确保指标采集与暴露逻辑正确，而不依赖宿主机的内核或硬件环境。

脚本执行流程

该集成测试脚本主要包含以下步骤：

1. 生成临时的bamai.conf配置文件
2. 使用模拟的 procfs 和 sysfs 启动 huatuo-bamai 服务
3. 等待 /metrics 接口可访问
4. 从 /metrics 接口拉取所有指标数据
5. 校验所有预期指标是否存在且内容匹配
6. 停止服务并清理相关资源
7. 若任意一个预期指标缺失或不匹配，测试将直接失败

运行方式

请在项目根目录下执行集成测试：

bash integration/run.sh

或通过 Makefile 执行：

make integration

失败时的行为

• huatuo-bamai 服务指标和日志将直接输出到标准输出，便于问题定位
• 临时工作目录将被保留，用于后续调试分析

成功时的行为

• 显示验证成功的metrics 列表

如何新增指标测试

第一步：新增或更新模拟数据

如果新增的指标依赖 /proc 或 /sys 文件内容，请在以下目录中新增或修改模拟数据：

integration/fixtures/

目录结构需与真实内核文件系统保持一致。

第二步：添加预期指标

在以下目录中新建一个文件：

integration/fixtures/expected_metrics/
├── cpu.txt
├── memory.txt
└── ...

每一行（非空、非注释行）表示一条期望的 Prometheus 指标，指标内容必须与 /metrics 接口返回结果完全一致，新增的*.txt 文件会被测试脚本自动加载并参与校验。

第三步：运行测试

bash integration/run.sh

当任意一个预期指标缺失或不匹配时，测试将失败。