Skip to content

fix: log runtime LLM metadata#24

Merged
1aal merged 1 commit into
apecloud-basefrom
fix/runtime-llm-metadata-structured-log
Jun 11, 2026
Merged

fix: log runtime LLM metadata#24
1aal merged 1 commit into
apecloud-basefrom
fix/runtime-llm-metadata-structured-log

Conversation

@1aal

@1aal 1aal commented Jun 11, 2026

Copy link
Copy Markdown
Collaborator

背景

Runtime 已经通过结构化事件输出 LLM request/response metadata,用于排查工具型诊断中 skill、tool schema、tool choice 和 provider 返回之间的链路问题。为了后续线上定位时可以直接按 runId 检索 Runtime 日志,本 PR 在保持事件输出不变的基础上,同步输出一条安全的结构化日志。

改动范围

  • 在 Runtime worker 发出 llm.request.metadata / llm.response.metadata 事件时,同步向 stderr 写入 JSON structured log。
  • 日志字段仅使用已有白名单元数据,包括 run/session/user/conversation 标识、provider/model/base_url_host、skill/tool 名称与计数、tool_choice、finish_reason、tool_calls 计数、输出 token 等。
  • 新增回归测试,确认日志记录可按 runId 检索,并且不会包含完整 prompt、tool schema、API key、用户输入或工具输出。

查看方式

发版后,拿到异常 turn 对应的 Runtime runId 后,可以直接在 Hermes Runtime pod 日志中检索:

RUN_ID=run_xxx
kubectl --context cloud-dev logs -n kb-cloud deploy/hermes-agent --since=2h \
  | grep 'runtime.llm.metadata' \
  | grep "$RUN_ID"

如果需要查看 JSON 字段,可以裁掉 Runtime Manager 日志前缀后再交给 jq

RUN_ID=run_xxx
kubectl --context cloud-dev logs -n kb-cloud deploy/hermes-agent --since=2h \
  | grep 'runtime.llm.metadata' \
  | grep "$RUN_ID" \
  | sed -E 's/^.*runtime-manager worker\[[^]]+\]: //' \
  | jq .

重点字段:

  • request 侧:skills_countskill_namesskill_prompt_presencetools_counttool_namestool_choicerequest_char_countapprox_input_tokens
  • response 侧:finish_reasonassistant_tool_calls_countassistant_tool_namesoutput_tokens

常见判断:

  • tools_count=0:工具 schema 没有真正下发,需要查 Runtime toolset/schema 链路。
  • tools_count>0finish_reason=stopassistant_tool_calls_count=0:工具已下发,但模型没有选择 tool call。
  • assistant_tool_calls_count>0 但 Cloud 没有 tool action:再回查 Runtime event pump / Cloud projection。

安全边界

不会记录以下内容:

  • API key / Authorization
  • 完整 system prompt / user prompt
  • 完整 request / response
  • 完整 tool schema
  • kubeconfig 路径或内容
  • 用户输入正文、工具 stdout/stderr 或报告正文

验证

  • uv run pytest tests/runtime_manager/test_registry.py -k "llm_request_metadata or llm_response_metadata or llm_metadata_log"
  • uv run pytest tests/runtime_manager
  • uv run ruff check runtime_manager/worker_main.py tests/runtime_manager/test_registry.py
  • python3 -m py_compile runtime_manager/worker_main.py
  • git diff --check
  • git diff --check origin/apecloud-base...HEAD

非目标

  • 不改变 Agent loop、工具调用策略或模型选择策略。
  • 不新增前端展示或数据库持久化。
  • 不扩大 metadata 字段范围。

@1aal 1aal marked this pull request as ready for review June 11, 2026 09:53
@1aal 1aal merged commit 978b4de into apecloud-base Jun 11, 2026
7 checks passed
@1aal 1aal deleted the fix/runtime-llm-metadata-structured-log branch June 11, 2026 09:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant