Python 日志工具，通过装饰器自动追踪代码执行流程并生成 Mermaid JS 时序图，支持异步、分布式追踪、FastAPI 及 LangChain 集成。
核心定位#
MermaidTrace 是一个专为 Python 设计的执行流可视化工具，通过装饰器技术（@trace、@trace_class、@trace_interaction）在运行时捕获函数调用，自动转换为标准 Mermaid JS 时序图。旨在解决传统文本日志在理解复杂逻辑时的局限性。
主要特性#
追踪能力#
- 装饰器驱动：
@trace、@trace_interaction、@trace_class（全覆盖类公共方法） - 自动时序图生成：函数调用自动转换为 Mermaid Sequence Diagram 语法
- 异步原生支持：无缝支持 asyncio 协程和并发场景
- 智能折叠：自动识别循环调用并折叠（如
func (x10)），避免图表爆炸 - 第三方库补丁：
patch_object无需修改源码即可追踪外部库方法
隐私与安全#
- 内置
DataMasker自动数据脱敏 - 支持配置敏感字段掩码（password, token 等）
capture_args=False参数防止敏感参数被记录
性能控制#
- 可配置采样率（
sample_rate）控制追踪百分比 - 异步模式（
async_mode=True）将日志写入转移到后台线程 - 队列大小限制（
queue_size=1000）防止高流量场景内存溢出
分布式追踪#
- 支持 W3C Trace Context 标准
- 支持 B3 和自定义 X-Trace-ID headers
- FastAPI 中间件支持跨服务追踪传播
可视化与 UI#
- FastAPI 驱动的交互式 Web 预览界面
- 实时渲染（集成 mermaid.js）
- 支持缩放和平移（svg-pan-zoom）
- Server-Sent Events (SSE) 实现自动刷新
- 目录浏览和多文件切换
框架集成#
FastAPI#
- 零配置 HTTP 请求追踪中间件
- 支持 header 传播
LangChain#
MermaidTraceCallbackHandler支持 Chains, LLMs, ChatModels, Tools, Retrievers- 参与者栈正确追踪嵌套调用和返回箭头
- 支持 RAG 和 Agent 工作流可视化
日志管理#
RotatingMermaidFileHandler：基于大小轮转TimedRotatingMermaidFileHandler：基于时间轮转- 自动分割
.mmd文件 overwrite参数支持应用重启时清空图表文件
错误处理#
- 异常捕获完整 Python traceback
- 以 Note 形式在 Mermaid 图表中显示错误详情
安装与使用#
# 基础安装
pip install mermaid-trace
# FastAPI 集成
pip install mermaid-trace[fastapi]
# LangChain 集成
pip install mermaid-trace[langchain]
快速开始#
from mermaid_trace import trace, configure_flow
configure_flow("my_flow.mmd")
@trace(source="User", target="AuthService")
def login(username):
return verify_db(username)
login("admin")
CLI 预览#
mermaid-trace serve my_flow.mmd # 预览单个文件
mermaid-trace serve . # 预览目录
适用场景#
- 遗留代码理解：快速生成未知代码库的执行路径图
- 自动化文档：保持技术文档时序图与代码逻辑 100% 同步
- 调试并发与递归：可视化异步任务交错和递归深度
- 微服务交互可视化：追踪微服务之间调用关系
- LLM 应用监控：可视化 LangChain Chain、Agent 决策及 RAG 检索过程
项目信息#
- Python 版本：>=3.10（支持 3.10-3.14）
- 实现支持：CPython, PyPy
- 最新版本：v0.7.0
- 测试覆盖率：>90%
- 类型注解：100% Mypy 覆盖