python装饰器本质是高阶函数：接收函数为参数并返回新函数；通过闭包包装原函数，在入口出口动态插入监控逻辑，结合functools.wraps保留元信息、异步容错上报及外置配置，实现可复用、可配置、非侵入的自动埋点。

用高阶函数实现自动埋点装饰器，核心是把监控逻辑从业务代码里“抽出来”，变成可复用、可配置、不干扰主流程的旁路能力。它不靠改业务函数体，而是靠在函数调用入口和出口动态插入统计与上报逻辑，从而让监控覆盖率从“手动加、漏了就没了”变成“一加全加、漏不了”。

为什么高阶函数是自动埋点的基础

装饰器本质就是高阶函数：接收一个函数（func），返回另一个函数（wrapper）。这个结构天然支持“包裹”行为——在 wrapper 里控制 func 的执行时机、捕获它的输入输出、记录耗时与异常，再统一处理。没有高阶函数机制，就无法在不侵入原函数的前提下完成这些动作。

• wrapper 函数形成闭包，能安全持有 func 和装饰器参数（如 service_name、reporter）
• 所有被装饰函数共享同一套埋点模板，避免每个地方重复写 try/except/time.perf_counter()
• 函数作为一等对象，可被传入、返回、动态组合，支撑采样率、阈值、开关等运行时策略

自动埋点装饰器必须做对的三件事

只加 @trace 不等于真埋点。很多团队埋点覆盖率上不去，不是没加装饰器，而是装饰器本身没写对。

• 必须用 try/except/finally 包裹执行过程：只记开始时间、直接 return func() 会导致异常吞没、耗时为 0、返回值/错误类型无法采集。正确做法是在 finally 中更新结束时间，在 except 中捕获异常类型，在 return 前收集结果
• 必须用 functools.wraps 保留元数据：否则日志里看到的是 "wrapper" 而非真实函数名，OpenAPI 工具无法生成接口文档，监控平台查不到归属函数，等于埋了也白埋
• 上报必须异步且容错：不能用 requests.post 同步发请求，也不能在 except 里 raise 新异常。应设 timeout、捕获所有上报异常、仅打 debug 日志，确保埋点失败不影响主逻辑

如何让覆盖率真正“自动拉满”

覆盖率不是靠人一个个加 @trace 实现的，而是靠工程化手段批量覆盖。

• 对路由层统一装饰：FastAPI 的 @app.get 加一层中间件式装饰器，或 Flask 的 before_request + 自动匹配 endpoint，让所有 HTTP 接口默认带 trace_id、耗时、状态码埋点
• 按模块批量装饰：用 inspect 扫描某个 package 下所有函数，对符合命名规范（如 *_handler、*_service）的自动应用性能装饰器
• 结合框架生命周期：在 Celery task 定义前自动注入 @track，或在 SQLAlchemy event.listen 中对 commit/rollback 做统一耗时与错误统计

关键配置必须外置，不能硬编码

硬编码 reporter=logging.info() 或 sample_rate=1.0 的装饰器，上线后没法关、没法调、没法对接 Sentry/OpenTelemetry，最终会被开发绕过，导致覆盖率断崖下跌。

• 所有参数（service_name、slow_threshold_ms、sample_rate、reporter）都应通过装饰器工厂传入
• reporter 必须是可替换的 Callable，方便单元测试 mock，也支持灰度开关：reporter=lambda x: send_to_sentry(x) if is_prod else lambda x: None
• 动态 trace_id 应从 contextvars.ContextVar 读取，而非 threading.local 或全局变量，确保异步/协程场景下上下文不串