Q: extending instrument_claude_agent_sdk() — scope review + landing strategy

未关闭
#1,908 2 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
25/100
Issue 类型
功能
描述清晰度
基本清楚
活跃度
冷清
技术栈
python
领域
observability

调研方向

首先阅读 logfire/_internal/integrations/claude_agent_sdk.py,以及 issue 中提到的相关 semconv、scrubbing、tests、VCR cassettes 和文档。确认 maintainer 偏好的范围和 landing 策略;在开始实现之前,就变更集合和 PR 结构达成一致即表示完成。

由索引模型根据 Issue 内容生成。

描述

Hi @alexmojaki — I've been using instrument_claude_agent_sdk() for a few weeks and built out coverage in my fork
(oneryalcin/logfire@main) for gaps I hit (see: https://github.com/oneryalcin/logfire/pulls?q=is%3Apr+is%3Aclosed) . Before opening a PR I want to check scope and landing strategy with you, since you own the integration (#1799 / #1809).

Inventory

12 scoped changes, all under logfire/_internal/integrations/claude_agent_sdk.py plus adjacent semconv / scrubbing / docs / tests:

Stream-source coverage

  • Server-side tool blocks (web_search, web_fetch, code_execution, advisor, ...) as tool_call / tool_call_response parts on the chat span — currently dropped.
  • RateLimitEvent state transitions and MirrorErrorMessage as logs under invoke_agent.

Root invoke_agent span enrichment

  • ClaudeAgentOptions session config (model / permission_mode / max_turns / effort / cwd / system_prompt / ...).
  • Per-turn identifiers from AssistantMessage on chat spans.
  • ResultMessage agent-run metadata closing the root span (subtype, errors, structured_output, model_usage, tools_used, ...).

Hook coverage — the 5 SDK hooks the integration doesn't surface today

  • UserPromptSubmit, Stop, PreCompact, Notification, PermissionRequest as logfire log records under invoke_agent.
  • can_use_tool outcomes (PermissionResult allow/deny) and PreToolUse.updatedInput mutations reflected on the execute_tool span's gen_ai.tool.call.arguments.

Lifecycle + control methods (none currently traced)

  • connect, disconnect, set_model, set_permission_mode, rewind_files, stop_task, interrupt, mcp.reconnect, mcp.toggle.
  • receive_messages parity with receive_response (currently a black hole).

Subagents (Task tool)

  • subagent {agent_type} span keyed by agent_id (opens on SubagentStart, closes on SubagentStop).
  • Task started / Task progress / Task {status} SystemMessage events as logs.
  • AgentDefinition metadata when configured (claude.agent.model, .system_prompt, .tools, ...).
  • Tool calls and per-turn chat spans inside a subagent re-parented under the subagent envelope (via agent_id / parent_tool_use_id).

Plumbing

  • New claude.* semconv constants in _internal/integrations/llm_providers/semconv.py.
  • Allowlist additions in BaseScrubber.SAFE_KEYS for model-generated and operator-set fields (text / errors / structured_output / usage / etc).
  • claude-agent-sdk>=0.1.62 dev pin + [tool.uv.exclude-newer-package] entry, matching the existing pattern.
  • New + refreshed VCR cassettes; ~3,500 lines of test additions; new section in docs/integrations/llms/claude-agent-sdk.md.

Size

~+6,000 / -400 against pydantic/logfire@main, scoped entirely to
this integration + plumbing. 98 tests pass, make format / make lint
/ make typecheck clean.

Two questions

  1. Scope — any of these you'd reject on principle? Specific ones I'd flag for sanity-check:
    • claude.stop.last_assistant_message / claude.subagent.last_assistant_message are captured via defensive .get() on undocumented wire fields (the SDK type definitions don't declare them; the integration silently skips if a future SDK release renames them).
    • Hook-event surfacing as logs adds noise to traces; some teams may
      want it gated behind a flag rather than always-on.
    • The gen_ai.tool.call.arguments overwrite on PreToolUse
      updatedInput mutation matches OTel Gen AI semconv (arguments =
      what the tool actually saw) but the original is preserved under
      claude.tool_call.arguments.original — wanted to flag the
      semantic choice.
  2. Cadence — happy to ship as one big PR or as a series of 4–6
    mapped to the groups above (stream → root-span → hooks → lifecycle
    → subagents → glue), each 200–800 lines. Recent feature PRs in this
    repo trend in that range, so the series probably matches your
    review rhythm better, but I'll defer to your preference.

No urgency on my side. Thanks for the original integration — solid
foundation to build on.

主要语言
Python
星标
4.6k
派生
376
平均合并
1 天 21 小时
30 天内合并 PR
124

环境准备

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

pydantic/logfire 的其他 Issue

查看 pydantic/logfire 的全部 Issue

相似的 Issue

更多 Python Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。