V2.2.0 on HUATUO Documentation

Getting started

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

To help users quickly experience and deploy HUATUO, this document is divided into three sections: Quick Experience，Quick Start，Compilation & Deployment.

1. Quick Experience

This section helps you quickly explore the frontend capabilities. You can directly access demo station, such as viewing exception event overviews, exception event context information, metric curves, etc. (Account: huatuo passwd: huatuo1024).

Compile

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

1. Build with the Official Image

To isolate the developer’s local environment and simplify the build process, we provide a containerized build method. You can directly use docker build to produce an image containing the core collector huatuo-bamai, BPF objects, tools, and more. Run the following in the project root directory:

docker build --network host -t huatuo/huatuo-bamai:latest .

2. Build a Custom Image

Dockerfile.dev:

FROM golang:1.23.0-alpine AS base
# Speed up Alpine package installation if needed
# RUN sed -i 's/dl-cdn.alpinelinux.org/mirrors.aliyun.com/g' /etc/apk/repositories
RUN apk add --no-cache \
                make \
                clang15 \
                libbpf-dev \
                bpftool \
                curl \
                git

ENV PATH=$PATH:/usr/lib/llvm15/bin

# build huatuo components
FROM base AS build
ARG BUILD_PATH=${BUILD_PATH:-/go/huatuo-bamai}
ARG RUN_PATH=${RUN_PATH:-/home/huatuo-bamai}
WORKDIR ${BUILD_PATH}

2.1 Build the Dev Image

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

2.2 Run the Dev Container

docker run -it --privileged --cgroupns=host --network=host \
  -v /path/to/huatuo:/go/huatuo-bamai \
  huatuo/huatuo-bamai-dev:latest sh

2.3 Compile Inside the Container

Run:

Configuration Guide

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

1. Document Overview

huatuo-bamai is the core collector of HUATUO (a BPF-based metrics and anomaly inspector). Its configuration file defines the data collection scope, probe enablement strategy, metric output format, anomaly detection rules, and logging behavior.

The configuration file uses TOML format and includes multiple sections such as global blacklist, logging, runtime resource limits, storage configuration, and AutoTracing. Each configuration item comes with detailed comments explaining its purpose, default value, and important notes. This document provides a clear and detailed English explanation for every configuration item to help users understand and safely customize the settings.

Integration Test

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

This integration test validates that huatuo-bamai can start correctly with mocked /proc and /sys filesystems and expose the expected Prometheus metrics.

The test runs the real huatuo-bamai binary and verifies the /metricsendpoint output without relying on the host kernel or hardware.

What the Script Does

The integration test performs the following steps:

Generates a temporary bamai.conf
Starts huatuo-bamai with mocked procfs and sysfs
Waits for the Prometheus /metrics endpoint to become available
Fetches all metrics from /metrics
Verifies that all expected metrics exist
Stops the service and cleans up resources

If any expected metric is missing, the test fails.

Change Log

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

Features

Added iotracing AutoTracing capability
Added general hardware failure detection (CPU, Memory, PCIe)
Added MetaX GPU failure detection
Added physical link detection support
Added support for Amazon EKS deployment
Added support for Aliyun ACK deployment
Added dropwatch namespace cookie support
Added container throttled_time metric
Added compatibility with kubelet systemd cgroup driver
Added automatic detection of kubelet cgroup driver type
Added, optimized, and standardized the huatuo-bamai configuration file
Added Github CI/CD automated testing
Added unit testing, integration testing, and end-to-end testing
Enhanced golangci-lint static code analysis rules
Added daemonset YAML deployment files
Added new Metric API interfaces
Added compatibility support for 5.15.x kernel series

Bug Fixes & Improvements

Optimized local storage format
Optimized and refactored code in multiple modules
Improved and enriched documentation at https://huatuo.tech/docs/