HUATUO 文档中心

Docker 容器部署

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

镜像下载

镜像存储地址: https://hub.docker.com/r/huatuo/huatuo-bamai/tags。

docker 启动容器

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

⚠️：该方式使用容器内的默认配置文件，容器内的默认配置不会连接 kubelet 和 ES。

docker compose 启动容器

通过docker compose 方式，可以在本地快速搭建部署一套完整的环境自行管理采集器、ES、prometheus、grafana 等组件。

docker compose --project-directory ./build/docker up

安装docker compose 参考 https://docs.docker.com/compose/install/linux/

Docker 容器部署

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

镜像下载

镜像存储地址: https://hub.docker.com/r/huatuo/huatuo-bamai/tags。

docker 启动容器

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

⚠️：该方式使用容器内的默认配置文件，容器内的默认配置不会连接 kubelet 和 ES。

docker compose 启动容器

通过docker compose 方式，可以在本地快速搭建部署一套完整的环境自行管理采集器、ES、prometheus、grafana 等组件。

docker compose --project-directory ./build/docker up

安装docker compose 参考 https://docs.docker.com/compose/install/linux/

采集模式

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

为帮助用户全面深入洞察系统的运行状态，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

当前版本支持的指标:

CPU 系统

调度延迟

如下指标可以观测进程调度延迟状态，即一个进程从变得可运行的时刻（即被放进运行队列），到它真正开始在 CPU 上执行的这段时间。

# HELP huatuo_bamai_runqlat_container_latency cpu run queue latency for the containers
# TYPE huatuo_bamai_runqlat_container_latency gauge
huatuo_bamai_runqlat_container_latency{container_host="coredns-855c4dd65d-8v5kg",container_hostnamespace="kube-system",container_level="burstable",container_name="coredns",container_type="normal",host="hostname",region="dev",zone="0"} 226
huatuo_bamai_runqlat_container_latency{container_host="coredns-855c4dd65d-8v5kg",container_hostnamespace="kube-system",container_level="burstable",container_name="coredns",container_type="normal",host="hostname",region="dev",zone="1"} 0
huatuo_bamai_runqlat_container_latency{container_host="coredns-855c4dd65d-8v5kg",container_hostnamespace="kube-system",container_level="burstable",container_name="coredns",container_type="normal",host="hostname",region="dev",zone="2"} 0
huatuo_bamai_runqlat_container_latency{container_host="coredns-855c4dd65d-8v5kg",container_hostnamespace="kube-system",container_level="burstable",container_name="coredns",container_type="normal",host="hostname",region="dev",zone="3"} 0

# HELP huatuo_bamai_runqlat_latency cpu run queue latency for the host
# TYPE huatuo_bamai_runqlat_latency gauge
huatuo_bamai_runqlat_latency{host="hostname",region="dev",zone="0"} 35100
huatuo_bamai_runqlat_latency{host="hostname",region="dev",zone="1"} 0
huatuo_bamai_runqlat_latency{host="hostname",region="dev",zone="2"} 0
huatuo_bamai_runqlat_latency{host="hostname",region="dev",zone="3"} 0

指标	意义	单位	对象	取值	标签
runqlat_container_latency	进程调度延迟计数： zone0, 0~10ms zone1, 10-20ms zone2, 20-50ms zone3, 50+ms	计数	容器	eBPF	container_host, container_hostnamespace, container_level, container_name, container_type, host, region, zone
runqlat_latency	进程调度延迟计数： zone0, 0~10ms zone1, 10-20ms zone2, 20-50ms zone3, 50+ms	计数	物理机	eBPF	host, region, zone

中断延迟

系统中各类软中断在不同CPU上的响应延迟指标（当前只采集了 NET_RX/NET_TX）。

指标说明

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

当前版本支持的指标:

CPU 系统

调度延迟

如下指标可以观测进程调度延迟状态，即一个进程从变得可运行的时刻（即被放进运行队列），到它真正开始在 CPU 上执行的这段时间。

# HELP huatuo_bamai_runqlat_container_latency cpu run queue latency for the containers
# TYPE huatuo_bamai_runqlat_container_latency gauge
huatuo_bamai_runqlat_container_latency{container_host="coredns-855c4dd65d-8v5kg",container_hostnamespace="kube-system",container_level="burstable",container_name="coredns",container_type="normal",host="hostname",region="dev",zone="0"} 226
huatuo_bamai_runqlat_container_latency{container_host="coredns-855c4dd65d-8v5kg",container_hostnamespace="kube-system",container_level="burstable",container_name="coredns",container_type="normal",host="hostname",region="dev",zone="1"} 0
huatuo_bamai_runqlat_container_latency{container_host="coredns-855c4dd65d-8v5kg",container_hostnamespace="kube-system",container_level="burstable",container_name="coredns",container_type="normal",host="hostname",region="dev",zone="2"} 0
huatuo_bamai_runqlat_container_latency{container_host="coredns-855c4dd65d-8v5kg",container_hostnamespace="kube-system",container_level="burstable",container_name="coredns",container_type="normal",host="hostname",region="dev",zone="3"} 0

# HELP huatuo_bamai_runqlat_latency cpu run queue latency for the host
# TYPE huatuo_bamai_runqlat_latency gauge
huatuo_bamai_runqlat_latency{host="hostname",region="dev",zone="0"} 35100
huatuo_bamai_runqlat_latency{host="hostname",region="dev",zone="1"} 0
huatuo_bamai_runqlat_latency{host="hostname",region="dev",zone="2"} 0
huatuo_bamai_runqlat_latency{host="hostname",region="dev",zone="3"} 0

指标	意义	单位	对象	取值	标签
runqlat_container_latency	进程调度延迟计数： zone0, 0~10ms zone1, 10-20ms zone2, 20-50ms zone3, 50+ms	计数	容器	eBPF	container_host, container_hostnamespace, container_level, container_name, container_type, host, region, zone
runqlat_latency	进程调度延迟计数： zone0, 0~10ms zone1, 10-20ms zone2, 20-50ms zone3, 50+ms	计数	物理机	eBPF	host, region, zone

中断延迟

系统中各类软中断在不同CPU上的响应延迟指标（当前只采集了 NET_RX/NET_TX）。

快速开始

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）。

快速开始

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 启动

K8s Daemonset 部署

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

通过 K8s daemonset 方式在云原生集群部署。

1. 获取配置文件

curl -L -o huatuo-bamai.conf https://github.com/ccfos/huatuo/raw/main/huatuo-bamai.conf

根据实际环境修改配置，如kubelet 和 elasticsrearch 的相关配置。

2. 创建 configmap

kubectl create configmap huatuo-bamai-config --from-file=./huatuo-bamai.conf

3. 部署采集器

kubectl apply -f https://github.com/ccfos/huatuo/blob/main/build/huatuo-daemonset.minimal.yaml

huatuo-daemonset.minimal.yaml：

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: huatuo
  namespace: default
  labels:
    app: huatuo
spec:
  selector:
    matchLabels:
      app: huatuo
  template:
    metadata:
      labels:
        app: huatuo
    spec:
      containers:
      - name: huatuo
        image: docker.io/huatuo/huatuo-bamai:latest
        resources:
          limits:
            cpu: '1'
            memory: 2Gi
          requests:
            cpu: 500m
            memory: 512Mi
        securityContext:
          privileged: true
        volumeMounts:
        - name: proc
          mountPath: /proc
        - name: sys
          mountPath: /sys
        - name: run
          mountPath: /run
        - name: var
          mountPath: /var
        - name: etc
          mountPath: /etc
        - name: huatuo-local
          mountPath: /home/huatuo-bamai/huatuo-local
        - name: huatuo-bamai-config-volume
          mountPath: /home/huatuo-bamai/conf/huatuo-bamai.conf
          subPath: huatuo-bamai.conf
      volumes:
      - name: proc
        hostPath:
          path: /proc
      - name: sys
        hostPath:
          path: /sys
      - name: run
        hostPath:
          path: /run
      - name: var
        hostPath:
          path: /var
      - name: etc
        hostPath:
          path: /etc
      - name: huatuo-local
        hostPath:
          path: /var/log/huatuo/huatuo-local
          type: DirectoryOrCreate
      - name: huatuo-bamai-config-volume
        configMap:
          name: huatuo-bamai-config
      hostNetwork: true
      hostPID: true

K8s Daemonset 部署

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

通过 K8s daemonset 方式在云原生集群部署。

1. 获取配置文件

curl -L -o huatuo-bamai.conf https://github.com/ccfos/huatuo/raw/main/huatuo-bamai.conf

根据实际环境修改配置，如kubelet 和 elasticsrearch 的相关配置。

2. 创建 configmap

kubectl create configmap huatuo-bamai-config --from-file=./huatuo-bamai.conf

3. 部署采集器

kubectl apply -f https://github.com/ccfos/huatuo/blob/main/build/huatuo-daemonset.minimal.yaml

huatuo-daemonset.minimal.yaml：

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: huatuo
  namespace: default
  labels:
    app: huatuo
spec:
  selector:
    matchLabels:
      app: huatuo
  template:
    metadata:
      labels:
        app: huatuo
    spec:
      containers:
      - name: huatuo
        image: docker.io/huatuo/huatuo-bamai:latest
        resources:
          limits:
            cpu: '1'
            memory: 2Gi
          requests:
            cpu: 500m
            memory: 512Mi
        securityContext:
          privileged: true
        volumeMounts:
        - name: proc
          mountPath: /proc
        - name: sys
          mountPath: /sys
        - name: run
          mountPath: /run
        - name: var
          mountPath: /var
        - name: etc
          mountPath: /etc
        - name: huatuo-local
          mountPath: /home/huatuo-bamai/huatuo-local
        - name: huatuo-bamai-config-volume
          mountPath: /home/huatuo-bamai/conf/huatuo-bamai.conf
          subPath: huatuo-bamai.conf
      volumes:
      - name: proc
        hostPath:
          path: /proc
      - name: sys
        hostPath:
          path: /sys
      - name: run
        hostPath:
          path: /run
      - name: var
        hostPath:
          path: /var
      - name: etc
        hostPath:
          path: /etc
      - name: huatuo-local
        hostPath:
          path: /var/log/huatuo/huatuo-local
          type: DirectoryOrCreate
      - name: huatuo-bamai-config-volume
        configMap:
          name: huatuo-bamai-config
      hostNetwork: true
      hostPID: true

异常事件

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

HUATUO 华佗平台通过 eBPF 技术实时检测 Linux 内核中的多种异常事件，帮助用户快速定位系统、应用及硬件相关问题。

事件列表

事件名称	核心功能	典型场景
softirq	检测内核关闭软中断时间过长，输出调用栈、进程信息等	解决系统卡顿、网络延迟、调度延迟等问题
softlockup	检测系统 softlockup 事件，提供目标进程及内核栈信息	定位和解决系统 softlockup 问题
hungtask	检测 hungtask 事件，输出所有 D 状态进程及栈信息	定位瞬时批量 D 进程场景，保留故障现场
oom	检测宿主机或容器内的 OOM 事件	聚焦内存耗尽问题，提供详细故障快照
memory_reclaim_events	检测内存直接回收事件，记录回收耗时、进程及容器信息	解决内存压力导致的业务卡顿问题
ras	检测 CPU、Memory、PCIe 等硬件故障事件	及时感知硬件故障，降低业务影响
dropwatch	检测内核网络协议栈丢包，输出调用栈及网络上下文	解决协议栈丢包导致的业务毛刺和延迟
net_rx_latency	检测协议栈收包路径（驱动、协议、用户态）的延迟事件	解决接收延迟引起的业务超时和毛刺
netdev_events	检测网卡链路状态变化	感知网卡物理链路故障
netdev_bonding_lacp	检测 bonding LACP 协议状态变化	界定物理机与交换机故障边界
netdev_txqueue_timeout	检测网卡发送队列超时事件	定位网卡发送队列硬件故障

详细说明

通用字段说明

hostname: 物理机 hostname
region：物理机所在可用区
uploaded_time：数据上传时间
container_id：如果事件关联容器，则记录的容器 id
container_hostname：如果事件关联容器，则记录的容器 hostname
container_host_namespace：如果事件关联容器，则记录容器的 K8s 命名空间
container_type：记录容器类型，例如 normal 普通容器，sidecar 边车容器等
container_qos：记录容器级别
tracer_name: 事件名称
tracer_id：此次的 tracing id
tracer_time：触发 tracing 时间
tracer_type：类型，手动触发还是自动触发
tracer_data：特定 tracer 私有数据

1. softirq 软中断关闭

功能描述 检测内核关闭中断时间过长时触发，记录关闭软中断的内核调用栈、当前进程信息等关键数据，帮助分析中断相关延迟问题。

异常事件

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

HUATUO 华佗平台通过 eBPF 技术实时检测 Linux 内核中的多种异常事件，帮助用户快速定位系统、应用及硬件相关问题。

事件列表

事件名称	核心功能	典型场景
softirq	检测内核关闭软中断时间过长，输出调用栈、进程信息等	解决系统卡顿、网络延迟、调度延迟等问题
softlockup	检测系统 softlockup 事件，提供目标进程及内核栈信息	定位和解决系统 softlockup 问题
hungtask	检测 hungtask 事件，输出所有 D 状态进程及栈信息	定位瞬时批量 D 进程场景，保留故障现场
oom	检测宿主机或容器内的 OOM 事件	聚焦内存耗尽问题，提供详细故障快照
memory_reclaim_events	检测内存直接回收事件，记录回收耗时、进程及容器信息	解决内存压力导致的业务卡顿问题
ras	检测 CPU、Memory、PCIe 等硬件故障事件	及时感知硬件故障，降低业务影响
dropwatch	检测内核网络协议栈丢包，输出调用栈及网络上下文	解决协议栈丢包导致的业务毛刺和延迟
net_rx_latency	检测协议栈收包路径（驱动、协议、用户态）的延迟事件	解决接收延迟引起的业务超时和毛刺
netdev_events	检测网卡链路状态变化	感知网卡物理链路故障
netdev_bonding_lacp	检测 bonding LACP 协议状态变化	界定物理机与交换机故障边界
netdev_txqueue_timeout	检测网卡发送队列超时事件	定位网卡发送队列硬件故障

详细说明

通用字段说明

hostname: 物理机 hostname
region：物理机所在可用区
uploaded_time：数据上传时间
container_id：如果事件关联容器，则记录的容器 id
container_hostname：如果事件关联容器，则记录的容器 hostname
container_host_namespace：如果事件关联容器，则记录容器的 K8s 命名空间
container_type：记录容器类型，例如 normal 普通容器，sidecar 边车容器等
container_qos：记录容器级别
tracer_name: 事件名称
tracer_id：此次的 tracing id
tracer_time：触发 tracing 时间
tracer_type：类型，手动触发还是自动触发
tracer_data：特定 tracer 私有数据

1. softirq 软中断关闭

功能描述 检测内核关闭中断时间过长时触发，记录关闭软中断的内核调用栈、当前进程信息等关键数据，帮助分析中断相关延迟问题。

自定义指标

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

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

Systemd 物理机部署

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

1. 腾讯云下载

腾讯操作系统 OpenCloudOS 提供 HUATUO 安装包

wget https://mirrors.opencloudos.tech/epol/9/Everything/x86_64/os/Packages/huatuo-bamai-2.1.0-2.oc9.x86_64.rpm  
wget https://mirrors.opencloudos.tech/epol/9/Everything/aarch64/os/Packages/huatuo-bamai-2.1.0-2.oc9.aarch64.rpm

2. 安装 RPM

sudo rpm -ivh huatuo-bamai*.rpm

3. 启动华佗

sudo systemctl start huatuo-bamai
sudo systemctl enable huatuo-bamai

完整安装可参考https://mp.weixin.qq.com/s/Gmst4_FsbXUIhuJw1BXNnQ

Systemd 物理机部署

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

1. 腾讯云下载

腾讯操作系统 OpenCloudOS 提供 HUATUO 安装包

wget https://mirrors.opencloudos.tech/epol/9/Everything/x86_64/os/Packages/huatuo-bamai-2.1.0-2.oc9.x86_64.rpm  
wget https://mirrors.opencloudos.tech/epol/9/Everything/aarch64/os/Packages/huatuo-bamai-2.1.0-2.oc9.aarch64.rpm

2. 安装 RPM

sudo rpm -ivh huatuo-bamai*.rpm

3. 启动华佗

sudo systemctl start huatuo-bamai
sudo systemctl enable huatuo-bamai

完整安装可参考https://mp.weixin.qq.com/s/Gmst4_FsbXUIhuJw1BXNnQ

源码编译

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, 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, 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

只需实现 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） 是华佗内核监控系统的一项智能诊断功能。当系统出现特定性能异常或资源突变时，AutoTracing 会自动触发，实时捕获详细的现场信息（包括火焰图、进程上下文、调用栈、资源状态等），帮助运维和开发人员快速定位和分析问题，无需手动干预。该功能基于 eBPF 技术实现，具备低开销、高实时性的特点，适用于物理机和容器环境下的异常诊断场景。

支持的自动追踪类型

当前版本支持以下五种自动追踪功能：

追踪名称	核心功能	适用场景
cpusys	检测物理机 CPU sys（系统态）占用率突增，自动生成火焰图并提供进程上下文信息	解决系统负载异常导致的业务毛刺、延迟等问题
cpuidle	检测容器 CPU idle（空闲率）异常下降，自动生成火焰图并提供进程上下文信息	解决容器 CPU 使用率异常，帮助业务分析进程热点
dload	检测容器 loadavg（系统平均负载）突增，自动抓取容器内 D 状态进程的调用信息	解决 D 状态进程突增、资源不可用或锁被长期持有等问题
memburst	检测物理机内存突发分配行为，自动捕获进程内存使用状态	应对短时间内大量内存分配，可能引发直接回收或 OOM 的场景
iotracing	检测物理机磁盘 IO 延迟异常，自动捕获相关进程、容器、磁盘及文件信息	解决磁盘 IO 带宽打满、磁盘访问突增导致的应用请求延迟或系统性能抖动问题

功能特点

智能触发：根据预设阈值自动检测异常，无需人工配置触发条件。
丰富诊断信息：每次触发时自动采集火焰图、调用栈、进程/容器上下文、资源使用详情等关键数据。
低开销设计：采用 eBPF 技术，仅在异常发生时进行针对性采集，日常运行开销极低。
统一输出：所有追踪数据以标准化格式上报，便于查询、分析和告警整合。

使用建议

cpusys 与 cpuidle 适合 CPU 相关性能毛刺的快速定位。
dload 特别适用于 D 状态进程导致的“假死”或卡顿问题。
memburst 可提前发现潜在的内存压力，避免 OOM 发生。
iotracing 是排查磁盘 IO 瓶颈的首选工具。

通过 AutoTracing 功能，华佗能够实现从异常检测到现场保留的自动化闭环，大幅提升问题诊断效率。

自动追踪

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

概述

支持的自动追踪类型

当前版本支持以下五种自动追踪功能：

追踪名称	核心功能	适用场景
cpusys	检测物理机 CPU sys（系统态）占用率突增，自动生成火焰图并提供进程上下文信息	解决系统负载异常导致的业务毛刺、延迟等问题
cpuidle	检测容器 CPU idle（空闲率）异常下降，自动生成火焰图并提供进程上下文信息	解决容器 CPU 使用率异常，帮助业务分析进程热点
dload	检测容器 loadavg（系统平均负载）突增，自动抓取容器内 D 状态进程的调用信息	解决 D 状态进程突增、资源不可用或锁被长期持有等问题
memburst	检测物理机内存突发分配行为，自动捕获进程内存使用状态	应对短时间内大量内存分配，可能引发直接回收或 OOM 的场景
iotracing	检测物理机磁盘 IO 延迟异常，自动捕获相关进程、容器、磁盘及文件信息	解决磁盘 IO 带宽打满、磁盘访问突增导致的应用请求延迟或系统性能抖动问题

功能特点

智能触发：根据预设阈值自动检测异常，无需人工配置触发条件。
丰富诊断信息：每次触发时自动采集火焰图、调用栈、进程/容器上下文、资源使用详情等关键数据。
低开销设计：采用 eBPF 技术，仅在异常发生时进行针对性采集，日常运行开销极低。
统一输出：所有追踪数据以标准化格式上报，便于查询、分析和告警整合。

使用建议

cpusys 与 cpuidle 适合 CPU 相关性能毛刺的快速定位。
dload 特别适用于 D 状态进程导致的“假死”或卡顿问题。
memburst 可提前发现潜在的内存压力，避免 OOM 发生。
iotracing 是排查磁盘 IO 瓶颈的首选工具。

通过 AutoTracing 功能，华佗能够实现从异常检测到现场保留的自动化闭环，大幅提升问题诊断效率。

配置指南

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：日志级别。

配置指南

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

1. 文档概述

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：日志级别。

硬件故障

Fri, 06 Mar 2026 00:00:00 +0000

架构介绍

HUATUO（华佗）支持各种硬件故障检查：

CPU, L1/L2/L3 Cache, TLB
Memory, ECC
PCIe
Network Interface Card Link
PFC/RDMA
ACPI
GPU MetaX

HUATUO（华佗）总体架构如下：

HUATUO 基于 Linux 内核 MCE 和 RAS 技术，通过 eBPF 捕获关键硬件事件，获取硬件设备信息。RAS 在 Linux 内核一直在不断演进发展，从内核 2.6 版本开始逐步的引入更多 tracepoint 点。这种轻量级，事件驱动的实现方式能够覆盖绝大多数高频硬件故障场景。此外 HUATUO 还支持 PFC/RDMA，网卡物理链路状态的检查。

硬件指标事件

HUATUO 通过事件触发实时感知各硬件模块上报的故障信息：故障类型，设备标识，错误信息，时间戳等。

网卡故障，该故障信息被存储在部署华佗组件的服务器，huatuo-local/netdev_event，以及配置的 Elasticsearch 存储服务。其中本地存储的信息格式如下：

{
    "hostname": "your-host-name",
    "region": "xxx",
    "uploaded_time": "2026-03-05T18:28:39.153438921+08:00",
    "time": "2026-03-05 18:28:39.153 +0800",
    "tracer_name": "netdev_event",
    "tracer_time": "2026-03-05 18:28:39.153 +0800",
    "tracer_type": "auto",
    "tracer_data": {
        "ifname": "eth0",
        "index": 2,
        "linkstatus": "linkstatus_admindown",
        "mac": "5c:6f:11:11:11:11",
        "start": false
    }
}

linkstatus 数值类型还可能为：

硬件故障

Fri, 06 Mar 2026 00:00:00 +0000

架构介绍

HUATUO（华佗）支持各种硬件故障检查：

CPU, L1/L2/L3 Cache, TLB
Memory, ECC
PCIe
Network Interface Card Link
PFC/RDMA
ACPI
GPU MetaX

HUATUO（华佗）总体架构如下：

硬件指标事件

HUATUO 通过事件触发实时感知各硬件模块上报的故障信息：故障类型，设备标识，错误信息，时间戳等。

网卡故障，该故障信息被存储在部署华佗组件的服务器，huatuo-local/netdev_event，以及配置的 Elasticsearch 存储服务。其中本地存储的信息格式如下：

{
    "hostname": "your-host-name",
    "region": "xxx",
    "uploaded_time": "2026-03-05T18:28:39.153438921+08:00",
    "time": "2026-03-05 18:28:39.153 +0800",
    "tracer_name": "netdev_event",
    "tracer_time": "2026-03-05 18:28:39.153 +0800",
    "tracer_type": "auto",
    "tracer_data": {
        "ifname": "eth0",
        "index": 2,
        "linkstatus": "linkstatus_admindown",
        "mac": "5c:6f:11:11:11:11",
        "start": false
    }
}

linkstatus 数值类型还可能为：

自定义追踪

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

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

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

自定义追踪

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

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

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

集成测试

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 文件会被测试脚本自动加载并参与校验。

集成测试

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
└── ...

变更日志

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

变更日志

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

HUATUO 文档中心

Docker 容器部署

镜像下载

docker 启动容器

docker compose 启动容器

Docker 容器部署

镜像下载

docker 启动容器

docker compose 启动容器

采集模式

模式

指标

事件

自动追踪

采集模式

模式

指标

事件

自动追踪

指标说明

CPU 系统

调度延迟

中断延迟

指标说明

CPU 系统

调度延迟

中断延迟

快速开始

1. 极速体验

2. 容器启动

2.1 Docker 启动

2.2 Docker Compose 启动

快速开始

1. 极速体验

2. 容器启动

2.1 Docker 启动

2.2 Docker Compose 启动

K8s Daemonset 部署

1. 获取配置文件

2. 创建 configmap

3. 部署采集器

K8s Daemonset 部署

1. 获取配置文件

2. 创建 configmap

3. 部署采集器

异常事件

事件列表

详细说明

通用字段说明

1. softirq 软中断关闭

异常事件

事件列表

详细说明

通用字段说明

1. softirq 软中断关闭

自定义指标

创建

注册

实现 Update

自定义指标

创建

注册

实现 Update

Systemd 物理机部署

1. 腾讯云下载

2. 安装 RPM

3. 启动华佗

Systemd 物理机部署

1. 腾讯云下载

2. 安装 RPM

3. 启动华佗

源码编译

1. 容器编译

2. 物理机编译

2.1 安装依赖

2.2 编译

3. 镜像发布

源码编译

1. 容器编译

2. 物理机编译

实现 `Update`

实现 `Update`

实现 `Start`

实现 `Start`