V2.2.0 on HUATUO 文档中心

快速开始

Wed, 03 Dec 2025 00:00:00 +0000

为帮助大家快速体验、部署 HUATUO, 该文档分别从极速体验，容器启动，编译部署三部分说明。

1. 极速体验

你可以直接登陆示例网站访问前端监控大盘示例，如内核指标、异常事件、火焰图等（账户：huatuo 密码：huatuo1024）。

2. 容器启动

2.1 Docker 启动

通过 docker 启动已经编译好的容器镜像（注意：该方式默认关闭了获取容器信息功能，和 ES 存储功能）。

启动容器：

$ docker run --privileged --cgroupns=host --network=host -v /sys:/sys -v /proc:/proc -v /run:/run huatuo/huatuo-bamai:latest

获取指标：打开另外一个终端，通过 curl 获取。

$ curl -s localhost:19704/metrics

查看异常事件 (Events, AutoTracing)：HUATUO 会将采集到的内核异常事件信息在 ES （已关闭），和本地目录 huatuo-local 分别存储。注意：通常该路径下没有任何文件（正常状态的系统不会触发事件采集），你可以通过构造异常场景或者修改配置文件阈值产生事件。

2.2 Docker Compose 启动

通过 docker compose，可以快速地在本地搭建部署一套完整的环境。该命令拉取最新镜像，启动 elasticsearch, prometheus, grafana，huatuo-bamai 等组件。命令执行成功后，打开浏览器访问 http://localhost:3000 即可浏览监控大盘（grafana 默认管理员账户：admin 密码：admin；系统正常状态不会触发 Events, AutoTracing）。

源码编译

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

1. 容器编译

可以执行如下命令，完成编译，静态代码检查。

$ sh build/build-run-testing-image.sh

或者单独执行：

1. 准备编译环境

$ docker build --network host -t huatuo/huatuo-bamai-dev:latest -f ./Dockerfile.devel .

2. 启动编译容器

$ docker run -it --privileged --cgroupns=host --network=host -v $(pwd):/go/huatuo-bamai huatuo/huatuo-bamai-dev:latest sh

3. 进入容器编译

$ make

2. 物理机编译

2.1 安装依赖

Ubuntu 24.04:

apt install make git clang libbpf-dev linux-tools-common curl

Fedora 40:

dnf install make git clang libbpf-devel bpftool curl

2.2 编译

$ make

3. 镜像发布

通过 docker build 方式能够快速的发布，最新二进制容器镜像。

配置指南

Sun, 29 Mar 2026 00:00:00 +0000

1. 文档概述

huatuo-bamai 作为 HUATUO 的核心采集器（bpf-based metrics and anomaly inspector），其配置文件用于定义数据采集范围、探针启用策略、指标输出格式、异常检测规则、以及日志行为等。

配置文件包含全局黑名单、日志、运行时资源限制、存储配置以及自动追踪（AutoTracing）等多个 section。每个配置项均附带详细注释，明确说明用途、默认值及注意事项。本文档针对配置文件中的每一个配置项提供中文的详细解释，帮助用户准确理解和安全定制配置。

注意：配置文件中多数参数以 # 注释形式提供默认值，实际启用时需移除 # 并根据环境调整。修改后需重启 huatuo-bamai 进程生效。生产环境建议遵循最小化原则，避免过度开启高开销特性。

2. 全局黑名单

# The global blacklist for tracing and metrics
BlackList = ["netdev_hw", "metax_gpu"]

BlackList：全局追踪与指标黑名单。

用于排除特定模块或追踪和指标采集，避免无关噪声或高开销探针。例如 [“netdev_hw”, “metax_gpu”]，即全局禁用网络设备硬件层（netdev_hw）和 Metax GPU 相关的追踪与指标。

说明：添加黑名单项可有效降低资源消耗，尤其在特定硬件环境中；支持数组格式，可根据实际业务扩展。

3. 日志配置

# Log Configuration
#
# - Level
# The log level for huatuo-bamai: Debug, Info, Warn, Error, Panic.
# Default: Info
#
# - File
# Store logs to where the logging file is. If it is empty, don't write log
# to any file.
# Default: empty
#
[Log]
	# Level = "Info"
	# File = ""

Level：日志级别。

集成测试

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

或通过 Makefile 执行：

make integration

失败时的行为

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

成功时的行为

显示验证成功的metrics 列表

如何新增指标测试

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

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

integration/fixtures/

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

第二步：添加预期指标

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

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

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

变更日志

Sun, 29 Mar 2026 00:00:00 +0000