MLflow × Claude Code使用mlflow-claude-code status查看 Tracing 生效配置【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow导读mlflow-claude-code status是 MLflow Claude Code 集成中用于查看当前 MLflow Tracing 配置状态的 CLI 命令它在仓库中以一个 Claude Code Skillskills/status/SKILL.md的形式提供给 Agent 使用Agent 运行该命令后即可向用户准确总结「Tracing 是否启用、配置来自哪个层级、当前生效的 Tracking URI 与 Experiment 设置」。本文以该 Skill 文档为核心结合仓库源码完整讲解命令的输出字段、配置来源优先级、配置文件位置与故障排查方法帮助你快速定位 Claude Code 会话的 Tracing 配置从何而来、为何生效、如何修正。status Skill 的定位Claude Code 会话的「体检工具」在 MLflow Claude Code 集成npm 包mlflow/claude-code源码位于 libs/typescript/integrations/claude-code中Skills 目录下提供了两个互补的 Agent 技能skills/setup/SKILL.md负责配置MLflow Tracing运行mlflow-claude-code setupskills/status/SKILL.md负责查看当前生效的 Tracing 配置运行mlflow-claude-code status。statusSkill 的 frontmatter 中标注了disable-model-invocation: true说明它属于手动/显式触发的辅助技能而非 Agent 自动调用的工具其description为Show the current MLflow tracing configuration for Claude Code。当用户询问「Tracing 开没开」「配置写在哪」「现在连的哪个 Tracking Server / Experiment」时Agent 就应执行本 Skill 定义的动作。status 与 setup 形成闭环先 setup 写入配置再 status 验证生效结果。这也是本文要重点展开的「查看 验证」能力。运行命令mlflow-claude-code status按 SKILL.md 的定义核心操作只有一条命令mlflow-claude-code status该命令由 CLI 入口 src/cli.ts 分发当第一个位置参数为status且未附带--help/-h时调用runStatus()。命令本身不读取任何额外参数全部配置信息来自环境变量与 Claude 的 settings.json 文件因此它可以随时执行、用于快速体检当前环境。提示执行mlflow-claude-code status --help会输出完整命令用法setup 的选项与示例、status 的说明该命令输出到 stderr不影响脚本解析。输出字段逐一解读runStatus()的实现位于 src/commands/setup.ts实际执行时先调用getEffectiveTracingConfig()计算合并后的有效配置然后逐行打印。典型输出如下MLflow Tracing Status Enabled: true Source: project Settings file: /path/to/repo/.claude/settings.json Tracking URI: http://localhost:5000 Experiment ID: 42 Experiment name: claude-code-traces Trace location: my_catalog.my_schema.my_prefix Workspace: my-workspace各字段含义与取值逻辑如下对应TracingConfig接口见 src/config.ts字段含义取值逻辑EnabledTracing 是否启用由MLFLOW_CLAUDE_TRACING_ENABLED决定true/1/yes不区分大小写、会先 trim视为启用未配置时为false见isTruthysrc/config.tsSource配置生效来源三选一environment环境变量/project项目级 settings/user用户级 settings无任何配置时为noneSettings file配置文件路径仅当来源为project或user时输出指向./.claude/settings.json或~/.claude/settings.jsonTracking URIMLflow 追踪服务地址来自MLFLOW_TRACKING_URI如http://localhost:5000、databricks、databricks://profile未配置显示not setExperiment ID实验 ID来自MLFLOW_EXPERIMENT_ID未配置显示not setExperiment name实验名称来自MLFLOW_EXPERIMENT_NAME可选未配置显示not setTrace locationUC Trace 目标可选catalog.schema.table_prefix三段式仅配置时输出WorkspaceDatabricks 工作区可选来自MLFLOW_WORKSPACE未配置显示not set如果最终Enabled为false命令还会追加一行提示Tracing is disabled. Run mlflow-claude-code setup to configure it.这正好衔接 skills/setup/SKILL.md 的引导流程。配置来源与优先级environment project userstatus输出的核心价值在于Source 字段它揭示了「当前配置到底是从哪一层读到的」。这个判定逻辑在getEffectiveTracingConfig()中完整实现src/config.ts分为三步读取两个 settings 作用域分别读取用户级~/.claude/settings.jsonprojectLocalfalse与项目级./.claude/settings.jsonprojectLocaltrue解析其中env段得到两份TracingConfiggetScopeTracingConfigsrc/config.ts。settings 内合并以 user 配置为基础若项目级配置包含任何 Tracing 键tracking URI、experiment ID/name、trace location、enabled 任一非空则用项目级整体覆盖user 级。也就是说只要项目里配置过 Tracing项目级就优先于用户级。环境变量最高优先process.env中出现的键逐字段覆盖上面的合并结果并且只要环境变量里出现任一 Tracing 相关键source就判定为environment否则依次回退到project/user/none。这套优先级在测试中得到了直接验证例如 tests/config.test.ts 的用例「lets environment variables override saved settings」settings 中保存了http://saved.example与 experiment 7而环境变量设置了http://override.example、experiment 99 与 enabledtrue最终getEffectiveTracingConfig返回 tracking URI 为 override 值、source: environment。而 tests/config.test.ts 的用例则验证了仅写项目 settings 时source为project且 experiment name 被保留。对排查的实际意义如果status显示Source: environment说明即使改动了 settings.json当前会话仍会受环境变量支配——这是最常见的「改了配置不生效」原因。配置文件位置与内容resolveSettingsPath()src/config.ts决定 settings 文件的写入与读取位置项目级--project/-p当前工作目录/.claude/settings.json只对当前仓库生效用户级--user/-uhome/.claude/settings.json对所有仓库生效。文件是标准 JSONTracing 配置统一放在env段由writeTracingSettings()写入src/config.ts示例{ env: { MLFLOW_CLAUDE_TRACING_ENABLED: true, MLFLOW_TRACKING_URI: http://localhost:5000, MLFLOW_EXPERIMENT_ID: 42, MLFLOW_EXPERIMENT_NAME: claude-code-traces, MLFLOW_TRACE_LOCATION: my_catalog.my_schema.my_prefix } }写入时注意两点细节MLFLOW_TRACE_LOCATION会先trim()再存储保证与解析逻辑一致而MLFLOW_EXPERIMENT_ID、MLFLOW_EXPERIMENT_NAME、MLFLOW_TRACE_LOCATION、MLFLOW_WORKSPACE在传入空值时会被删除而非保留空串见writeTracingSettings的 hasConfigValue 判断。loadSettings()在文件不存在时返回空对象而非报错因此未配置时status也能正常输出none状态。相关环境变量总览status输出的所有值都源自下表环境变量常量定义见 src/config.ts这些变量既可由 shell 导出也可写入 Claude settings.json 的env段环境变量作用有效值示例MLFLOW_CLAUDE_TRACING_ENABLED总开关决定Enabled字段true/1/yes不区分大小写MLFLOW_TRACKING_URIMLflow Tracking Server 地址http://localhost:5000、databricks、databricks://profileMLFLOW_EXPERIMENT_ID复用已有实验数字 ID如42MLFLOW_EXPERIMENT_NAME按名称复用或创建实验如claude-code-tracesMLFLOW_TRACE_LOCATION可选Databricks Unity Catalog Trace 目标catalog.schema.table_prefix三段式MLFLOW_WORKSPACE可选Databricks 工作区名如my-workspaceMLFLOW_ENABLE_ASYNC_TRACE_LOGGING异步 Trace 日志开关默认在初始化时置为true除非已显式设置其中MLFLOW_TRACKING_URI的合法性校验在isValidTrackingUri()src/config.ts允许字面量databricks、databricks://profile前缀或http:/https:绝对 URL其余一律视为非法MLFLOW_TRACE_LOCATION必须是恰好三个非空、点分隔的段parseTraceLocationsrc/config.ts因为 SDK 不会自动创建 UC Trace 目标三段缺一不可。status 与 setup、Stop-hook 的协同从「配置」到「真正生效」status展示的是静态配置快照而真正让 Tracing 跑起来的是 Stop-hook 的运行时流程。理解这条链路才能读懂 status 输出背后的含义setup 写配置mlflow-claude-code setup校验参数scope、tracking URI、experiment 二选一、trace location 格式见 src/commands/setup.ts并通过resolveExperiment()src/config.ts把 experiment name 解析为 ID不存在则调用MlflowClient.createExperiment创建最后写入 settings.json。Stop-hook 读配置Claude Code 每次会话结束时触发 src/hooks/stop.ts它依次调用isTracingEnabled()和ensureInitialized()前者即getEffectiveTracingConfig().enabled后者校验 tracking URI、experiment并调用init()初始化mlflow/core同时把MLFLOW_ENABLE_ASYNC_TRACE_LOGGING默认置为true。只有当 enabled 为真且初始化成功才会processTranscript上报 Trace。status 验证状态如果步骤 2 没有产生 Trace跑一次mlflow-claude-code status即可快速定位是开关没开、URI 缺失、experiment 缺失还是 trace location 格式错误——这正是本 Skill 文档要求 Agent「summarize the effective configuration」的用途。值得注意的运行时细节当MLFLOW_TRACE_LOCATION被设置时SDK 走 UC table-prefix 目的地V4 Trace ID否则走实验支持的 V3 路径见 src/config.ts 的注释说明ensureInitialized()还实现了基于JSON.stringify的初始化缓存相同配置只初始化一次。常见问题与排查建议结合源码status输出可用于快速排查以下场景Enabled: falseMLFLOW_CLAUDE_TRACING_ENABLED未设置或值非法非true/1/yes。按提示运行mlflow-claude-code setup重新配置。Source: environment但期望来自 settings 文件说明 shell 中存在 Tracing 相关环境变量它们覆盖了 settings.jsonstatus中同时显示的实际 URI/experiment 即环境变量的值。删除或修正对应环境变量即可恢复 settings 生效。Experiment ID: not set且Experiment name: not setensureInitialized()会报错MLFLOW_EXPERIMENT_ID or MLFLOW_EXPERIMENT_NAME is not setTrace 不会上报。两者至少配置其一。Tracking URI: not setensureInitialized()会报错MLFLOW_TRACKING_URI is not set若配置了databricks://profile需确保对应 profile 可用。Trace location格式错误parseTraceLocation失败时初始化会中止并在 stderr 提示必须为catalog.schema.table_prefix格式。Trace 未落库但 status 一切正常检查 experiment 解析name 是否成功映射为 ID、以及MLFLOW_ENABLE_ASYNC_TRACE_LOGGING是否被外部显式设为false默认会自动开启测试见 tests/config.test.ts。小结mlflow-claude-code status是一条零参数、可重复执行的配置体检命令它汇总环境变量与两级 settings 文件输出「启用状态 配置来源 生效的 Tracking URI / Experiment 设置」并明确告诉你在 Tracing 关闭时下一步该做什么。配合 skills/setup/SKILL.md 的配置流程以及 src/config.ts 中 environment project user 的合并逻辑开发者可以快速回答「Claude Code 的 Trace 到底发到了哪里、为什么没有发」这个集成排障中最核心的问题。【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
