feat(claude-messages)!: emit invoke_agent, chat and execute_tool spans - #30
feat(claude-messages)!: emit invoke_agent, chat and execute_tool spans#30apucacao wants to merge 10 commits into
Conversation
|
bugbot run |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
0ccb68d to
a4e837e
Compare
|
bugbot run |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit a4e837e. Configure here.
|
bugbot run |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 80c5a66. Configure here.
|
bugbot run |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 80c5a66. Configure here.
|
bugbot run |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 80c5a66. Configure here.
|
bugbot run |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 914e2bb. Configure here.
|
bugbot run |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 0aeafc5. Configure here.
|
bugbot run |
|
bugbot run |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 4ad052e. Configure here.
|
bugbot run |
|
bugbot run |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 1ac5a89. Configure here.
|
bugbot run |
|
bugbot run |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 60586d4. Configure here.
|
bugbot run |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 60586d4. Configure here.
60586d4 to
a68b202
Compare
|
bugbot run |
|
bugbot run |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit a1833cd. Configure here.
|
bugbot run |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit a1833cd. Configure here.
One flat span per call, named claude.messages, becomes the tree the
TypeScript SDK emits: an invoke_agent root, one `chat {model}` child per
model turn, one `execute_tool {name}` child per tool call. A five-turn run
with tools was previously one span with one set of token counts, so per-turn
cost and latency were not recoverable from a trace at all, and a tool call
left no trace beyond its LD metric event.
BREAKING CHANGE: the span this handler emits is renamed from
`claude.messages` and `claude.messages.stream` to `invoke_agent`. Queries
that select on the old names will not match. Prompt and completion content is
no longer on spans unless the caller passes capture_content=True.
Span construction moved to spans.py so the tool loop reads as a tool loop
rather than as span bookkeeping with a provider call in the middle.
Tool spans take the root's context, not the chat span's, so they are siblings
of chat rather than nested inside it. Both parents are passed explicitly:
these handlers open a plain span rather than an active one, so there is no
ambient span for a child to inherit, and a host app with its own tracer
provider would otherwise get a flat trace.
The root keeps what only it can carry: the launchdarkly.* identity, the
feature_flag event, and the run's token total. It is the span a config-scoped
query finds, and summing the children requires having already found them. A
test asserts children carry none of it.
Cache tokens now reach the span. Anthropic reports cache reads and writes
beside input_tokens rather than inside it, so a turn that read 19,971 tokens
from cache and wrote 3,580 more reported 3. The chat span now reports 23,554
for that turn, and there is a test with those numbers in it.
The handler's return value keeps the cache fields unfolded, in Anthropic's own
names, because parse_usage folds exactly once; a pre-folded figure returned
alongside the fields would count the cache twice downstream. RawRunUsage
carries that shape and is named so it cannot be confused with the client's
SpanUsage-based RunUsage, which is cache-inclusive.
Finish reasons are mapped rather than passed through: end_turn becomes stop,
tool_use becomes tool_calls. A consumer grouping by this attribute across
handlers previously saw two names for one outcome.
A failed run now reports what its completed turns cost, on the root, but only
when a turn actually reported usage. All-zero attributes would assert the run
cost nothing, which a run whose first call died mid-flight cannot claim.
The streaming path gets a `finally`. A consumer that breaks out of the
iteration makes the generator skip `except` entirely, because GeneratorExit
inherits from BaseException, so the root span was never ended and never
exported: the whole run vanished from AI Config Monitoring along with the
feature_flag event it carries. Every span now ends through end_span_once, and
an abandoned one is marked and left UNSET rather than ERROR, because
LaunchDarkly's own metrics record neither a success nor an error for
abandonment and ERROR would put two dashboards in disagreement about one run.
The success tail sets status without ending, so the `finally` owns every end.
Ending twice is ignored by the OTel SDK but recorded as a diagnostic error,
and would hide a genuine leak.
Tests: the telemetry classes are rewritten rather than extended, because they
pinned the old flat span. The single shared MagicMock span is replaced with a
recorder that keeps one object per span, since the old approach could not tell
a parent from a child. 82 tests here, up from 64. The fake usage object now
declares only the fields Anthropic sets, so a handler cannot read a cache
field the provider never reported.
Not changed: the tool catalog is still unfiltered, unlike the TypeScript SDK,
which offers the model only tools that have a registered handler. That
difference predates this work and changes what the model is offered rather
than what the span reports.
…apper The wrapper never passed capture_content to the factory, so it stayed in kwargs and reached config(), which takes no such argument. A caller asking for content on spans got a TypeError rather than content. Lifted out alongside variables, which was already handled the same way and for the same reason: one configures the handler, the other belongs to the invocation, and config() accepts neither. Two tests, one per branch, asserting the flag reaches the factory and does not reach config(). Found by Bugbot on #33 against openai-agents. Five of the six wrappers had it; each is fixed in its own layer.
… its span The success-side content write and the span finish sat outside the try, so a raise while recording the result skipped both the finish and the failure path. The tool span was never ended, so the exporter never saw it: the run showed a root marked ERROR and no sign the tool had been called. Reachable rather than theoretical. Serialising a tool result raises TypeError whenever capture_content is on and the result is not JSON-serialisable, which is any object a handler happens to return. The TypeScript handler has always done this inside the try. I put it outside when porting, and the two handlers that copied this file's shape inherited it, so they are fixed in their own layers. Found by Bugbot on #34, against the handler that copied it rather than this one.
… reads Span construction moved to spans.py, which holds the real _HAS_OTEL. The handler kept its own copy, plus the two imports it needed, alive only by a noqa. Nothing read any of it. That mattered because the tests patched the dead one. 7 tests set handler._HAS_OTEL to False and believed they were exercising the install without the otel extra; the flag was unread, so they exercised nothing and passed either way. They now patch spans._HAS_OTEL, which is the flag start_root_span actually consults: with it patched, span creation returns None, and with it set it does not. Found by Bugbot on #32. Five of the six handlers carried the dead gate, and four had tests aimed at it.
The streaming finally closed the model span and the root, but the in-flight execute_tool span was held only by a local. except Exception does not see a CancelledError or a GeneratorExit, so a tool cancelled mid-flight left its span open and unexported: the trace showed a closed parent above a child that never arrived, which reads as a tool still running long after the run ended. Tracked in open_tool_span and abandoned in the finally, the same way the model span already was. The tracker is cleared on the two paths that end the span and deliberately not in a finally, because a finally would also clear it for the BaseException case, which is the one case where the outer finally is the only thing left to close it. Found by Bugbot on the openai-messages layer. This handler is where the pattern was copied from, so the same gap reached four of the six.
…guard The output content write and the span finish sat outside the try that fails the chat span, and the blocking path has no finally that could recover it. A raise while serialising the completion left the span open and unexported, so the trace showed an errored root with no model call at all, and the turn was dropped from the run total even though Anthropic had already billed it. Reachable through capture_content, where serialising any non-JSON-serialisable value raises TypeError. The usage is now accumulated straight after the provider returns, before anything that can raise, and every span write happens inside the guard. Two tests: the span still ends and reports ERROR, and the tokens survive. Found while checking whether the openai-messages defect Bugbot reported on #32 reached the other handlers. It did.
…ntent failure The blocking path accumulates a turn's usage before any content work. The streaming path did it last, after the content write and the span finish, so a raise while serialising the completion dropped a turn Anthropic had already billed and left the root reporting less than the run cost. Both paths now accumulate straight after the provider returns. Found by Bugbot on #30.
The prompt write ran before the try that fails the span it writes to. Serialising conversation content raises on anything that is not JSON-serialisable, so a raise there left the chat span open in the tool loop, and on both root paths left the root open: never ended, never exported, so the run disappeared from AI Config Monitoring along with the feature_flag event it carries. The output writes were moved inside their guards earlier in this stack. The input writes were not, which is the same defect at the other end of the same span. Two tests, one per root path. Found by Bugbot on #34, which is this shape in langchain-messages.
…ot send RawRunUsage seeded both cache fields at zero, which undid raw_usage_of: that function omits the fields Anthropic did not send precisely so absent stays absent. The returned bag therefore always looked cache-aware, and parse_usage emitted an input_details breakdown of zeros for a model with no prompt caching at all. A zero cache read is a claim, and this accumulator has no grounds to make it. The two base counts are always present, because a completed turn always has them. A cache field joins the total only once some turn reports one. Two tests: a model with no caching returns the two base counts alone, and a reported cache figure is still carried unfolded so parse_usage folds it once. Found by Bugbot on #30.
…ing it The content write and the span finish sat after the try that fails the chat span, so a serialisation failure reached the outer finally with open_model_span still set. The chat span was ended as abandoned and left UNSET while the root was marked ERROR, which describes one turn as a consumer walking away and as a failure at the same time. The blocking path records the exception and ERROR for the same failure. Both writes now sit inside the guard, so the two paths agree. One test, and it fails on the reverted code with the chat span carrying no status at all. Found by Bugbot on this PR.
a1833cd to
8cb4036
Compare
|
bugbot run |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 8cb4036. Configure here.
1 participant
Replaces one flat span per call with the tree the TypeScript SDK emits, for
claude-messages.A multi-turn run with tools was previously one span with one set of token counts, so per-turn cost and latency were not recoverable from a trace, and a tool call left no trace beyond its LD metric event.
What else changed
spans.pybeside the handler, so the tool loop reads as a tool loop rather than as span bookkeeping with a provider call in the middle. The five handler PRs above follow this shape.parse_usagefolds exactly once.RawRunUsagecarries that shape and is named so it cannot be confused with the client's cache-inclusiveRunUsage.end_turnbecomesstop,tool_usebecomestool_calls.finally. A consumer that breaks out of the iteration skipsexceptentirely, becauseGeneratorExitinherits fromBaseException, so the root span was never ended and never exported: the whole run vanished from AI Config Monitoring along with thefeature_flagevent it carries.The telemetry tests are rewritten rather than extended, because they pinned the old flat span. The single shared mock span is replaced with a recorder that keeps one object per span, since the old approach could not tell a parent from a child.
Not changed: the tool catalog is still unfiltered, unlike the TypeScript SDK. That difference predates this work and changes what the model is offered rather than what the span reports.
Breaking change
The span is renamed from
claude.messagestoinvoke_agent. Queries selecting on the old name will not match. Prompt and completion content is no longer on spans unless the caller passescapture_content=True.Where this sits
Needs the usage layer (#28) and the content layer (#29). Independent of the other five handler PRs; the stack orders them only because
gh stackis linear.Tests: 711 to 729.
Note
Overview
Breaking: The root span is now
invoke_agent(wasclaude.messages). Prompt/completion on spans only whencapture_content=True(default off).Replaces one flat OTel span per call with the same tree as the TypeScript SDK: an
invoke_agentroot (LD identity, run-level tokens), onechat {model}child per model turn, andexecute_tool {name}siblings per tool call (not nested underchat). Span helpers live in newspans.py.Usage & cache: Spans fold Anthropic cache into input totals; handler return value keeps raw Anthropic fields so
parse_usagefolds once. Failed runs still attach token totals on the root when any turn reported usage.Streaming: Adds
finallycleanup so early consumer exit still ends/export spans (abandoned vs ERROR semantics). Hardens leak paths when serialising content or when tools raiseBaseException.claude_messages()now popscapture_contentso it configures the handler instead of breakingconfig().Reviewed by Cursor Bugbot for commit 8cb4036. Bugbot is set up for automated code reviews on this repo. Configure here.