参考手册 on HUATUO 文档中心

指标参考

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

本文列出指标名称、单位、标签、来源及统计口径。功能与排查场景见内核全景观测。

阅读说明

本文按 CPU、内存、网络、I/O、系统事件和 GPU 分类说明常用指标，供查询和排障时参考。实际输出取决于内核接口、设备驱动、采集器开关和过滤配置，完整指标以节点的 /metrics 输出为准。启用方式见节点配置。

名称：表格统一省略 huatuo_bamai_ 前缀。例如，cpu_util_total 的完整名称为 huatuo_bamai_cpu_util_total。
标签：所有指标带有 host、region；容器指标另带 container_host、container_hostnamespace、container_level、container_name、container_type。表格仅列附加标签，— 表示无附加标签。
计数与单位：计数值表示事件或对象数量，不等于延迟值。累计 Counter 可用 rate() 或 increase() 分析变化；部分内核累计统计以 Gauge 导出，需结合字段语义判断，不能仅凭类型或名称推断。
示例：下列数值仅用于说明输出格式，不代表诊断阈值。未输出指标不等于指标值为零。

# TYPE huatuo_bamai_runqlat_latency counter
huatuo_bamai_runqlat_latency{host="hostname",region="dev",zone="0"} 35100
# TYPE huatuo_bamai_runqlat_container_latency counter
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

此例分别展示宿主机和容器的调度延迟分桶计数，zone 的范围见下文。

构建信息

huatuo_bamai_build_info 和 huatuo_apiserver_build_info 是值恒为 1 的 Gauge，分别表示 bamai 和 apiserver 当前运行的构建。两者由各自程序的 /metrics 暴露，构建信息与该程序的 /version 一致。它们包含既有公共标签 host、region（apiserver 中为空），以及以下构建标签：

标签	含义
`name`	程序名称，与 `/version` 中的 `name` 一致
`version`	程序发布版本，与 `/version` 中的 `version` 一致
`git_commit`	构建的 Git 标识，与 `/version` 中的 `git_commit` 一致；不保证是完整 SHA
`git_tree_state`	构建时的工作区状态：`clean`、`dirty` 或 `unknown`
`build_time`	`/version` 中的时间戳：优先使用注入的构建时间，缺失时回退为 VCS 提交时间或 `(devel)`
`go_version`	构建程序所用的 Go 工具链版本
`compiler`	Go 编译器，例如 `gc`
`platform`	操作系统和架构，例如 `linux/amd64`

未提供发布版本时，version 使用 (devel)。git_commit 优先使用注入值，其次读取 Go 构建信息中的 VCS 提交标识，两者均不可用时使用 (devel)。构建标签只附加到该指标，业务指标的标签保持不变。Prometheus 抓取后，可通过相同的 job、instance 将构建信息与业务指标关联；跨集群查询还需纳入实际用于区分目标的集群标签。

自动追踪字段

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

本文说明自动追踪记录的字段、单位和示例。适用场景见自动追踪，配置节和参数见节点配置。下文阈值为内置默认值，配置文件可覆盖。

结果

自动追踪事件按已启用的存储配置写入 Elasticsearch 或本地文件。可通过 tracer_type=autotracing、tracer_name、主机或容器标识及时间范围筛选。下列 JSON 为说明字段结构的示例，并非实测结果。

CPU 示例使用 perf。使用 profiler 时，事件保留触发指标，profile 独立存入 Elasticsearch，并与事件共用 tracer_id。存储要求与查看方式见节点配置。

公共字段

记录包含以下公共字段；容器字段仅在关联到容器时提供。

字段	说明
`hostname`	节点主机名
`region`	节点所属区域
`uploaded_timestamp`	数据上传时间
`container_id`	容器 ID
`container_hostname`	容器主机名
`container_host_namespace`	容器的 Kubernetes 命名空间
`container_type`	容器类型
`container_qos`	容器 QoS 级别
`tracer_name`	事件名称（如 `cpusys`、`memburst` 等）
`tracer_id`	本次追踪 ID
`started_timestamp`	开始追踪的时间
`tracer_type`	观测类型，自动追踪记录固定为 `autotracing`
`tracer_data`	特定事件私有数据（详见各事件说明）

宿主机 CPU

追踪器：cpusys。通过 AutoTracing.CPUSys.Tool 选择 perf（默认）或 profiler。

周期性读取 /proc/stat，检测宿主机 system、user（user + nice）和总执行 CPU（user + nice + system + irq + softirq）突增，包含容器工作。任一组使用率及其增量同时严格超过阈值时触发采样。默认使用率／增量阈值分别为 system 45%／20 个百分点、user 75%／45 个百分点、total 90%／55 个百分点。

异常事件字段

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

本文说明异常事件的记录结构、字段和适用限制。功能介绍见异常事件诊断，采集设置见节点配置。

事件记录

结果按已启用的存储配置写入 Elasticsearch 或本地文件。查询时按 tracer_type=event、事件名称、主机或容器及时间范围筛选。下列 JSON 为结构示例，省略部分公共字段；其中阈值说明使用内置默认值。

容器字段仅在关联到容器时提供；具体事件数据位于 tracer_data。

字段	说明
`hostname`	节点主机名
`region`	节点所属区域
`uploaded_timestamp`	数据上传时间
`container_id`	容器 ID
`container_hostname`	容器主机名
`container_host_namespace`	容器的 Kubernetes 命名空间
`container_type`	容器类型，例如 `normal` 普通容器，`sidecar` 边车容器等
`container_qos`	容器 QoS 级别
`tracer_name`	事件名称（如 `sched_tick`、`memory_oom_kill` 等）
`tracer_id`	本次追踪 ID
`observed_timestamp`	用户态观测时间
`tracer_type`	观测类型，即时事件记录固定为 `event`
`tracer_data`	特定事件私有数据（详见各事件说明）

CPU 调度

调度 tick 间隔

观测器：sched_tick。

检测相邻调度 tick 的总间隔；间隔达到阈值时记录当前内核调用栈和进程信息。该事件可发现 IRQ 长时间关闭、CPU 停顿或虚拟化调度延迟等问题，但不能单独证明软中断被禁用。comm 和 pid 表示上报 tick 所中断的任务，不表示造成延迟的任务。

硬件事件字段

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

本文说明 RAS 指标、事件结构、严重级别和来源字段。采集范围及启用方式见硬件故障诊断。

EventTracing.Ras.MceThrBackoff 控制阈值中断事件的保存间隔。冷却期间仍累计事件数，因此计数增长量不一定等于已保存记录数。

结果

错误计数

huatuo_bamai_ras_hw_err_total 为接收到的 RAS 事件累计数，按 type 区分 mce、edac、acpi、aer、thr 和 arm_ghes。标签存在不代表当前平台支持对应探针。

huatuo_bamai_ras_hw_err_total{hostname="node-01",region="region-01",type="edac"} 12

以上为示例值。计数单位是事件，并非 EDAC 记录中 err_count 的累加值。网卡硬件丢包及 PFC 指标见内核全景观测，网卡状态变化见异常事件诊断。

事件记录

按 tracer_name=ras 和 tracer_type=event 查询。下面以 EDAC 为例，省略部分字段：

{
    "hostname": "node-01",
    "observed_timestamp": "2026-05-11T08:58:47.329Z",
    "kernel_observed_timestamp": "2026-05-11T08:58:47.328548319Z",
    "tracer_name": "ras",
    "tracer_type": "event",
    "tracer_data": {
        "dev": "MEM",
        "event": "EDAC",
        "type": "Corrected",
        "info": "{\"err_count\":1,\"err_type\":\"Corrected\",\"err_msg\":\"memory read error\",\"label\":\"CPU_SrcID#0_Ha#0_Chan#0_DIMM#0\",\"mc_index\":0,\"addr\":7860269056,\"grain\":128}"
    }
}

字段	说明
`tracer_data.dev`	设备或部件标识，如 `CPU/MEM`、`MEM`、`ACPI`、`PCIe 0000:03:00.0`
`tracer_data.event`	错误来源，见采集范围
`tracer_data.type`	归一化后的严重级别，见下表
`tracer_data.info`	包含详细字段的 JSON 字符串，需再次解析；结构取决于事件来源
`observed_timestamp`	用户态接收事件的时间
`kernel_observed_timestamp`	内核观测时间转换后的时间戳

严重级别

严重级别用于分类，不等同于恢复成功、业务无影响或必须重启的判断。

Profiling API

Wed, 21 Oct 2026 00:00:00 +0000

本文列出性能剖析任务的请求、响应和状态约定。首次采集见性能剖析实践。

huatuo-apiserver 通过 /v1/profiling 创建、监督和停止 Profiling Job。每次 HTTP 创建请求都是一次独立执行。Job 持久化在 huatuo-apiserver，Node 只维护内存中的 Operation 和 profiler 进程。

Job 控制不依赖 Elasticsearch；查询原始结果和生成 Dashboard 链接时才要求配置 Elasticsearch。Node 和 Apiserver 必须使用同一索引。

请求约定

huatuo-apiserver 默认监听 :12740。以下示例使用环境变量统一设置服务地址和 Bearer token：

API_BASE="http://127.0.0.1:12740"
API_TOKEN="REPLACE_WITH_RANDOM_HEX"

每个请求必须在 Authorization 请求头中传入配置的 Bearer token：

Authorization: Bearer REPLACE_WITH_RANDOM_HEX

非管理员用户需要配置 /v1/profiling 和 /v1/profiling/** 权限。权限可带 HTTP 方法前缀，例如 GET /v1/profiling/**。成功响应仅包含 data：

{
  "data": {}
}

错误响应包含稳定错误码和可读消息：

{
  "error": {
    "code": "result_unavailable",
    "message": "Job state does not provide a complete Profiling result"
  }
}

客户端应根据 error.code 分支处理，不应解析 error.message。

profiler 命令行参数

Wed, 21 Oct 2026 00:00:00 +0000

本文列出 profiler 的参数、默认值和适用范围。构建条件与采集示例见命令行采集，格式选择见输出格式。

--output-path 和 --output-format 都必须显式传入。--output-format 的声明默认值为 collapsed，但不能依靠该默认值省略参数。

通用参数

参数	默认值	适用范围	说明
`--type`, `-t`	无	全部	观测类型：`cpu` 或 `memory`，必填
`--language`, `-l`	无	全部	目标语言：`c`、`c++`、`go`、`java` 或 `python`，必填
`--pid`, `-p`	无	全部	目标 PID；Java、Python 可使用逗号分隔多个 PID，原生采集最多一个 PID
`--container-id`	无	全部	目标容器 ID；原生 CPU 采集可与 `--pid`（宿主机 PID）组合，两个过滤条件同时生效；其他采集类型与 `--pid` 互斥
`--duration`, `-d`	`10`	全部	总采集时长，单位为秒，最小为 1
`--aggr-interval`	`10`	全部	聚合周期，单位为秒，不得大于采集时长
`--freq`, `-F`	`99`	CPU	每秒采样次数；Java 最大为 1000
`--output-path`	必填	全部	本地文件、目录或 `stdout`，`remote-store` 时为 Unix socket；新目录路径以 `/` 结尾
`--output-format`	`collapsed`	全部	`collapsed`、`flamegraph`、`svg`、`json` 或 `remote-store`；必须与 `--output-path` 一起显式指定
`--max-concurrent-procs`	`0`	Java、Python	并发采集子进程上限；`0` 表示不限制
`--tool-path`	无	Java、Python	外部采集工具统一根目录，必填
`--binary-match-path`	无	Java、Python	按可执行文件路径匹配容器内目标进程
`--huatuo-api-address`	`127.0.0.1:19704`	容器目标	用于解析容器元数据的 HUATUO API 地址
`--task-id`	空；本地输出时内部生成	全部；`remote-store` 必填	toolstream 和远端存储共用的稳定采集任务 ID
`--enable-pprof`	`false`	工具自身	在 `127.0.0.1:6000` 暴露工具自身的 Go runtime profile
`--version-format`	`text`	版本查询	`--version` 的输出格式：`text`、`json` 或 `short`
`--help`, `-h`	-	全部	显示命令帮助
`--version`, `-v`	-	全部	显示版本与构建信息

这些 pprof 接口描述 profiler 进程自身的 Go runtime，不是 --pid 指定的目标或 Java/Python 采集子进程。监听范围由所有网卡收紧为 loopback；端口被占用时启动失败。