开发手册 on HUATUO 文档中心

扩展观测能力

Sat, 18 Jul 2026 00:00:00 +0000

HUATUO 支持 Metrics、Event 和 AutoTracing 三种观测扩展。三者共享注册机制，但触发方式、运行开销和数据输出不同。

类型	触发方式	数据输出	适用场景
Metrics	周期采集	Prometheus	持续观测系统性能和长期趋势
Event	内核事件或阈值触发	ES、本地文件，可选 Prometheus	常态运行并捕获异常现场
AutoTracing	系统异常触发	ES、本地文件，可选 Prometheus	按需执行开销较高的上下文采集

模式说明

Metrics

Metrics 通过 procfs、sysfs 或 eBPF 周期采集系统状态，以 Prometheus 格式输出，适合实时监控和长期趋势分析。内置采集能力包括：

CPU：sys、usr、util、load、nr_running 等。
内存：vmstat、memory_stat、directreclaim、asyncreclaim 等。
IO：d2c、q2c、freeze、flush 等。
网络：ARP、socket memory、qdisc、netstat、netdev、sockstat 等。

Event

Event 常态监听内核事件或阈值条件，在异常发生时保存内核运行上下文。该模式面向需要持续开启的低开销观测，数据写入 Elasticsearch 和本地文件，也可以同步生成 Prometheus 指标。内置事件包括：

软中断异常 softirq_tracing。
内存异常分配 oom。
软锁定 softlockup。
D 状态进程 hungtask。
内存回收 memory_reclaim_events。
异常丢包 dropwatch。
网络接收延迟 net_rx_latency。

AutoTracing

AutoTracing 在检测到系统异常后自动调用诊断工具，采集火焰图或上下文快照等现场信息。它适合采集成本较高、无法持续运行的诊断数据。结果写入 Elasticsearch 和本地文件，也可以转换为 Prometheus 指标。内置能力包括：

开发调试

Sat, 18 Jul 2026 00:00:00 +0000

全组件联调

开发 Compose 使用当前工作区源码构建开发镜像，并启动采集器、API Server、 Elasticsearch、Prometheus 和 Grafana。采集器需要访问宿主机内核和 cgroup，因此应在 Linux 主机的项目根目录使用 root 权限运行：

sudo make compose-dev-up

Compose 在前台聚合所有组件日志。修改源码后，按 Ctrl+C 停止环境并重新执行命令；Docker 会复用工具链和 Go 编译缓存。

调试结束后删除容器、数据卷和开发镜像：

sudo make compose-dev-down

该命令会删除 Elasticsearch 数据卷。需要保留联调数据时，不要执行该命令。

BPF 调试

BPF 代码可以使用 bpf_dbg() 和 bpf_dbg_msg() 宏在内核态输出调试信息。宏定义位于 bpf/include/bpf_dbg.h。调试功能包含编译时和运行时两级开关，默认完全关闭。

添加调试埋点

每个使用调试宏的 BPF 源文件都需要声明独立的调试 map：

#include "bpf_dbg.h"

BPF_DBG_MAP(native_cpu);

SEC("perf_event")
int prog(void *ctx)
{
        bpf_dbg_msg(ctx, native_cpu, "enter prog");
        bpf_dbg(ctx, native_cpu, "pid and addr", pid, addr, 0);
        return 0;
}

bpf_dbg_msg() 只输出消息；bpf_dbg() 还可以携带最多三个 u64 参数。

集成测试

Wed, 04 Mar 2026 00:00:00 +0000

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

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

脚本执行流程

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

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

运行方式

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

bash integration/run.sh

指定文件名可以只运行一个集成测试，第二个参数指定循环次数，默认为 1：

bash integration/run.sh test_metrics_exclude_filter.sh 10

或通过 Makefile 执行：

make integration

失败时的行为

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

成功时的行为

显示验证成功的metrics 列表

如何新增指标测试

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

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

integration/fixtures/

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

BPF ABI 指南

Wed, 04 Mar 2026 00:00:00 +0000

BPF 侧 C 结构体是 perf event ABI 的唯一来源。Go 类型由 BPF 对象中的 BTF 自动生成，禁止手工维护同构结构体。

约定

一个 ABI 域对应一个 C 头文件和一个 Go 生成文件：

项目	约定
域名	`<domain>`
C 头文件	`bpf/include/abi/<domain>_types.h`
C 结构体前缀	`<domain>_`
Go 生成文件	`internal/bpf/abi/<domain>_types_generated.go`

<domain> 必须以小写字母开头，只能包含小写字母、数字和下划线。避免使用前缀重叠的域，例如 net 和 net_rx。

实现

以下示例创建 sample 域。

1. 定义 ABI 头文件

新建 bpf/include/abi/sample_types.h：

// Copyright 2026 The HuaTuo Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#ifndef __BPF_ABI_SAMPLE_H__
#define __BPF_ABI_SAMPLE_H__

#include "bpf_abi.h"

#define SAMPLE_DATA_LEN 4

struct sample_detail {
	u32 code;
	u8 data[SAMPLE_DATA_LEN];
};

struct sample_event {
	u64 timestamp;
	struct sample_detail detail;
	u32 pid;
	u8 kind;
	u8 pad[3];
};

BPF_ABI_EXPORT(sample_detail);
BPF_ABI_EXPORT(sample_event);

#endif /* __BPF_ABI_SAMPLE_H__ */

要求：

时间格式约定

Wed, 22 Jul 2026 00:00:00 +0000

时间格式约定

HUATUO 统一以 UTC 和固定九位纳秒精度序列化时间戳：

2006-01-02T15:04:05.000000000Z

例如，2026 年 7 月 22 日 00:30:00.123456789 的事件会写为：

2026-07-22T00:30:00.123456789Z

为什么使用固定 UTC 精度

所有主机都使用 Z 时区，分布式查询无需处理不同的本地时区。
九位小数使字符串宽度固定，因此字典序与时间序一致，便于日志文件和关键字索引存储排序。
纳秒精度能够保留 Go time.Time 与事件追踪流水线提供的时间信息。

集成建议

向 HUATUO 写入数据时，请使用统一辅助函数：

timestamp := timeutil.FormatUTC(time.Now())

读取时间戳时使用 timeutil.Parse。它既支持统一格式，也支持包含 0 到 9 位小数的 RFC 3339 旧数据；返回值始终会规范化为 UTC。

只有在两侧均由 FormatUTC 生成字符串时，才应直接按字符串比较时间。第三方 RFC 3339 值可能使用可变小数精度或非 UTC 偏移。