开发手册

• 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 - 自定义指标

概述

Metrics 类型用于采集系统性能等指标数据，可以 Prometheus 格式输出，作为 /metrics（curl localhost:<port>/metrics）的数据提供方。

• 类型：指标采集

• 功能：采集各子系统的性能指标

• 特点：

  • 指标主要用于采集 CPU 使用率、内存使用量、网络统计等系统性能数据，适用于监控系统性能，支持实时分析和长期趋势观察。
  • 指标来源可以是常规 procfs/sysfs 采集，也可以由 tracing 类型（autotracing、event）生成。
  • 以 Prometheus 格式输出，无缝集成 Prometheus 可观测性生态。

• 已集成：

  • CPU（sys、usr、util、load、nr_running…）
  • 内存（vmstat、memory_stat、directreclaim、asyncreclaim…）
  • IO（d2c、q2c、freeze、flush…）
  • 网络（arp、socket mem、qdisc、netstat、netdev、socketstat…）

如何添加统计指标

只需实现 Collector 接口并完成注册即可将指标添加到系统。

type Collector interface {
    // Get new metrics and expose them via prometheus registry.
    Update() ([]*Data, error)
}

1. 创建结构体

在 core/metrics 目录下创建实现 Collector 接口的结构体：

type exampleMetric struct{}

2. 注册回调函数

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

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

3. 实现 Update 方法

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

项目 core/metrics 目录中已集成多种实用的 Metrics 示例，框架还提供了丰富的底层接口，包括 BPF 程序和 map 数据交互、容器信息等。更多详情请参考对应的代码实现。

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 - 自定义追踪

概述

• 类型：异常事件驱动（tracing/autotracing）
• 功能：自动追踪系统异常状态，在异常发生时触发上下文信息捕获
• 特点：
  • 当系统出现异常时，autotracing 自动触发并捕获相关上下文信息
  • 事件数据实时存储到本地，同时发送到远程 ES，还可以生成 Prometheus 指标进行观测
  • 适用于性能开销较大的场景，例如在检测到指标超过阈值或上升过快时触发捕获
• 已集成：CPU 空闲异常追踪（cpu idle）、D 状态追踪（dload）、容器内外部竞争（waitrate）、内存突发分配（memburst）、磁盘异常追踪（iotracer）

如何添加 Autotracing

AutoTracing 只需实现 ITracingEvent 接口并完成注册即可将事件添加到系统。

AutoTracing 与 Event 在框架实现上没有区别，只是根据实际应用场景进行区分。

// ITracingEvent represents a autotracing or event
type ITracingEvent interface {
    Start(ctx context.Context) error
}

1. 创建结构体

type exampleTracing struct{}

2. 注册回调函数

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

func newExample() (*tracing.EventTracingAttr, error) {
    return &tracing.EventTracingAttr{
        TracingData: &exampleTracing{},
        Internal:    10, // 重新触发追踪的间隔（秒）
        Flag:        tracing.FlagTracing, // 标记为 tracing 类型；| tracing.FlagMetric（可选）
    }, nil
}

3. 实现 ITracingEvent

func (t *exampleTracing) Start(ctx context.Context) error {
    // 检测你关注的内容
    ...

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

此外，可以选择实现 Collector 接口以 Prometheus 格式输出：

func (c *exampleTracing) Update() ([]*metric.Data, error) {
    // 将 tracerData 转换为 prometheus.Metric
    ...

    return data, nil
}

项目 core/autotracing 目录中已集成多种实用的 autotracing 示例，框架还提供了丰富的底层接口，包括 BPF 程序和 map 数据交互、容器信息等。更多详情请参考对应的代码实现。

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

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