mcpField
M
mlflow-trace-instrumentation

mlflow-trace-instrumentation

github.com/mlflow其他8215 次安装2 天前更新
代码仓库

关于 mlflow-trace-instrumentation

用于为 Python 和 TypeScript 应用添加并验证 MLflow 跟踪的技能，涵盖插桩选择、跟踪捕获和限时后端验证，并保留已配置的目标位置。

主要功能

  1. 01检查运行时、SDK 和跟踪设置
  2. 02按框架启用跟踪
  3. 03捕获应用及 I/O 跨度
  4. 04保存跟踪 ID 供读取
  5. 05在时限内验证已持久化跟踪

适用场景

  1. 01评估前为应用添加插桩
  2. 02调查代表性应用请求
  3. 03检查跟踪导出和持久化跨度

安装

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

$npx skills add https://github.com/mlflow/skills --skill mlflow-trace-instrumentation

安装后在 Claude Code 中输入/mlflow-trace-instrumentation确认已加载。

包含的文件

除 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 步：运行一次请求

  • 运行一个有代表性的请求；记录开始和结束的 epoch 毫秒时间戳。
  • 在进程内立即保存其追踪 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，并包含 Span。

  • 每次 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 位置。

  • 复用返回的 Span；成功后停止。

  • 仅在原始时间预算内进行一次重试，且须先找到明确的快速修复方法。

  • 如果缺少提供方密钥、出现身份验证／权限错误、数据仓库超时或 RESOURCE_EXHAUSTED／429，则停止。

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

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

  • 如果后端验证受阻，保留插桩变更；在追踪得到验证前暂停评估。

返回已验证的追踪 ID／链接及观察到的 Span。对于 Databricks，请使用已验证追踪 URL 规则，不要使用仅指向实验的链接。不要将未验证的链接称为证据。

参考资料

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

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

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

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

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

  • 解释捕获到的行为：mlflow-trace-analysis；实现请求的行为修复：mlflow-agent-improvement，并附上追踪证据。这些是可选的后续任务。

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

  • 缺失／已移动的主题：llms.txt。文档不可用：使用本地方案和已安装 API 的自省；如果仍无法确定正确性，请停止。

评论

支持 Markdown