开发手册 on HUATUO 文档中心

采集模式

Sun, 11 Jan 2026 00:00:00 +0000

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

模式

模式	类型	触发条件	数据存储	适用场景
Metrics	指标数据	Pull 采集	Prometheus	系统性能指标
Event	异常事件	内核事件触发	ES + 本地存储，Prometheus（可选）	常态运行，事件触发，获取内核运行上下文
Autotracing	系统异常	系统异常触发	ES + 本地存储，Prometheus（可选）	系统异常触发，获取例如火焰图数据

指标

类型：指标采集。
功能：采集内核各子系统指标数据。
特点：
- 通过 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 状态追踪
- 容器内外争抢
- 内存突发分配
- 磁盘异常追踪

自定义指标

Sun, 11 Jan 2026 00:00:00 +0000

只需实现 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 等。

自定义事件

Sun, 11 Jan 2026 00:00:00 +0000

只需实现 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
}

自定义追踪

Sun, 11 Jan 2026 00:00:00 +0000

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

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

开发手册 on HUATUO 文档中心

采集模式

模式

指标

事件

自动追踪

自定义指标

创建

注册

实现 Update

自定义事件

创建

注册

实现 Start

自定义追踪

实现 `Update`

实现 `Start`