Files
douyin_guaji-main/docs/param_usage.md
T
Your Name 95b4517bdd feat: Enhance logging and parameter tracking capabilities
- Refactor `gui_core.py` to improve code readability and maintainability by adding line breaks for long statements.
- Introduce `inspect_lines.py` script for inspecting specific line ranges in files.
- Add `generate_param_locations.py` to scan the repository and generate a report of function definitions, argparse parameters, and tracking calls.
- Implement `param_usage_tool.py` for analyzing `param_usage.json` records and scanning code for tracking calls.
- Create `simulate_reservation_preempted_flow.py` and `simulate_reservation_preempted_flow_dynamic.py` to validate behavior of reservation logic under specific conditions.
- Add global parameter tracking feature in `run_cli.py` to enable detailed usage tracing.
2026-01-03 19:12:58 +08:00

97 lines
3.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 参数使用跟踪模块说明
简要说明如何使用新添加的 `douyin.utils.param_usage_tracker` 模块来记录参数调用位置。
1) 直接记录单个参数位置
```python
from douyin.utils.param_usage_tracker import track_param
def some_fn():
cfg_value = 42
track_param("important_threshold", cfg_value)
# ... 业务逻辑 ...
```
调用 `track_param` 会把一条记录追加到 `state/param_usage.json`,包含时间戳、调用文件、行号、函数名和参数的 repr。文件为逐行 JSON(NDJSON)。
2) 用装饰器自动记录函数调用参数
```python
from douyin.utils.param_usage_tracker import track_call
@track_call()
def process(item, flag=False):
# 每次调用时,会把 func 名、定义位置、调用位置与参数记录到 state/param_usage.json
pass
process(1, flag=True)
```
3) 读取记录
可以在调试脚本或 REPL 中使用 `read_entries()` 来读取并解析记录文件:
```python
from douyin.utils.param_usage_tracker import read_entries
entries = read_entries(limit=200)
for e in entries:
print(e)
```
注意:为了兼容并发与减少文件读写冲突,记录以逐行 JSON 追加方式保存(NDJSON)。如需转换为 JSON 数组,可用脚本读取所有行并写入新的 JSON 文件。
启用全局跟踪(可选)
如果你想在程序运行期间自动记录仓库内所有函数的调用位置与参数,可以在启动前设置环境变量 `PARAM_TRACK_ALL=1`:
```bash
PARAM_TRACK_ALL=1 python run_cli.py --help
```
在 Windows PowerShell 中:
```powershell
$env:PARAM_TRACK_ALL = '1'
python run_cli.py --help
```
注意:全局跟踪使用 `sys.settrace` 实现,会对性能产生显著影响,建议仅用于短时调试或在受控环境下使用。跟踪记录默认写入 `state/param_usage.json`(逐行 JSON)。
性能与范围控制建议:
- 在仅需跟踪少数模块时,优先使用 `@track_call()` 装饰器或在关键位置调用 `track_param(...)`,以降低运行开销。
- 若启用全局跟踪,请在完成诊断后关闭(退出进程)以避免长期性能下降。
查看与转换记录示例:
```python
from douyin.utils.param_usage_tracker import read_entries
entries = read_entries(limit=500)
for e in entries:
print(e)
# 将 NDJSON 转为 JSON 数组
with open('state/param_usage.json','r',encoding='utf-8') as f:
lines = [json.loads(l) for l in f if l.strip()]
with open('state/param_usage_array.json','w',encoding='utf-8') as f:
json.dump(lines, f, ensure_ascii=False, indent=2)
```
快速查看工具:
仓库中包括一个独立工具 `tools/param_usage_tool.py`,可以作为独立脚本使用来查看记录或静态扫描代码:
示例:
```bash
python tools/param_usage_tool.py show --limit 200
python tools/param_usage_tool.py show --param important_threshold
python tools/param_usage_tool.py tail
python tools/param_usage_tool.py scan track_param
```
该工具不依赖运行时跟踪器,可独立拿来分析 `state/param_usage.json` 或查找代码中 `track_param`/`track_call` 的调用位置。