mcpField
I
instrumenting-with-mlflow-tracing

instrumenting-with-mlflow-tracing

github.com/mlflow开发821.1k 次安装2 天前更新
代码仓库

关于 instrumenting-with-mlflow-tracing

instrumenting-with-mlflow-tracing 是用于为应用配置和核验 MLflow tracing 的技能，涵盖框架集成、手动 span、追踪读取和超时约束。它强调沿用现有后端与目标，并核实已持久化的应用追踪。

主要功能

  1. 01检查运行环境与追踪目标
  2. 02配置匹配的框架追踪
  3. 03为关键应用操作添加 span
  4. 04运行请求并保存追踪 ID
  5. 05限时读取并检查持久化追踪

适用场景

  1. 01为应用请求捕获 LLM 与工具调用
  2. 02检查检索和路由步骤的追踪
  3. 03验证 Databricks 上的追踪读取
  4. 04遇到权限或仓库超时时报告未验证结果

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mlflow/skills --skill instrumenting-with-mlflow-tracing

安装后在 Claude Code 中输入/instrumenting-with-mlflow-tracing确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
advanced-patterns.md
databricks.md
distributed-tracing.md
feedback-collection.md
production.md
python.md
root-span-previews.md
typescript.md

详细介绍

埋点 MLflow 跟踪

复用有效的跟踪来进行调查或评估。

前提条件

  • 检查入口点、语言／框架、SDK 版本、跟踪 URI、实验和部署身份。
  • 保留目标位置和提供方。显式应用目标会覆盖继承的环境值；助手遥测可能使用另一个实验。
  • 根据运行时阅读 Python 或 TypeScript。

第 1 步：检查目标位置（仅限 Databricks）

对于 OSS 或 SageMaker，保留已配置的后端并继续执行第 2 步。

  • 编辑前阅读 UC 设置；验证身份验证和工作区。
  • 复用显式指定的目标位置；否则，在预配前确定架构选项。
  • 自动发现可访问的数据仓库。默认使用 UC；只有在明确请求时才使用旧版存储。

第 2 步：启用框架跟踪

  • 在执行前启用对应的集成。LangGraph 使用 mlflow.langchain.autolog()，而不是 mlflow.langgraph.autolog()。
  • 不要再次包装已自动跟踪的节点、工具或模型。仅对未捕获的工作或外层应用边界使用手动 span。

第 3 步：捕获应用工作

  • 跟踪有意义的根、LLM、检索、工具、路由和外部 I/O（文件／队列）。 跳过工具函数、配置和日志噪声。
  • 对手动 span 显式捕获实际相关的输入／输出；导出前进行脱敏。

第 4 步：运行一个请求

  • 运行一个有代表性的请求；记录开始和结束的纪元毫秒时间戳。
  • 在进程内立即保存其跟踪 ID：Python 中使用 mlflow.get_last_active_trace_id()；TypeScript 中使用活动 span 的 ID。
  • 在回读前将跟踪 ID 写入文件或捕获的标准输出；如果进程被取消，则保留该 ID。 不要为了找回 ID 而重新运行。

验证

  • 获取一条已持久化的应用跟踪，而不是本地 span 或旧跟踪。

  • 为回读设置 60 秒的实际运行时间进程截止时间，包括刷新、SDK 重试、请求和退避。 到期后终止，除非用户明确要求进行更深入的故障排查。

  • 工具执行超时／线程等待超时不会取消调用。若无法取消，请说明未执行后端验证。

  • 刷新一次（mlflow.flush_trace_async_logging() / await mlflow.flushTraces()）；获取已保存的 ID。

  • 如果没有 ID，则在已配置的实验中搜索一次，并设置运行时边界、max_results=1，且包含 spans。

  • 每次 UC 搜索都需要 trace.timestamp_ms；结果数量上限不会限制扫描范围。Python 的 search_traces() 没有 start_time 关键字参数。

对于 Python 回读，请根据已保存的运行值调整此配方，并在外部强制执行截止时间：

mlflow.flush_trace_async_logging()
if trace_id:
    trace = mlflow.get_trace(trace_id)
else:
    traces = mlflow.search_traces(
        locations=[experiment_id],
        filter_string=(f"trace.timestamp_ms >= {run_start_ms} "
                       f"AND trace.timestamp_ms <= {run_end_ms}"),
        max_results=1, return_type="list", include_spans=True,
    )
    trace = traces[0] if traces else None
assert trace is not None, "No persisted trace read back"
assert run_start_ms <= trace.info.request_time <= run_end_ms
assert trace.data.spans, "No spans captured"

  • 检查预期的根／图、模型、检索和工具 span，以及实际 I/O。确认是应用的请求，而不是评分器或助手遥测。

  • 根据返回的元数据检查实验／位置；如果没有实验 ID，则检查已绑定的 UC 位置。

  • 复用返回的 spans；成功后停止。可用的 agent-evaluation/scripts/validate_tracing_runtime.py 脚本可以在相同截止时间内替代此检查，但不要再额外执行一次审计。

  • 只有在原定时间预算内出现明确且快速的修复方案时，才最多重试一次。

  • 遇到提供方密钥缺失、身份验证／权限错误、数据仓库超时或 RESOURCE_EXHAUSTED/429 时停止。

  • 不要并行搜索、重复运行 Agent、直接执行 UC SQL、调用原始 REST、使用替代凭据或回退到其他数据仓库。

  • 报告操作／错误、已捕获的 ID、成功项和未验证结果。请求缺失的前提条件，不要索要密钥。

  • 如果后端验证受阻，保留埋点更改；在跟踪验证通过前暂停评估。

返回已验证的跟踪 ID／链接和观察到的 spans。对于 Databricks，请使用已验证跟踪的 URL 规则，不要只提供实验链接。不要将未经验证的链接标记为证明。

参考资料

  • 部署、异步导出、采样：生产环境。

  • 异步／线程上下文、脱敏、捕获的错误或链接：高级模式。

  • 跨服务父级传播：分布式追踪。

  • 与追踪关联的用户评分：反馈收集。

  • 难以阅读的非聊天根预览：根跨度预览。

  • 解释捕获的行为：debug-agent；实现用户请求的行为修复：fix-agent-issue，并附上追踪证据。这些都是可选的后续任务。

  • 其他集成：自动追踪文档。请检查已安装版本的签名和类型。

  • 主题缺失或已移动：llms.txt。文档不可用时：使用本地操作指南和已安装 API 的内省；如果仍无法确定正确性，请停止。

评论

支持 Markdown