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

3.0 KiB
Raw Blame History

参数使用跟踪模块说明

简要说明如何使用新添加的 douyin.utils.param_usage_tracker 模块来记录参数调用位置。

  1. 直接记录单个参数位置
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)。

  1. 用装饰器自动记录函数调用参数
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)
  1. 读取记录

可以在调试脚本或 REPL 中使用 read_entries() 来读取并解析记录文件:

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:

PARAM_TRACK_ALL=1 python run_cli.py --help

在 Windows PowerShell 中:

$env:PARAM_TRACK_ALL = '1'
python run_cli.py --help

注意:全局跟踪使用 sys.settrace 实现,会对性能产生显著影响,建议仅用于短时调试或在受控环境下使用。跟踪记录默认写入 state/param_usage.json(逐行 JSON)。

性能与范围控制建议:

  • 在仅需跟踪少数模块时,优先使用 @track_call() 装饰器或在关键位置调用 track_param(...),以降低运行开销。
  • 若启用全局跟踪,请在完成诊断后关闭(退出进程)以避免长期性能下降。

查看与转换记录示例:

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,可以作为独立脚本使用来查看记录或静态扫描代码:

示例:

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 的调用位置。