为 Python/TypeScript LLM 应用接入…

当需要给 agent 或 LLM 应用加可观测性追踪、或为后续 agent 评估做准备时，用 MLflow Tracing 埋点并确认 trace/span 真正落库。

适用场景

解决思路

1. 先判断项目语言：Python 项目读 references/python.md，TypeScript/JavaScript 项目读 references/typescript.md；不确定就看项目里是 package.json（TS）还是 requirements.txt/pyproject.toml（Python）。
2. 若目标是 Databricks，编辑代码前先读 references/databricks.md，并配置 UnityCatalog 的 trace location；只调用 mlflow.set_tracking_uri("databricks") 和 mlflow.set_experiment(...) 而不设 trace location 会落到旧的 workspace experiment 存储，不算把 trace 发到 Databricks。
3. 在 Databricks 上先检查项目/环境配置里已有的候选目标、可选表前缀和 SQL warehouse；绑定 experiment 或创建 UC 资源前，按 references/databricks.md 的 schema 选择流程让用户选已有 schema 或新建，除非用户已明确指定目标，绝不随意挑一个可访问的 schema，缺失的必填值要先问清，不要静默回退到旧存储（仅当用户明确要求时才用旧存储）。
4. 首次运行前验证认证和目标 workspace：用 `databricks current-user me --profile <name>`（认证过期会失败且不打印 token），用 `python -c "import mlflow; print(mlflow.get_tracking_uri())"` 确认是 databricks 或 databricks://<name>；认证过期就运行 `databricks auth login --profile <name>`，绝不在 agent 记录里打印或保存 `databricks auth token` 的输出。
5. 按价值决定埋点范围：要追踪根操作（主入口、顶层 pipeline、工作流步骤）、LLM 调用（chat completion、embedding）、检索（向量库查询、文档获取、搜索）、工具/函数调用（API、数据库、web 搜索）、agent 决策（路由、规划、工具选择）、外部服务（HTTP API、文件 IO、消息队列）。
6. 跳过过于细粒度、只会增加噪音的操作：简单数据变换（dict/list 操作）、字符串格式化/解析/校验、配置加载与环境初始化、日志或指标上报、纯工具函数（数学、排序、过滤）。判断标准是：对调试和定位问题重要的操作才追踪。
7. 埋点后必须验证：先运行被埋点的代码，让至少一个被追踪的操作触发。
8. 用 `mlflow.search_traces()` 或 `MlflowClient().search_traces()` 确认 trace 出现在 experiment 中；若找不到，先调用 `mlflow.flush_trace_async_logging()` 刷新后台队列。示例：`import mlflow; mlflow.flush_trace_async_logging(); traces = mlflow.search_traces(locations=["<experiment_id>"]); print(f"Found {len(traces)} trace(s)"); assert len(traces) > 0, "No traces were logged — check tracking URI and experiment settings"`。
9. 确认 span 被捕获而非空壳：`trace = traces.iloc[0]; spans = mlflow.get_trace(trace.trace_id).data.spans; print(f"Trace has {len(spans)} span(s)"); for span in spans: print(f" - {span.name} ({span.span_type})")`。
10. 向用户报告结果：说明找到多少 trace 和 span 并确认追踪生效；在 Databricks 上按 references/databricks.md 的 URL 指引给出本次运行中已验证 trace 的可点击链接（只给 experiment 链接打不开具体 trace）。
11. 若没有 trace 出现，按顺序排查：①验证跑在 trace 导出之前——trace 日志默认异步，运行后立刻 search_traces 可能返回 0，先调 `mlflow.flush_trace_async_logging()`；②tracking URI 未设置——agent 运行前是否调了 `mlflow.set_tracking_uri(...)`，否则 trace 会进本地 ./mlruns；③autolog 警告——`mlflow.autolog()` 或框架专用 autolog 是否在 setup 时报警告，检查 stderr 里的 patch 失败；④experiment ID 错误——确认传给 search_traces() 的 ID 与代码运行时激活的 experiment 一致（用 `mlflow.get_experiment_by_name(...)` 核对）；⑤网络/认证问题——进程能否连到 tracking server，检查日志里的连接错误或 401/403。自动化校验可用 agent-evaluation/scripts/validate_tracing_runtime.py。
12. 用 `mlflow.log_feedback()` 在 trace 上记录用户评分和评论，捕获 trace ID 返回给客户端，并做 LLM-as-judge 自动评估，用于评估、调试和微调（详见 references/feedback-collection.md）。
13. 生产部署参考 references/production.md：环境变量配置、低延迟应用的异步日志、采样配置（MLFLOW_TRACE_SAMPLING_RATIO）、轻量 SDK（mlflow-tracing）、Docker/Kubernetes 部署。
14. 高级模式参考 references/advanced-patterns.md：异步函数追踪、多线程上下文传播、用 span processor 做 PII 脱敏。
15. 分布式追踪参考 references/distributed-tracing.md：跨服务传播 trace context、客户端/服务端 header API。
16. 追踪就绪后，调试或改进 agent 行为时先读 span，不要只回退到读源码和输出文件；加载 fix-agent-issue skill，用 trace 作为证据定位 agent 实际收到/产出/决策了什么、应该怎样、为什么，再改代码，并把修复固化为回归测试。

适用边界 · 注意事项

• 不要追踪简单数据变换、字符串格式化/解析/校验、配置加载、日志/指标上报、纯工具函数等细粒度操作，只会增加噪音。
• 在 Databricks 上不要只设 tracking URI 和 experiment 而不配 UnityCatalog trace location，也不要静默回退到旧 workspace 存储，除非用户明确要求。
• 不要在 agent 记录中打印或持久化 `databricks auth token` 的输出。