# MStools

**Repository Path**: adrian0711/mstools

## Basic Information

- **Project Name**: MStools
- **Description**: MindSpore tools
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2025-07-25
- **Last Updated**: 2025-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 分布式调试工具集

本仓库包含三个用于 PyTorch / MindSpore 分布式训练的调试与追踪工具，帮助开发者更高效定位问题。

---

## 📂 目录

- [概述](#概述)
- [1. 分布式调试器（`pdb_utils`）](#1-分布式调试器pdb_utils)
- [2. 执行路径追踪器（`execution_tracker`）](#2-执行路径追踪器execution_tracker)
- [3. 函数调用堆栈打印器（`trace_print`）](#3-函数调用堆栈打印器trace_print)
- [4. 版本快照工具](#-版本快照工具)
- [文档链接](#文档链接)
- [许可证与联系](#许可证与联系)

---

## 概述

| 工具模块                | 功能说明                 |
|---------------------|----------------------|
| `pdb_utils`         | 在指定 rank 设置断点，暂停其他进程 |
| `execution_tracker` | 跟踪函数进入 / 退出与耗时       |
| `trace_print`       | 当指定函数被调用时打印调用堆栈      |

---

## 1. 分布式调试器（`pdb_utils`）

在多卡环境下，对指定 rank 进入 `pdb` 调试，其它 rank 阻塞或跳过。

### 🔧 使用方法

在训练脚本前插入：

- **MindSpore**：

```bash
  source tools/debug_utils/dist_debug.sh
  exit
````

* **PyTorch**：

```bash
  source tools/debug_utils/dist_debug_pt.sh
  exit
```

在代码中添加断点：

```python
from pdb_utils import breakpoint_, clear_

breakpoint_()          # 阻塞其他进程
breakpoint_(False)     # 非阻塞模式
clear_()               # 手动解除阻塞
```

👉 全文见：[分布式调试说明](./dist_debug/distributed_debug.md)

---

## 2. 执行路径追踪器（`execution_tracker`）

跟踪选定项目目录下函数的进入、退出与执行时间，并以缩进方式显示层级。

### 示例

```python
from execution_tracker import ExecutionTracer

with ExecutionTracer():
    main()
```

👉 查看源码：[execution\_tracker.py](./trace_print/execution_tracker.py)

---

## 3. 函数调用堆栈打印器（`trace_print`）

当指定函数（通过函数名或正则匹配）被调用时，自动打印当前堆栈。

### 示例

```python
from trace_print import TraceContext

with TraceContext('train_step', regex=['forward.*']):
    main()
```

👉 查看源码：[trace\_print.py](./trace_print/trace_print.py)

---

## 4. 版本快照工具

复制 [`version_control`](./version_control) 目录下的文件至MindSpeed-Core-MS仓， 然后：

- `export_version.sh`：导出所有子仓当前 commit 的信息。
- `import_version.sh`：按版本快照还原各仓到指定 commit。

适用于调试、精度对齐或实验复现等场景。

📖 [详细说明请见 → version_control/README.md](./version_control/README.md)

## 文档链接

* 📖 [分布式调试文档](./dist_debug/distributed_debug.md)
* 🧭 [执行路径跟踪器](./trace_print/execution_tracker.py)
* 📌 [函数堆栈打印工具](./trace_print/trace_print.py)

---

## 许可证与联系

本项目基于 Apache License 开源。
如有问题或建议，欢迎提 Issue 或提交 PR。