docs: describe the span tree the SDK now emits - #37
Conversation
|
bugbot run |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
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 2137167. Configure here.
2137167 to
73fa904
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 73fa904. Configure here.
73fa904 to
1f5aa42
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 1f5aa42. Configure here.
1f5aa42 to
619c8ef
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 619c8ef. 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 619c8ef. Configure here.
619c8ef to
c2a178b
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 c2a178b. Configure here.
c2a178b to
cc0eb52
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 cc0eb52. Configure here.
cc0eb52 to
b2b3c53
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 b2b3c53. Configure here.
b2b3c53 to
c139584
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 f2cf8bc. Configure here.
f2cf8bc to
3eb47b2
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 3eb47b2. Configure here.
3eb47b2 to
f70c1ab
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 f70c1ab. Configure here.
f70c1ab to
6988504
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 6988504. Configure here.
6988504 to
6541db4
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 6541db4. Configure here.
6541db4 to
babef9a
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 babef9a. Configure here.
babef9a to
8c7eec5
Compare
babef9a to
8c7eec5
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 8c7eec5. Configure here.
README and AGENTS.md both still described one flat span per call with four attributes, which is what this SDK emitted before the span work and what neither SDK emits now. A reader following either document would have built the wrong thing. README gains the tree, the rule that tool spans are siblings of chat rather than children, why the root is the only span carrying the LaunchDarkly identity and the run total, and what prompt caching does to the input count. The Anthropic example is the one worth keeping in mind: the provider reports an input of 3 for a turn that processed 23,554 tokens. It also documents that conversation content is off by default and how to turn it on, since that is the change most likely to surprise someone who was reading prompts off their spans. AGENTS.md now points at TELEMETRY-CONTRACT.md as the authority rather than restating a summary that can drift from it, and lists the shared helpers with what each one writes. The instruction that matters most is not to hand-write a span.set_attribute for anything a helper covers: six hand-rolled copies is how these spans drifted apart in the first place. It also records the three things a new handler author would otherwise get wrong: that cache folding belongs at the call site and not in the shared writer, that finish reasons have three mechanisms rather than one, and that `except Exception` does not catch the GeneratorExit a streaming consumer triggers by breaking out of the loop. Each handler package's agents.md gets a four-line note with its span shape and a pointer to the contract, so someone opening one package sees it without reading the root document first. Fixes the README's install command, which named a package that does not exist: launchdarkly-ai rather than launchdarkly-ai-python.
8c7eec5 to
d83d7be
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 d83d7be. Configure here.
1 participant
Updates the docs to describe the span tree the SDK now emits.
README and AGENTS.md both still described one flat span per call with four attributes, which is what this SDK emitted before this stack and what neither SDK emits now. A reader following either document would have built the wrong thing.
README
chatrather than children.Also fixes an install command that named a package which does not exist:
launchdarkly-airather thanlaunchdarkly-ai-python.AGENTS.md
Now points at
TELEMETRY-CONTRACT.mdas the authority rather than restating a summary that can drift from it, and lists the shared helpers with what each one writes.The instruction that matters most is not to hand-write a
span.set_attributefor anything a helper covers: six hand-rolled copies is how these spans drifted apart in the first place.It also records the three things a new handler author would otherwise get wrong:
except Exceptiondoes not catch theGeneratorExita streaming consumer triggers by breaking out of the loop.Per-package docs
Each handler package's
agents.mdgets a four-line note with its span shape and a pointer to the contract, so someone opening one package sees it without reading the root document first.Where this sits
Top of the stack. Docs only, no code.
Note
Overview
Documentation-only PR that replaces outdated “one flat span per call” telemetry guidance with the three-level span tree (
invoke_agent→chat {model}→execute_tool {tool_name}), including that tool spans are siblings ofchat, not children.README adds user-facing coverage of root-only LaunchDarkly identity and run totals, per-turn token reporting, Anthropic-style cache folding into
gen_ai.usage.input_tokens,capture_content=Trueon handler factories, and abandoned streaming (launchdarkly.stream.abandoned). It also corrects the OTel install line fromlaunchdarkly-ai[otel]tolaunchdarkly-ai-python[otel].AGENTS.md defers to
TELEMETRY-CONTRACT.md, lists shared span helpers and what they write, and documents handler-author pitfalls: explicit parent context, call-site cache folding, default-off content, three finish-reason mechanisms, andfinallycleanup for streaming (GeneratorExit).Each Tier 1 handler package
agents.mdgets a short top note on span shape,spans.py, and the contract pointer.Reviewed by Cursor Bugbot for commit d83d7be. Bugbot is set up for automated code reviews on this repo. Configure here.