mem-scan
一个用于监控系统和 GPU 内存使用情况的命令行工具,特别适用于监控 Python 程序执行期间的内存特征。
功能特性
- 实时监控 CPU 内存和 GPU 内存使用情况
- 支持监控任意命令的执行过程
- 提供峰值、最小值和平均值统计
- 支持将报告保存为 JSON 格式
- 可配置监控间隔和 GPU 设备
- 支持静默模式执行
安装
使用 uv 安装(推荐)
# 从源码安装
uv pip install -e .
# 或者直接安装
uv pip install mem-scan
使用 pip 安装
pip install -e .
依赖项
psutil>=5.8.0- 系统内存监控pynvml>=11.0.0- GPU 内存监控
使用方法
基本用法
# 监控 Python 脚本执行
mem-scan python your_script.py
# 监控带参数的命令
mem-scan python train.py --batch-size 128 --epochs 10
# 监控模型量化过程
mem-scan python -m modelopt.onnx.quantization --onnx_path=model.onnx --quantize_mode=fp8
高级选项
# 指定 GPU 设备
mem-scan --gpu-id 1 python eval.py
# 调整监控间隔(秒)
mem-scan --interval 0.05 python train.py
# 保存报告到文件
mem-scan --output memory_report.json python inference.py
# 静默模式(不显示命令输出)
mem-scan --quiet --output report.json python benchmark.py
# 查看版本信息
mem-scan --version
# 查看帮助信息
mem-scan --help
输出示例
Starting memory monitoring for: python train.py --batch-size 128
GPU ID: 0, Interval: 0.1s
------------------------------------------------------------
============================================================
MEMORY USAGE REPORT
============================================================
Execution Time: 45.32 seconds
Return Code: 0
GPU Memory Usage:
Peak: 8.45 GB
Min: 0.12 GB
Avg: 6.78 GB
Host Memory Usage:
Peak: 12.34 GB
Min: 8.90 GB
Avg: 10.45 GB
Report saved to: memory_report.json
JSON 报告格式
当使用 --output 选项时,会生成包含详细信息的 JSON 报告:
{
"execution_time": 45.32,
"return_code": 0,
"memory_usage": {
"gpu_peak_gb": 8.45,
"gpu_min_gb": 0.12,
"gpu_avg_gb": 6.78,
"host_peak_gb": 12.34,
"host_min_gb": 8.90,
"host_avg_gb": 10.45
},
"command": "python train.py --batch-size 128",
"timestamp": "2024-01-20 14:30:45"
}
开发
开发环境设置
# 克隆仓库
git clone <repository-url>
cd mem_scan
# 使用 uv 安装开发依赖
uv pip install -e ".[dev]"
# 运行测试
pytest
# 代码格式化
black src/ tests/
# 类型检查
mypy src/
构建和发布
# 构建包
uv build
# 发布到 PyPI(需要配置认证)
uv publish
注意事项
- GPU 监控需要安装 NVIDIA 驱动和
pynvml库 - 如果没有 GPU 或无法初始化 GPU 监控,工具会显示警告但仍会监控 CPU 内存
- 监控间隔设置过小可能会影响被监控程序的性能
- 使用
--quiet模式时,被监控程序的输出会被捕获但不显示
许可证
MIT License
贡献
欢迎提交 Issue 和 Pull Request!
Metadata
Release files for mem-scan 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mem_scan-1.0.0.tar.gz | 5.7 kB | Without provenance | Details for mem_scan-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mem_scan-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for mem_scan-1.0.0-py3-none-any.whl |
Total release size: 12.8 kB
Release files / mem_scan-1.0.0.tar.gz
| Download URL | mem_scan-1.0.0.tar.gz |
|---|---|
| Size | 5.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
16659718d0c2bdb12f789fb05af52f4938224d4ce8fa941bf2c7c0a22cc7b3cb
|
|
BLAKE2b-256 checksum How to use checksums |
a50ea04707eaf6f812f729f6822d7eab678a2d6e9ee1270cdc99e24ff4b62763
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.0.0 CPython/3.12.7
|
Release files / mem_scan-1.0.0-py3-none-any.whl
| Download URL | mem_scan-1.0.0-py3-none-any.whl |
|---|---|
| Size | 7.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4b31122fc91ca2b73bb4514d2293e1addc9d16b2d31d5134117616ff885e470c
|
|
BLAKE2b-256 checksum How to use checksums |
ccb68bc33e0909b74c65aa57c7088f111620f886b93e71f6068aaf78ea7b9471
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.0.0 CPython/3.12.7
|
Security for mem-scan 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.