参考手册

• 1: 指标参考
• 2: 自动追踪字段
• 3: 异常事件字段
• 4: 硬件事件字段
• 5: Profiling API
• 6: profiler 命令行参数

1 - 指标参考

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

阅读说明

本文按 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 中为空），以及以下构建标签：

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

CPU

调度延迟

调度延迟指任务进入可运行状态到实际获得 CPU 的等待时间。以下指标为 eBPF 采集的累计 Counter，按 zone 分桶：0 为 [0, 10) ms，1 为 [10, 20) ms，2 为 [20, 50) ms，3 为 ≥50 ms。

软中断延迟

统计各 CPU 上软中断从触发到开始处理的等待时间，当前仅输出 NET_RX、NET_TX。该指标为累计 Counter；zone：0 为 [0, 10) μs，1 为 [10, 100) μs，2 为 [100, 1000) μs，3 为 ≥1 ms。

利用率

宿主机利用率按在线 CPU 核数归一化，容器利用率按可用 CPU 容量归一化，输出范围为 0–100%。

可用核数

容器可用 CPU 容量取配额折算核数与有效 CPU 集合大小的较小值；未限制配额时使用有效 CPU 集合大小，无法获取有效集合时回退到宿主机在线核数。

限流与争抢

限流统计来自 cgroup CPU 接口，仅输出内核提供的字段。等待占比还要求内核导出 wait_sum，并启用 kernel.sched_schedstats=1。

等待占比按采集区间计算：等待时间增量 /（等待时间增量 + CPU 使用时间增量）× 100%。它描述可调度时间中的等待比例，不是限流时间占比。

参考：

• CFS 带宽统计
• cgroup v2 CPU 接口

突发使用

统计 cgroup 使用突发 CPU 容量的周期数和时间，仅在内核提供对应字段时输出。

负载

宿主机输出 1、5、15 分钟平均负载；容器输出当前可运行和不可中断任务数，两者不是相同时间窗口的统计。

内存

内存回收

内存回收和规整可能阻塞任务。以下指标分别记录宿主机累计耗时和容器直接回收事件数。

memory_others_container_directstall_time、memory_others_container_asyncreclaim_time、memory_others_container_local_direct_reclaim_time 依赖滴滴定制内核的 memory.directstall_stat、memory.asynreclaim_stat、memory.local_direct_reclaim_time 接口。

主线及常见发行版内核缺少这些接口时不会输出对应指标，无需额外加载模块。标准内核上的容器直接回收次数可使用 memory_reclaim_container_directstall 观测。

内存状态

容器字段来自 memory.stat，宿主机字段来自 /proc/vmstat，均受 MetricCollector.Vmstat 过滤规则影响。字段是否存在及其含义取决于内核和 cgroup 版本。

容器内存

宿主机内存

以下名称已包含 memory_vmstat_ 前缀；底层字段值原样导出，不统一换算为字节。pgpgin、pgpgout 按内核的 KiB 口径读取，见 Linux vmstat 实现。

页面状态与 LRU

脏页与写回

缺页与换页

回收与扫描

透明大页（THP）

NUMA

参考：

• cgroup v2
• cgroup v1 内存控制器
• 透明大页

内存事件

以下字段来自 memory.events，记录回收、内存限制和 OOM 事件。主线内核在 cgroup v2 中提供该接口；滴滴定制内核也可在 cgroup v1 中提供。接口缺失时不输出。各字段的统计条件不同，不能相加作为独立事件总数。

空闲内存块

展示每个 NUMA 节点、内存区域和阶数的空闲内存块数量。order=n 表示每块包含 2^n 个连续页面；指标值是块数，不是页面数。

容器直接回收与内存规整累计耗时

两项为累计耗时 Gauge，统计全局直接回收与规整中的任务耗时。主机总量包含容器工作；缺失或归属不明确的容器记录不输出。容器采集失败仍保留主机数据，加载依赖容器探针，加载或挂载失败时该采集器不可用。容器重建后对应容器累计值重新开始，主机累计值不受影响；BPF 重载后两者均归零。

主机 memcg 回收累计次数

该 Gauge 统计全机 memcg 回收次数，排除 kswapd，不是全局回收次数或耗时。主机总量包含容器活动，不能与容器计数相加；BPF 重载后归零。

网络

TCP 内存

记录 TCP 内存使用量及其相对限制的占比。

连接跟踪

宿主机 nf_conntrack 表的占用与容量，分别来自 /proc/sys/net/netfilter/nf_conntrack_count 与 /proc/sys/net/netfilter/nf_conntrack_max。仓库配置默认通过 BlackList 禁用 net_conntrack。

ARP 邻居项

按宿主机和容器网络命名空间统计 ARP 邻居项。

发送队列

Qdisc 指标描述发送队列积压、发送量、丢包和重入队次数，不直接提供排队延迟。仅采集匹配设备的根 Qdisc，跳过 noqueue。仓库配置默认通过 BlackList 禁用 netdev_qdisc。

硬件丢包

统计支持的网卡驱动在接收方向的硬件丢包。优先使用 rx_missed_errors，否则尝试从 rx_dropped 中扣除 eBPF 统计的软件丢包。仓库配置默认通过 BlackList 禁用 netdev_hw。

RDMA 端口统计

netdev_rdma_link_<counter> 输出内核的逐端口计数，具体名称取决于驱动。附加标签为 device、nodeguid、index、num_ports 和 port。

新增 port 标签会产生新的时间序列，单端口设备也受影响。端口级查询保留该标签；对选定计数器，设备总量使用 sum by (region, host, device) (<metric>)，设备速率使用 sum by (region, host, device) (rate(<metric>[5m]))，将 <metric> 替换为完整指标名。只按 device 聚合会混合不同主机上的同名设备。

网卡统计

通过 proc 或 netlink 采集网卡统计，公共指标遵循 Linux /proc/net/dev 的统计口径：

• receive_dropped：rx_dropped + rx_missed_errors。
• receive_frame_errors：rx_length_errors + rx_over_errors + rx_crc_errors + rx_frame_errors。
• transmit_carrier_errors：tx_carrier_errors + tx_aborted_errors + tx_window_errors + tx_heartbeat_errors。

netlink 还提供细分错误指标和 receive_nohandler，细分错误可能已包含在上述聚合值中，不能与聚合值重复相加。表中列宿主机名称；容器名称在 netdev_ 后增加 container_。

TCP 统计

读取网络命名空间的 /proc/<pid>/net/netstat 和 snmp，受 MetricCollector.Netstat 过滤规则影响。表中列宿主机名称；容器名称在 netstat_ 后增加 container_。

表中仅列部分 TcpExt 字段；其余字段及版本差异见 Linux 内核文档。

参考：

• TCP/SNMP 计数器

Socket 使用量

读取网络命名空间的 /proc/<pid>/net/sockstat。表中列宿主机名称；容器名称在 sockstat_ 后增加 container_。mem、mem_bytes 仅在宿主机输出。

I/O

配置

iotracing、iolatency、blk_throtl、iocost 和 io_health 默认启用。 向全局 BlackList 添加对应名称并重启 Huatuo 可关闭该功能。 关闭 iotracing 会同时停止磁盘指标和自动诊断；关闭 io_health 会停止 健康事件、取证及其指标，不影响 iotracing。

磁盘性能

通过以下指标观测磁盘性能。指标使用 huatuo_bamai_iotracing_ 前缀， 均为区间 Gauge，带 disk 标签。

指标覆盖整盘和支持的逻辑设备，不包含分区及 loop、ram、zram、fd 等伪设备。

延时与 IO 大小分布

iolatency 统计 SCSI/SAS、NVMe、virtio 磁盘及容器读写 IO 的延时和大小分布。 仅采集启动时已开启 iostats 和请求时间统计的磁盘，运行中不支持关闭这些配置。 启动时若软件 blk-crypto fallback 已初始化，整个 iolatency 不启动。

SCSI 下发大小沿用内核的 16 位扇区计数，达到 32 MiB 会回绕。 跨 blkcg 合并 request 时，容器下发大小为近似归属，宿主机统计不受影响。

块设备增删或重建时，iolatency、blk_throtl 和 iocost 重新开始统计， 过渡期间的所有磁盘数据可能缺失。

桶值为采集区间内小于等于 le 上界的 IO 数量，+Inf 为总数；延时边界 单位为秒，大小边界单位为字节。指标为区间 Gauge。

# TYPE huatuo_bamai_iolatency_q2d_seconds_bucket gauge
huatuo_bamai_iolatency_q2d_seconds_bucket{disk="sda",operation="read",host="hostname",region="dev",le="0.001"} 3
huatuo_bamai_iolatency_q2d_seconds_bucket{disk="sda",operation="read",host="hostname",region="dev",le="+Inf"} 5
# TYPE huatuo_bamai_iolatency_d2c_seconds_bucket gauge
huatuo_bamai_iolatency_d2c_seconds_bucket{disk="sda",operation="read",host="hostname",region="dev",le="+Inf"} 5
# TYPE huatuo_bamai_iolatency_q2g_seconds_bucket gauge
huatuo_bamai_iolatency_q2g_seconds_bucket{disk="sda",operation="read",host="hostname",region="dev",le="+Inf"} 5
# TYPE huatuo_bamai_iolatency_container_q2g_seconds_bucket gauge
huatuo_bamai_iolatency_container_q2g_seconds_bucket{container_host="etcd-hostname",container_hostnamespace="kube-system",container_level="burstable",container_name="etcd",container_type="normal",disk="sda",operation="read",host="hostname",region="dev",le="+Inf"} 2

17 个延时桶界（秒）为 0.00005、0.0001、0.00025、0.0005、 0.001、0.002、0.004、0.008、0.016、0.032、0.064、0.128、 0.256、0.512、1、2、+Inf。

Grafana

IO 总览展示各采集区间的延时分布和 IO 数量，点击柱状图可查看该时段的 延时与大小直方图。面板使用 Business Charts（volkovlabs-echarts-panel）。

旧指标变更指南

升级后需更新自定义面板和告警，以下省略 huatuo_bamai_ 前缀：

disk 从 8:0 等设备号改为 sda 等磁盘名，新增 operation 区分读写。 旧 zone 编号改为以秒为单位的 le 累计上界；桶界见上文，不能按编号直接替换。 统计 (a, b] 范围的数量时，用 le=b 的值减去 le=a 的值。

旧延时指标仅统计 20 ms 及以上的 IO；新指标覆盖支持盘的全部读写 IO， D2C 从最后一次下发计时。旧告警需按新的阶段和桶界调整，不能只改指标名称。

新延时桶由累积 Counter 改为区间 Gauge，不能继续使用 rate() 或 increase()。 单个采集区间直接查询；例如，统计最近五分钟某盘读 IO 的 D2C 样本总数：

sum_over_time(huatuo_bamai_iolatency_d2c_seconds_bucket{disk="sda",operation="read",le="+Inf"}[5m])

硬件

# HELP huatuo_bamai_io_health_blkdisk_freeze the disk freeze event count
# TYPE huatuo_bamai_io_health_blkdisk_freeze counter
huatuo_bamai_io_health_blkdisk_freeze{disk="sda",host="hostname",region="dev"} 0

可在宿主机仪表盘的 Overview → Selected Metric 中选择此指标。

blk-throttle 排队等待

blk_throtl 统计 IO 因 blk-throttle 限速而排队的数量和平均等待时间。 每个 IO 结束排队后计数一次，等待时间从首次排队算起。

指标按 disk 和 operation（read 或 write）区分，scope=host 表示宿主机总量，scope=other 表示其中无法归属容器的部分。 容器指标使用容器标签，不带 scope。四项均为区间 Gauge。

容器发现可选，宿主机采集不依赖 kubelet。容器查询失败或标签无效时，本轮数据 归入 other；关联恢复后不补报历史数据。临时采集失败后，首次成功采集仅重建 基线，下一次成功采集恢复输出，不补报失败区间。若错误导致采集停止，需排障后 重启 Huatuo。

cgroup 实际释放后，尚未采集的尾部等待增量归入 Host 和 Other，不再关联容器。 两次成功采集之间，同一统计项在单 CPU 上完成至少 67,108,864 次等待，或累计 等待约 274.9 万秒时，计数回绕可能导致少计。

IOCOST 等待统计

iocost 统计预算不足造成的等待。等待时间从 IO 进入等待队列算到最终被唤醒， 计入等待结束所在的采集区间。

这些区间 Gauge 按 disk（如 sda、nvme0n1）和 operation （read、write）分组。scope=host 表示设备总量，包含所有 容器；scope=other 表示其中未归属容器的部分。

容器发现可选，宿主机采集不依赖 kubelet。容器查询失败或标签无效时，本轮数据 归入 other；关联恢复后不补报历史数据。临时采集失败后，首次成功采集仅重建 基线，下一次成功采集恢复输出，不补报失败区间。若错误导致采集停止，需排障后 重启 Huatuo。

cgroup 实际释放后，尚未采集的尾部等待增量归入 Host 和 Other，不再关联容器。 两次成功采集之间，同一统计项在单 CPU 上完成至少 67,108,864 次等待，或累计 等待约 274.9 万秒时，计数回绕可能导致少计。例如，同一统计项的 10,240 次等待 各持续 270 秒、在同一区间由同一 CPU 结算，会超出等待时间容量。

采集需要支持 IOCOST 的非 PREEMPT_RT Linux 内核，具备 BPF/BTF 和 kprobe 能力。

设备健康

io_health 记录以下事件：

NVMe 状态名不可用时，new_state 为 unknown，new_state_raw 保留状态码。

block 错误、NVMe 超时、SCSI 异常及 MD 成员进入 faulty、blocked、 write_error 或 removed 状态会触发只读健康取证：NVMe 使用 nvme-cli， SCSI 使用 smartctl，结果随事件保存。无法唯一确定目标时仅保留事件，不扫描 其他设备。MD 监测不需要 mdadm。 事件中的 device 可保留 MD 成员的分区名；取证目标归整为唯一物理磁盘或 NVMe controller。 同设备取证执行中及结束后的 60 秒冷却期内不重复取证，原始事件仍独立保存。

huatuo_bamai_io_health_ Counter 记录进程启动后观察到的事件：

MD 和 NVMe controller 状态变化以事件保存，不提供当前状态 Gauge。 Counter 先于事件保存更新；保存失败计入 event_persistence_failures_total{reason="save_error"}。

健康事件单独保存为文档，不可获得或不适用的可选字段省略：

NVMe 证据包括 critical_warning、media_errors_total，以及最多八条包含 状态码、NSID 和 LBA 的错误日志。SCSI 证据包括整体健康状态、ASC/ASCQ、温度、 缺陷数量、读/写/校验错误计数，以及待处理缺陷数量和最多八个示例 LBA。

磁盘统计

diskio 读取 /proc/diskstats 和 /proc/stat，提供设备级请求数、吞吐量、累计耗时和宿主机 CPU iowait。

磁盘名标签由 device 改为 disk，自定义查询的筛选和图例需同步更新； 指标名称和类型不变。

仓库配置默认通过 BlackList 禁用 diskio。从黑名单移除并重启 huatuo-bamai 服务后启用。

请求数、字节数和 I/O 耗时为累计 Counter，可用 rate() 计算 IOPS、吞吐量和耗时增长速率。平均请求耗时为耗时增长速率除以请求速率，计算时需排除请求速率为零的区间。io_in_progress 和 disk_iowait_percent 为 Gauge。

XFS

xfs 从 sysfs 采集宿主机各设备的统计，附加标签为 device。xfs_log_free_bytes 为 Gauge，名称以 _total 结尾的指标为累计 Counter。

无法获取日志可用空间时不输出 xfs_log_free_bytes。新增 XFS 挂载后需重启 huatuo-bamai 服务。

系统事件

软锁死

记录内核检测到的 soft lockup 事件。

任务阻塞

记录内核检测到的 hung task 事件。

HungTask 容器归属与计数

容器计数包含在主机 Counter 中，不受追踪退避影响。容器归属无法解析的事件仍计入主机总量。容器退出后清理其计数，agent 重启后归零；同一阻塞任务重复上报按多次事件计数。

GPU

MetaX

仓库配置默认通过 BlackList 禁用 metax_gpu，启用前需满足对应设备和 SDK 依赖。

MThreads

摩尔线程 GPU 采集依赖 MTML 管理库，启动时依次查找 libmtml.so.2、libmtml.so。

从 BlackList 移除 mthreads_gpu 并重启 huatuo-bamai 服务后启用。MetricCollector.Mthreads 中的 EnableHealth、EnablePCIe、EnableMTLink 控制对应指标组。

2 - 自动追踪字段

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

结果

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

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

公共字段

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

宿主机 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 个百分点。

三组共用一次采集和默认 30 分钟冷却。阈值在 CPUSys 下独立配置，不与 CPUIdle 共用，见配置参考。事件保留原 system 字段，并增加对应的 user_percent*、total_percent* 字段；零值新增字段省略。

示例（省略部分公共字段）：

{
    "tracer_name": "cpusys",
    "tracer_data": {
        "system_percent": 52,
        "system_percent_threshold": 45,
        "system_percent_delta": 25,
        "system_percent_delta_threshold": 20,
        "flamedata": [
            {"level": 0, "value": 1000, "self": 0, "label": "all"},
            {"level": 1, "value": 350, "self": 350, "label": "do_syscall_64"}
        ]
    }
}

容器 CPU

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

周期性读取容器 cgroup CPU 统计。用户态、系统态或总占用率中的任一项同时超过占用率阈值和相邻采样增量阈值时，触发容器级 CPU 采样。

同一容器默认冷却 30 分钟，目标范围由 AutoTracing.CPUIdle.Filter 控制。内置默认阈值如下：

示例（省略部分公共字段）：

{
    "tracer_name": "cpuidle",
    "tracer_data": {
        "user_percent": 80,
        "user_percent_threshold": 75,
        "user_percent_delta": 48,
        "user_percent_delta_threshold": 45,
        "system_percent": 12,
        "system_percent_threshold": 45,
        "system_percent_delta": 5,
        "system_percent_delta_threshold": 20,
        "total_percent": 92,
        "total_percent_threshold": 90,
        "total_percent_delta": 53,
        "total_percent_delta_threshold": 55,
        "flamedata": [
            {"level": 0, "value": 1000, "self": 0, "label": "all"},
            {"level": 1, "value": 800, "self": 800, "label": "java/com.example.App.main"}
        ]
    }
}

容器 D 状态负载

追踪器：dload。

通过 netlink 及 cgroup 读取容器内进程状态，计算不可中断（D 状态）进程负载的指数加权移动平均值（EMA）。EMA 超过阈值（默认 5）时触发，同一容器默认冷却 30 分钟。

结果包含容器及宿主机 D 状态进程的内核栈，通过 AutoTracing.IssuesList 标记已知问题。

示例（省略部分公共字段）：

{
    "tracer_name": "dload",
    "tracer_data": {
        "threshold": 5,
        "nr_sleeping": 120,
        "nr_running": 4,
        "nr_stopped": 0,
        "nr_uninterruptible": 8,
        "nr_iowait": 3,
        "load_avg": 7.23,
        "dload_avg": 6.81,
        "known_issue": "",
        "stack": "task:java            state:D stack:    0 pid: 12345 tgid: 12345 ...\n  io_schedule+0x18/0x40\n  ext4_file_write_iter+0x..."
    }
}

磁盘 I/O

追踪器：iotracing。

每 5 秒读取 /proc/diskstats。触发条件需连续两个采样周期成立：非 NVMe 设备检查利用率；NVMe 设备要求利用率和读、写吞吐率之一同时超阈值；各设备也会独立检查读、写平均等待时间。采集结果包含进程及文件 I/O 速率、I/O 调度等待栈。

直接运行 iotracing 时，可通过 --enable-pprof（默认关闭）在 http://127.0.0.1:6000/debug/pprof/ 提供 profile；若地址已被占用，命令启动失败。这些 profile 仅反映 iotracing 进程自身的 Go runtime，不包含 huatuo-bamai 或执行磁盘 I/O 的业务进程。自动追踪不会开启此选项。

示例（省略部分公共字段）：

{
    "tracer_name": "iotracing",
    "tracer_data": {
        "reason_snapshot": {
            "type": "ioutil",
            "device": "sda",
            "major_num": 8,
            "minor_num": 0,
            "iostatus": {
                "read_bps": 125829120,
                "read_iops": 450,
                "read_await": 12,
                "write_bps": 2202009600,
                "write_iops": 890,
                "write_await": 145,
                "io_util": 95,
                "queue_size": 32
            }
        },
        "process_file_io_stats": [
            {
                "pid": 12345,
                "comm": "java",
                "container_hostname": "app-pod-xxx",
                "total_fs_read_bps": 0,
                "total_fs_write_bps": 52428800,
                "total_disk_read_bps": 0,
                "total_disk_write_bps": 49152000,
                "total_files": [
                    {
                        "path": "/data/logs/app.log",
                        "dev_name": "sda",
                        "fs_write_bps": 52428800,
                        "disk_write_bps": 49152000
                    }
                ],
                "total_file_count": 1
            }
        ],
        "io_schedule_timeout_stacks": [
            {
                "pid": 12345,
                "tid": 12346,
                "cpu": 2,
                "comm": "java",
                "container_hostname": "app-pod-xxx",
                "schedule_latency_us": 250000,
                "stack": [
                    "io_schedule+0x18/0x40",
                    "ext4_file_write_iter+0x2a0/0x4c0"
                ]
            }
        ]
    }
}

宿主机匿名内存

追踪器：memburst。

默认每 10 秒采样一次宿主机匿名内存，填满 60 个采样点的滑动窗口后开始判断。当前匿名内存达到窗口最早值的 2 倍，且占宿主机总内存至少 70% 时触发；默认冷却时间为 30 分钟。

结果按 RSS 降序记录前 N 个进程（默认 10 个），并依次尝试为排名前 min(N, 3) 个进程采集运行时快照。Go、HotSpot 和 CPython 使用对应采集器；不支持的运行时返回 unavailable，并在可用时保留进程内存计数。采集失败不代表内存使用为零。

每个进程的采集预算为 2 秒，每份快照最多保留 10 条内存对象记录，JSON 上限为 512 KiB。超时为协作式，不能中断正在执行的同步系统调用，因此不保证在 2 秒内返回。

整个 tracer_data 上限为 2 MiB，落盘排名最多 1,000 条。超限时先移除排名靠后的快照，再按需裁剪基础排名尾部，并设置 snapshot_reason；取消或降级记录也遵循这些限制。

示例（省略部分公共字段）：

{
    "tracer_name": "memburst",
    "tracer_data": {
        "top_memory_usage": [
            {
                "PID": 3456,
                "ProcessName": "go-service",
                "MemSize": 268435456
            }
        ],
        "process_snapshots": [
            {
                "pid": 3456,
                "process_name": "go-service",
                "language": "go",
                "snapshot": {
                    "runtime_version": "go1.24.0",
                    "status": "complete",
                    "duration_ms": 25,
                    "entries": [
                        {
                            "kind": "inuse_space_objects",
                            "name": "main.allocate",
                            "bytes": 1048576,
                            "objects": 16,
                            "stack": [
                                "main.allocate fixture.go:42"
                            ]
                        }
                    ]
                },
                "process_memory": {
                    "status": "complete",
                    "rss_bytes": 268435456,
                    "rss_anon_bytes": 260046848
                }
            }
        ]
    }
}

snapshot 字段：

process_memory 是与语言无关的进程内存计数，使用 status 和可选的 status_reason 表示可用性。以下字段均为可选，缺失表示不可用，不表示零：

3 - 异常事件字段

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

事件记录

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

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

CPU 调度

调度 tick 间隔

观测器：sched_tick。

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

适用场景

• 内核或驱动长时间关闭本地中断，或 hardirq/NMI 长时间占用 CPU。
• 虚拟机 vCPU 被宿主机长时间抢占，包括高 steal time 和调度停顿。
• SMI、固件停顿、clockevent 延迟投递或丢失等底层异常。

使用边界

成功进入 NO_HZ 的正常停 tick 会被过滤。普通 CPU 高负载或 softirq backlog 本身不等同于 tick 延迟。

阈值应高于目标机器的正常 tick 周期；事件栈仅表示延迟结束后首个 tick 的现场，需要结合 IRQ、steal time 和硬件指标定位根因。

示例（省略部分公共字段）：

{
    "uploaded_timestamp": "2025-06-11T16:05:16.251152703+08:00",
    "hostname": "***",
    "tracer_data": {
        "tick_interval_ns": 237328905,
        "tick_interval_threshold_ns": 10000000,
        "comm": "***-agent",
        "pid": 688073,
        "cpu": 1,
        "stack": "scheduler_tick/..."
    },
    "observed_timestamp": "2025-06-11T16:05:16.251+08:00",
    "tracer_type": "event",
    "region": "***",
    "tracer_name": "sched_tick"
}

软锁死

观测器：softlockup。

记录内核报告 softlockup 时的进程、CPU 和 NMI 回溯信息；这些信息不能单独确定致因进程。触发时间由内核 watchdog 配置决定。

重复事件的上报间隔从 10 分钟递增至最长 3 小时，期间仍累计事件计数。

示例（省略部分公共字段）：

{
    "tracer_data": {
        "cpu": 15,
        "pid": 12345,
        "comm": "kworker/15:0",
        "cpus_stack": "2025-06-10 14:30:22 sysrq: Show backtrace of all active CPUs\nNMI backtrace for cpu 15\n..."
    }
}

任务阻塞

观测器：hungtask。

可识别容器的 hungtask 事件附带容器 ID，否则保留主机输出；诊断堆栈仍为全机范围。计数说明见 HungTask 指标。

检测系统 hungtask 事件，采集 D 状态（不可中断睡眠）进程的内核栈及 CPU 回溯信息。重复事件的上报间隔从 10 分钟递增至最长 3 小时，期间仍累计事件计数。内核未提供 hung_task_timeout_secs 时不注册观测器；将该值设为 0 会禁用内核 hungtask 检测。

示例（省略部分公共字段）：

{
    "tracer_data": {
        "tid": 2567042,
        "comm": "kworker/u48:2",
        "cpus_stack": "2025-06-10 09:57:14 sysrq: Show backtrace of all active CPUs\nNMI backtrace for cpu 33\n...",
        "blocked_processes_stack": "task:java            state:D stack:    0 pid: 12345 ..."
    }
}

内存

OOM 终止

观测器：memory_oom_kill。

记录 OOM Killer 的触发进程（trigger）与被终止进程（victim），以及可获取的容器、cgroup 和宿主机内存信息。触发进程不一定是主要内存消耗者，需结合使用量和内存限制分析。

示例（省略部分字段）：

{
    "tracer_name": "memory_oom_kill",
    "tracer_data": {
        "trigger": {
            "memory_cgroup_css_addr": "0xff4b8d8be3818000",
            "container_id": "example-container",
            "container_hostname": "app-pod",
            "pid": 3218804,
            "comm": "java"
        },
        "victim": {
            "memory_cgroup_css_addr": "0xff4b8d8be3818000",
            "container_id": "example-container",
            "container_hostname": "app-pod",
            "pid": 3218745,
            "comm": "java",
            "cgroup": {
                "path": "kubepods.slice/...",
                "current": 2143289344,
                "max": 2147483648,
                "stat": {
                    "anon": 1509949440,
                    "file": 83886080
                },
                "events": {
                    "oom": 1,
                    "oom_kill": 1
                }
            }
        },
        "memory_snapshot": {
            "host_meminfo": {
                "MemAvailable": 3355443200,
                "Cached": 1073741824,
                "Slab": 268435456
            }
        }
    }
}

cgroup 位于 trigger 或 victim 内，仅在容器关联和快照读取成功时提供。宿主机快照也可能缺失；这些信息在用户态读取，并非与 OOM 发生时刻严格同步。

直接回收

观测器：memory_reclaim_events。

记录线程单次直接内存回收的耗时。try_to_free_pages 返回时，若本次调用超过阈值（默认 900 毫秒），则上报进程、线程和容器信息。未解析到容器的事件保留到主机事件流。黑名单使用注册名 memory_reclaim_events，落盘记录的 tracer_name 为 memory_reclaim。

示例（省略部分公共字段）：

{
    "tracer_name": "memory_reclaim",
    "tracer_data": {
        "pid": 1896137,
        "tid": 1896138,
        "comm": "java",
        "reclaim_duration_ns": 1412702917
    }
}

容器 ID 为空可能表示主机任务或容器归属未解析。已归属容器事件不重复输出到主机流。

网络

协议栈丢包

观测器：dropwatch。

检测内核网络协议栈中的丢包行为，输出丢包时的内核调用栈、网络五元组、TCP 状态等信息。可通过可选的调用栈过滤器抑制经本机验证的噪声模式。type 字段为兼容 TCP 丢包类型而预留，当前未赋值。

示例（省略部分公共字段）：

{
    "observed_timestamp": "2026-07-23T02:14:40.304775546Z",
    "tracer_data": {
        "drop_reason": "SKB_DROP_REASON_NOT_SPECIFIED",
        "source": "events",
        "comm": "kubelet",
        "pid": 1687046,
        "net_namespace_cookie": 123456789,
        "net_namespace_inum": 402653184,
        "netdev_queue_mapping": 3,
        "netdev_linkstatus": ["linkStatusUp"],
        "netdev_name": "eth0",
        "netdev_ifindex": 2,
        "packet_eth_proto": "0x0800",
        "packet_len_bytes": 1460,
        "layers": {
            "label": "IPv4/TCP",
            "ipv4": {
                "saddr": "10.79.68.62",
                "daddr": "10.134.72.4",
                "protocol": "TCP"
            },
            "tcp": {
                "sport": 8080,
                "dport": 49000,
                "seq": 1009085774,
                "ack_seq": 689410995,
                "sk_state": "ESTABLISHED"
            }
        },
        "stack": "kfree_skb/..."
    }
}

接收延迟

观测器：net_rx_latency。

记录 TCP 报文从驱动接收点到 __netif_receive_skb、tcp_v4_rcv 和用户态拷贝点的延迟。这三个值均从驱动起算，不是相邻观测点之间的耗时；默认阈值依次为 5、10、115 毫秒。达到对应阈值时记录端点、TCP 状态、序列号及延迟值。

默认排除宿主机网络命名空间，仅观测容器网络。

示例（省略部分公共字段）：

{
    "observed_timestamp": "2025-06-11T00:00:00Z",
    "tracer_data": {
        "comm": "nginx",
        "pid": 2921092,
        "latency_stage": "RX_STAGE_USERCOPY",
        "latency_ms": 95973,
        "latency_threshold_ms": 115,
        "tcp_state": "ESTABLISHED",
        "tcp_saddr": "10.156.248.76",
        "tcp_daddr": "10.134.72.4",
        "tcp_sport": 9213,
        "tcp_dport": 49000,
        "tcp_seq": 1009085774,
        "tcp_ack_seq": 689410995,
        "net_namespace_cookie": 123456789,
        "net_namespace_inum": 402653184,
        "packet_len_bytes": 26064
    }
}

网卡状态

观测器：netdev_events。

通过订阅内核 netlink RTM_NEWLINK 消息，检测网卡链路状态标志变化（如 AdminDown、CarrierDown），输出接口名称、链路状态、MAC 地址及驱动信息。观测器启动时会扫描 EventTracing.Netdev.DeviceList 中配置的网卡当前状态作为基线，后续仅上报状态变化事件。

示例（省略部分公共字段）：

{
    "tracer_data": {
        "ifname": "eth1",
        "index": 3,
        "linkstatus": "linkStatusAdminDown, linkStatusCarrierDown",
        "mac": "5c:6f:69:34:dc:72",
        "start": false,
        "driver": "ixgbe",
        "driver_version": "5.1.0-k",
        "firmware_version": "3.25 0x80000421 1.2163.0"
    }
}

LACP 状态

观测器：netdev_bonding_lacp。

仅在系统存在 IEEE 802.3ad bonding 接口时启用。LACP（Link Aggregation Control Protocol）状态变化时，读取并记录 /proc/net/bonding/ 下所有 bonding 接口的状态，包括模式、MII 状态、Actor/Partner 协商参数和 Slave 链路状态。

落盘记录的 tracer_name 为 lacp，配置黑名单使用注册名 netdev_bonding_lacp。

示例（省略部分公共字段）：

{
    "tracer_name": "lacp",
    "tracer_data": {
        "content": "/proc/net/bonding/bond0\nEthernet Channel Bonding Driver: v4.18.0...\nBonding Mode: IEEE 802.3ad Dynamic link aggregation\nMII Status: down\n..."
    }
}

发送队列超时

观测器：netdev_txqueue_timeout。

检测网卡发送队列超时（TX queue timeout）事件，记录发生超时的队列索引、设备名称和驱动名称，用于排查发送方向的设备、驱动或链路异常。

示例（省略部分公共字段）：

{
    "tracer_data": {
        "queue_index": 3,
        "device_name": "eth0",
        "driver_name": "ixgbe"
    }
}

兼容性

OOM 名称迁移

OOM kill 追踪器现命名为 memory_oom_kill（此前为 memory_oom，更早为 oom），需同步更新黑名单、事件过滤器和告警查询。

指标前缀现为 huatuo_bamai_memory_oom_kill_，替代 huatuo_bamai_memory_oom_ 及更早的 huatuo_bamai_oom_，需同步更新指标仪表盘和记录规则。

历史事件保留原名称，跨版本查询需匹配这三个名称；内置事件仪表盘已覆盖三者。

4 - 硬件事件字段

本文说明 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}"
    }
}

严重级别

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

MCE 同时设置 DEFERRED 和 UC 时，优先归为 UncorrectedDeferred。

事件详情

以下字段位于解析后的 tracer_data.info 中。

MCE

寄存器与 Bank 的含义依 CPU 型号而异，诊断时需结合对应处理器手册。

MCE 阈值中断

EDAC

ACPI GHES

非标准错误部分（NVDIMM、CXL 以及各厂商自定义载荷）可能超出复制的窗口。raw_data 只包含该错误部分起点之后实际可用的字节：长度会按剩余窗口截断；记录声明的长度有效时，窗口末尾未使用的字节不会作为载荷输出。窗口还要容纳记录固定字段和起点之前的数据，因此它不是每条记录的 raw_data 容量。data_len 仍上报内核记录中的原始长度。偏移和长度都来自内核记录，使用前会先做边界约束，因此畸形事件不会输出窗口之外的字节。

PCIe AER

错误名称描述上报的现象，不能直接推断为设备损坏。以下列出当前解析器识别的状态值。

可纠正错误

不可纠正错误

ARM GHES

ARM_GHES 记录的严重级别为 unknown；平台可用性限制见采集范围。

5 - Profiling API

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

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。

查询能力

创建任务前，建议先查询服务端支持的剖析类型、语言、CPU 模式、内存模式和运行参数：

curl -sS \
  -H "Authorization: Bearer ${API_TOKEN}" \
  "${API_BASE}/v1/profiling/capabilities"

data.items 是随版本发布的静态能力表，每项包含：

当前 c、c++ 和 go CPU 剖析支持 oncpu、offcpu，java 和 python 仅支持 oncpu。内存剖析支持以下组合：

创建任务

POST /v1/profiling 的 JSON 参数如下：

即使请求内容相同，每次请求也会创建一个新 Job。超过每节点或进程级活动 Job 配额时返回 HTTP 429。

创建宿主机 Go CPU 剖析任务：

curl -sS -i \
  -X POST \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cpu",
    "language": "go",
    "mode": "oncpu",
    "scope": "host",
    "duration_seconds": 60,
    "hostname": "node-01"
  }' \
  "${API_BASE}/v1/profiling"

创建容器内 Java 存活对象剖析任务：

curl -sS -i \
  -X POST \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "memory",
    "language": "java",
    "mode": "object_usage",
    "scope": "container",
    "duration_seconds": 60,
    "container_id": "9f4c2f1a8b7d",
    "hostname": "node-01"
  }' \
  "${API_BASE}/v1/profiling"

创建成功返回 201 Created，Location 响应头指向新任务，响应体包含后续查询所需的任务 ID：

{
  "data": {
    "request_id": "<profile-job-id>",
    "hostname": "node-01",
    "duration_seconds": 60,
    "scope": "host",
    "type": "cpu",
    "language": "go",
    "mode": "oncpu",
    "status": "pending",
    "created_at": "2026-08-24T10:00:00Z",
    "updated_at": "2026-08-24T10:00:00Z"
  }
}

JOB_ID="<profile-job-id>"

查询任务

任务列表

GET /v1/profiling 支持以下查询参数：

查询最新的 20 个 Profiling Job：

curl -sS -G \
  -H "Authorization: Bearer ${API_TOKEN}" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0" \
  "${API_BASE}/v1/profiling"

服务端固定只返回 Profiling Job，并按 created_at 倒序排列。data.items 是任务数组，data.limit 和 data.offset 是实际使用的分页参数； data.has_more 表示是否还有下一页。非管理员只能查看自己创建的任务。

任务详情

GET /v1/profiling/:request_id 返回单个任务：

curl -sS \
  -H "Authorization: Bearer ${API_TOKEN}" \
  "${API_BASE}/v1/profiling/${JOB_ID}"

任务信息位于 data 字段：

任务状态如下：

terminal.outcome 可取 completed、failed、stopped 或 unknown。failed 时通过 terminal.reason 和 terminal.message 定位原因； stopped 表示主动停止，结果可能不完整；unknown 表示 Apiserver 无法确认 Operation 最终状态，但持久发布的结果仍可能可用。

operation_lost 和 execution_timed_out 是 terminal.reason 的原因码，不是 Job 状态。其他失败原因包括等待启动或停止超时、Node 不可用、执行容量超过上限、 启动或执行失败、表示 Apiserver 构造的 Node 请求无效的 invalid_node_request，以及协议错误。

获取结果

GET /v1/profiling/:request_id/raw 仅在持久发布标记仍存在时返回 terminal.outcome 为 completed 或 unknown 的 Job 原始剖析窗口。发布标记 不存在或已经过期时返回 result_not_found。活动状态返回 result_not_ready； failed 和 stopped 返回 result_unavailable。

数据量可能较大，可以直接保存到文件：

curl -sS \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -o profile-raw.json \
  "${API_BASE}/v1/profiling/${JOB_ID}/raw?limit=100&offset=0"

剖析窗口位于响应体的 data.items 字段；data.limit、data.offset 和 data.has_more 描述分页。每条记录包含 uploaded_timestamp、started_timestamp、 profile_type 和兼容 pprof 的 profile 数据。 已持久发布但内容为空的结果仍返回成功，items 为空数组。显式 limit=0 返回参数 错误；只有未传 limit 才使用默认值。limit 默认值为 20， 最大值为 100。编码后的 Profile 数据超过 64 MiB 时返回 413 result_too_large，调用方应减小 limit 后重试。

火焰图每批读取并合并 100 个窗口，每次请求总上限为 100000 个窗口。一小时每秒产生 一个窗口时，全部 3600 个窗口都会参与合并。超过 100000 个窗口时返回错误，提示缩小 时间范围或过滤条件；查询或合并失败都不返回部分火焰图。原始 Profile 列表仍按 Job 查询，其每页上限不限制完整火焰图的聚合数量。

停止任务

停止是异步意图，pending、running 或已经处于 stopping 的 Job 均可接收：

curl -sS \
  -X POST \
  -H "Authorization: Bearer ${API_TOKEN}" \
  "${API_BASE}/v1/profiling/${JOB_ID}/stop"

成功返回 200 OK 和当前 Job 快照。终态 Job 返回 409 Conflict。由于结果可能 不完整，stopped Job 不提供结果查询。

统一火焰图查询

Grafana 使用 /v1/profiling/flamegraph/ 下的 Pyroscope 兼容 Protobuf 接口。 SelectMergeStacktraces 的标签选择器必须指定 scope="host" 或 scope="container"。 region 是 Agent 配置的区域，hostname 仅表示采集节点，不隐含宿主机范围。 容器查询使用 container_id 或单个任务 id 定位目标；宿主机查询不能携带容器条件。 例如 {region="example",hostname="node-01",scope="container",container_id="…",id="…"}。

每个标签只接受一个等值条件。在本接口上，通配值 *、all 和空字符串只表示取消该标签 的限制，因此 {scope="host",hostname="*",id="job-1"} 仍只选中一个任务，scope 依旧必填。 重复同一个等值条件会被接受，而 {hostname="host-a",hostname="host-b"} 这类互相矛盾的 同名条件会返回 400，错误信息同时给出两个值，因为一次查询无法同时选中两台主机。 使用 = 以外运算符的条件（包括 hostname!="*"）同样会被拒绝。

统一面板 UID 为 continuous-profiling，变量顺序为 Region、节点、范围、容器、指标、任务。 趋势图与火焰图使用相同任务过滤。容器选择 All 时，任务仍限定到一个目标； physical_usage 始终要求单个任务并只取最新快照。 任务摘要使用 pyroscope.yaml 的 Infinity 数据源，需与 Pyroscope 数据源配置相同的 API token。 result_url 包含从已存储窗口取得的 Region 和实际指标；没有窗口的结果不返回该链接。

6 - profiler 命令行参数

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

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

通用参数

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

采集参数

硬件 PMU 事件或采样不受支持时，命令退出码为 1，标准错误以 Error: hardware_pmu_unavailable: 标识该错误；权限及其他启动错误不使用此标识。

日志参数