# hgvmctl

**Repository Path**: shilei-wang/hgvmctl

## Basic Information

- **Project Name**: hgvmctl
- **Description**: hgvmctl绑核工具使用方法说明
- **Primary Language**: Shell
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-29
- **Last Updated**: 2025-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# hgvmctl

## 介绍

hgvmctl是一个功能强大的命令行工具，提供以下实用功能：
- CPU拓扑查询
- 进程亲和性和调度管理
- 虚拟机查询、亲和性管理和自动编排
- Kubernetes Pod查询、cgroup查询、亲和性管理和自动编排

## 基础概念

在使用hgvmctl进行绑核操作之前，需要了解以下基础概念：

### 1. CCX (Core Complex)
CCX是产生于AMD处理器中的一个概念，指的是包含多个CPU核心的计算单元。在AMD的Zen架构中，一个CCX通常包含4个或8个物理核心，这些核心共享L3缓存。CCX是AMD处理器中CPU核心组织的基本单元，不同CCX之间的通信需要通过Infinity Fabric进行，因此了解CCX结构对于优化性能非常重要。

### 2. NUMA Node (Non-Uniform Memory Access Node)
NUMA节点是非统一内存访问架构中的基本单元。在NUMA系统中，CPU和内存被组织成多个节点，每个节点包含一个或多个CPU核心以及一部分物理内存。访问本地节点内存的速度比访问远程节点内存要快得多。在高性能计算场景中，合理分配进程到NUMA节点可以显著提升性能。

### 3. Socket
Socket是指物理CPU插槽，一个Socket中可以安装一个物理CPU。在多Socket系统中，每个Socket可能包含多个核心和CCX。Socket之间通过QPI（Intel）或Infinity Fabric（AMD）等互连技术通信。理解Socket结构对于优化多处理器系统的性能至关重要。

### 4. 为什么要进行绑核

绑核（CPU Affinity）是将进程或线程绑定到特定CPU核心的技术，主要原因包括：

- **性能优化**：减少CPU缓存失效，提高缓存命中率
- **资源隔离**：避免关键进程与其他进程争用CPU资源
- **实时性保证**：减少进程迁移开销，提高响应速度
- **NUMA优化**：确保进程在指定NUMA节点上运行，减少跨节点内存访问
- **功耗管理**：通过集中负载，使其他CPU核心进入节能状态
- **中断优化**：将特定中断绑定到特定CPU，避免中断处理的负载不均

## 安装

### 系统要求
- Linux系统（支持cgroup v1和v2）
- 需要配置了Ftrace的内核（用于性能分析工具）
- 安装perf命令（用于性能分析工具）

### 安装方式
1. 下载预编译的二进制文件，并chmod +x hgvmctl后即可使用

## 使用说明

### 基本命令结构

```bash
hgvmctl [命令] [子命令] [选项]
```

### 主要功能模块

#### 1. CPU拓扑查询

##### 查看CPU拓扑（表格视图）
```bash
hgvmctl cpu ls
```

##### 查看CPU拓扑（树形结构）
```bash
hgvmctl cpu tree
```

#### 2. 进程绑核管理

##### 查看进程亲和性信息
```bash
hgvmctl process affinity -p <pid>
```

##### 绑定进程到特定CPU
```bash
# 绑定进程1234到CPU 0和2-5
hgvmctl process bind -c 0,2-5 -p 1234

# 绑定进程1234及其所有线程到CPU 0和2-5
hgvmctl process bind -c 0,2-5 -p 1234 -a

# 清除进程1234的绑定
hgvmctl process bind -p 1234 --clear

# 清除进程1234及其所有线程的绑定
hgvmctl process bind -p 1234 -a --clear
```

##### 触发进程重调度
```bash
hgvmctl process resched -p <pid>
```

#### 3. 虚拟机绑核管理

##### 列出运行中的虚拟机
```bash
hgvmctl vm ls
```

##### 查看虚拟机亲和性信息
```bash
hgvmctl vm affinity
```

##### 绑定虚拟机到特定CPU
```bash
# 绑定名为my-vm的虚拟机到CPU 0和3-5
hgvmctl vm bind --cpu-list 0,3-5 --name my-vm

# 绑定CPU并立即触发重调度
hgvmctl vm bind --cpu-list 0,3-5 --name my-vm --resched-now

# 从JSON配置文件配置虚拟机亲和性
hgvmctl vm bind --config /path/to/myvm.json

# 显示配置文件示例
hgvmctl vm bind --show-config-example

# 从记录文件恢复虚拟机亲和性
hgvmctl vm bind --restore --name my-vm
hgvmctl vm bind --restore-all

# 刷新亲和性记录
hgvmctl vm bind --refresh-affinity-record

# 显示亲和性记录内容
hgvmctl vm bind --show-affinity-record
```

##### 触发虚拟机重调度
```bash
hgvmctl vm resched --name <vm-name>
```

##### 查看虚拟机cgroup路径
```bash
hgvmctl vm cgroup --name <vm-name>
```

#### 4. 容器/POD绑核管理

##### 列出运行中的POD资源信息
```bash
hgvmctl container ls
```

##### 查看POD亲和性信息
```bash
hgvmctl container affinity --pod <namespace/podname>
```

##### 绑定POD到特定CPU
```bash
# 绑定POD中所有容器到CPU 0-3
hgvmctl container bind --pod namespace/podname --cpuset-cpus 0-3

# 绑定POD中特定容器到CPU 4-7
hgvmctl container bind --pod namespace/podname --container mycontainer --cpuset-cpus 4-7

# 绑定CPU并立即触发重调度
hgvmctl container bind --pod namespace/podname --cpuset-cpus 0-3 --resched-now

# 清除POD中所有容器的CPU绑定
hgvmctl container bind --pod namespace/podname --cpuset-cpus 0-$(($(nproc --all)-1))
```

##### 触发容器重调度
```bash
hgvmctl container resched --pod <namespace/podname>
```

##### 查看容器cgroup路径
```bash
hgvmctl container cgroup --pod <namespace/podname>
```

#### 5. 自动编排功能

##### 自动编排QoS虚拟机的CPU亲和性
```bash
hgvmctl vm orche
```

##### 自动编排保证型QoS POD的CPU亲和性
```bash
hgvmctl container orche
```

#### 6. 性能分析工具

hgvmctl集成了Brendan Gregg的性能分析工具集合，包括：

##### 内核函数追踪
```bash
# 统计内核函数调用次数
hgvmctl funccount -h

# 追踪内核函数调用图
hgvmctl funcgraph -h

# 追踪慢于阈值的内核函数
hgvmctl funcslower -h

# 追踪内核函数调用
hgvmctl functrace -h
```

##### 系统调用追踪
```bash
# 追踪进程执行
hgvmctl execsnoop -h

# 追踪kill系统调用
hgvmctl killsnoop -h

# 追踪open系统调用
hgvmctl opensnoop -h

# 统计系统调用
hgvmctl syscount -h
```

##### 文件系统和磁盘I/O分析
```bash
# 显示页面缓存命中/未命中统计
hgvmctl cachestat -h

# 显示磁盘I/O大小直方图
hgvmctl bitesize -h

# 汇总块设备I/O延迟
hgvmctl iolatency -h

# 追踪块设备I/O
hgvmctl iosnoop -h
```

##### 网络分析
```bash
# 显示TCP重传
hgvmctl tcpretrans -h
```

### 高级用法

#### 批量操作
可以使用配置文件对多个虚拟机或容器进行批量绑核操作。

#### 自动化脚本
可以将hgvmctl命令集成到自动化脚本中，实现动态资源分配和优化。

#### 监控和调试
利用性能分析工具集，可以对系统性能进行深入分析和调试。

### 版本信息
```bash
hgvmctl version
```

### 获取帮助
```bash
hgvmctl -h
hgvmctl [command] -h
hgvmctl command-tree  # 显示命令层次结构
```

## 示例用例

### 用例1：为高优先级进程绑定专用CPU
```bash
# 假设PID为1234的进程是高优先级实时应用
hgvmctl process bind -c 0-3 -p 1234 -a
hgvmctl process resched -p 1234
```

### 用例2：为虚拟机分配独占CPU资源
```bash
# 为关键业务虚拟机分配专用CPU
hgvmctl vm bind --cpu-list 8-15 --name critical-vm --resched-now
```

### 用例3：为Kubernetes Pod设置CPU亲和性
```bash
# 为关键业务Pod分配专用CPU
hgvmctl container bind --pod production/my-app --cpuset-cpus 16-23 --resched-now
```

## 注意事项

1. 在执行绑核操作前，请确保目标CPU可用且未被其他关键进程占用
2. 修改CPU亲和性可能影响系统性能，请在生产环境操作前充分测试
3. 使用--resched-now选项会立即触发重调度，可能导致短暂的性能波动
4. 对于虚拟机和容器操作，请确保有适当的权限
5. 性能分析工具需要特定的内核配置和权限

## 故障排除

- 如果绑核操作失败，请检查目标进程是否存在
- 如果虚拟机操作失败，请确认虚拟机正在运行
- 如果容器操作失败，请验证命名空间和Pod名称
- 对于权限相关错误，请使用sudo或确保有足够的权限

## 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

## 版本

hgvmctl version 1.5.0

## 附加工具脚本

本项目还包含两个实用的shell脚本，用于辅助CPU绑核管理：

### 1. auto_bind_cpus.sh

这是一个高级的CPU亲和性绑定脚本，专门用于智能绑定Java进程到CPU核心。主要功能包括：

- **智能拓扑感知**：自动检测系统的硬件拓扑结构（Socket、NUMA节点、L3缓存/CCX）
- **优先级绑定**：根据以下优先级规则绑定进程：
  1. 优先级1：同一L3缓存组（近似CCX）
  2. 优先级2：同一NUMA节点
  3. 优先级3：同一Socket
- **动态管理**：运行过程中动态管理可用CPU池
- **持续监控**：持续监控新进程和终止的进程
- **自动重平衡**：当进程终止时自动重新优化所有现有绑定
- **可配置参数**：支持通过命令行参数自定义核心数、进程匹配模式和检查间隔

使用方法：
```bash
# 基本用法
./auto_bind_cpus.sh

# 指定参数
./auto_bind_cpus.sh -c 4 -p "org.apache.spark.executor.CoarseGrainedExecutorBackend" -i 10
```

参数说明：
- `-c, --cores`：分配给每个进程的CPU核心数（默认：4）
- `-p, --pattern`：用于识别目标Java进程的模式（默认：org.apache.spark.executor.CoarseGrainedExecutorBackend）
- `-i, --interval`：检查进程变化的间隔时间（秒）（默认：10）

### 2. kill_auto_bind_cpus.sh

这是一个简单的辅助脚本，用于终止正在运行的auto_bind_cpus.sh进程。它通过查找进程名并发送kill信号来停止auto_bind_cpus.sh脚本的执行。

使用方法：
```bash
./kill_auto_bind_cpus.sh
```

该脚本会查找所有包含"auto_bind_cpus.sh"的进程并使用kill -9命令强制终止它们。