通用函数执行追踪工具通过装饰器/proxy拦截函数调用，生成结构化trace记录，支持上下文传播、跨异步/进程链路串联、opentelemetry兼容输出、按需采样与敏感字段脱敏，零侵入、低开销、高适配性。
实现一个通用的函数执行追踪工具，核心在于不侵入业务代码、能动态捕获调用关系、支持多种语言环境，并保留足够上下文（如参数、返回值、耗时、调用栈）。它不是日志打印，而是结构化观测。
利用代理与装饰器拦截函数入口
在 Python、JavaScript 等支持运行时函数重写的语言中，可通过装饰器或 Proxy 拦截目标函数。关键不是“改写原函数”，而是“包裹并透传”。例如 Python 中：
- 用 @trace 装饰器标记需追踪的函数，内部生成唯一 trace_id 并记录开始时间
- 捕获 *args, **kwargs，但避免直接序列化大对象（可只记录类型+长度）
- 调用原函数后，捕获返回值（或异常）、结束时间，组装为一条 trace 记录
- 支持嵌套：通过线程/协程局部变量或 contextvars 传递当前调用链上下文
自动注入调用关系与上下文传播
单次调用容易记录，难点在于跨函数、跨异步任务、甚至跨进程的链路串联。需要轻量级上下文传播机制：
- 每次进入被追踪函数时，检查是否存在父 trace_id；若无则新建，若有则继承并生成子 span_id
- 对异步操作（如 await、Promise.then），需在回调入口显式恢复上下文（例如使用 asyncio.current_task().get_coro() 提取 context）
- HTTP 请求等外部调用，将 trace_id 注入请求头（如 X-Trace-ID），下游服务解析后继续链路
- 避免全局变量污染，优先使用语言原生上下文抽象（如 Python 的 contextvars、JS 的 AsyncLocalStorage）
输出结构化数据而非日志文本
追踪数据最终要用于分析，不能只写 console 或文件。应统一输出为标准格式：
- 每条记录包含：span_id、parent_span_id、trace_id、func_name、start_us、end_us、args_summary、return_summary、error（如有）
- 支持导出为 OpenTelemetry 兼容的 OTLP 格式，或简化为 JSON 行（ndjson），便于后续接入 Prometheus、Jaeger 或自建存储
- 提供内存缓冲 + 批量上报机制，避免高频调用拖慢主流程；失败时可降级为本地文件暂存
- 默认关闭，通过环境变量（如 TRACE_ENABLE=1）或运行时开关控制，不影响生产性能
按需过滤与采样，兼顾可观测性与开销
全量追踪代价高，必须支持精细化控制：
- 支持函数名白名单（如只追踪 user_service.*）、错误触发（仅当抛异常时展开调用链）、慢调用采样（耗时 >500ms 才记录）
- 采样策略可动态配置：固定率（如 1%）、基于 trace_id 哈希、或根据业务标签（如 user_type=admin 全量）
- 提供实时开关接口（如 HTTP POST /trace/enable），方便线上问题排查时临时开启
- 记录时跳过敏感字段（如 password、token），通过正则或标注声明脱敏规则
不复杂但容易忽略：真正的通用性不在功能多，而在适配成本低——开发者只需加一个装饰器或一行初始化，就能获得跨模块、跨调用类型的追踪能力。
