docs(telemetry): pin the span contract the TypeScript SDK already implements - #27
Conversation
…lements
The TypeScript SDK reshaped its OpenTelemetry output in July: a three-level
span tree, a cache-aware token vocabulary, one finish-reason enum, and
conversation content behind an opt-in flag. Python never got any of it, and
still emits the shape TypeScript retired.
Six handler packages have to change to close that. Six agents each deriving
the vocabulary from the TypeScript source would produce six slightly
different vocabularies, which is how the TypeScript span code drifted apart
the first time. So the vocabulary is written down once, here, and the handler
work is checked against this file rather than against a reading of the other
SDK.
Derived from js-ai-sdk at 5178db1. Where this file and the TypeScript source
disagree, the source wins and this file is a bug.
Two mechanical checks stand behind it. Every `gen_ai.*` and `launchdarkly.*`
literal in the TypeScript source appears here, verified by diffing the two
sets; the only absentees are the two keys inside `setOpenLLMetryCompletion`,
which has no call sites left. And two independent reviews, one against the
TypeScript source and one against the Python source, found nine defects in
an earlier draft. All nine are fixed here, including three that would have
produced wrong spans across several handlers:
- `gen_ai.response.model` is the requested model on four of six handlers,
not the answering model. Only openai-messages reads it off the response.
- The two OpenAI handlers use the Responses API, which has no
finish_reason field. They derive the value and must not use the mapping
table. An earlier draft told porters to build one table for all six.
- contextvars does cross asyncio.create_task. The claim that it does not
was wrong, and a porter reasoning from it would draw bad conclusions
elsewhere. Threads are the boundary that loses context.
Section 12 records the work the first draft left implicit, including the
348 existing test functions and how many assert on something this changes.
|
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 49c8fe8. Configure here.
…y ran The request-model row claimed the requested name for all six handlers. claude-agents writes the model the inference actually used on its chat span, the same value it gives gen_ai.response.model, which the TypeScript source does deliberately: the CLI reports the model it really ran and there is no separate per-turn requested name to report. Stated as it was, the document made a correct handler look like a defect. A review of #31 raised it against the handler rather than against this file, which is the failure mode a specification has when it overgeneralises. Its root span still writes the requested name, so only the chat span differs.
|
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 3f629c6. 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 3f629c6. 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 3f629c6. 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 3f629c6. 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 3f629c6. 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 3f629c6. 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 3f629c6. 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 3f629c6. 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 3f629c6. 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 3f629c6. 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 3f629c6. 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 3f629c6. 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 3f629c6. 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 3f629c6. 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 3f629c6. Configure here.
…ts in The contract described what the writer does with a value, that a string passes through unchanged and anything else becomes JSON, and said nothing about what a call site should hand it. A comment in the openai-agents handler read that line as a reason to pass a provider's raw JSON string straight through, which made an OpenAI span describe a tool call differently from an Anthropic one. State the call-site rule: arguments hold the object the provider means, not the encoding it chose. Name the two providers that send a string, and say what happens to a string that does not parse. Point at the cache folding in section 4 as the precedent, since it is the same division: the shared writer cannot know whether a string is an encoding or a value, so the provider's shape is the call site's business.
|
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 08b31d8. 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 08b31d8. Configure here.
The rule said the root is the only span carrying launchdarkly.*, and that child spans carry neither that nor the feature_flag event. The second half is right. The first half was already untrue: the streaming paths have marked launchdarkly.stream.abandoned on open chat and tool spans since the earlier rounds, and the cancellation teardown now marks launchdarkly.run.cancelled the same way. Both markers say why a span stopped, so they belong on whichever span was still open, root or child. A chat span that ends with no status and no marker cannot be told apart from a bug. What the rule protects is unchanged, and is now stated: neither marker identifies a config, so a config-scoped query still finds exactly one span per run. The config-association attributes stay on the root alone, and the test that asserts it runs a successful run, where no marker appears at all. Found by Bugbot on the usage layer.
|
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 79f0697. 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 79f0697. 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 79f0697. 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 79f0697. 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 79f0697. 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 79f0697. 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 79f0697. Configure here.
2 participants
Writes down the span contract the TypeScript SDK already implements, so the six Python handler packages can be checked against one document instead of against six readings of another SDK.
No code. This is the specification the rest of the stack is built from.
js-ai-sdkat5178db1. Where this file and that source disagree, the source wins and this file is the bug.gen_ai.*andlaunchdarkly.*literal in the TypeScript source appears here, verified by diffing the two sets.Three of those defects would have produced wrong spans across several handlers:
gen_ai.response.modelis the requested model on four of six handlers, not the answering model. Onlyopenai-messagesreads it off the response.finish_reasonfield. They derive the value and must not use the mapping table. An earlier draft told porters to build one table for all six.contextvarsdoes crossasyncio.create_task. The claim that it does not was wrong, and a porter reasoning from it would draw bad conclusions elsewhere. Threads are the boundary that loses context.Section 12 records the work an earlier draft left implicit, including the 348 existing test functions and how many assert on something this stack changes.
Where this sits
Bottom of the stack. Everything above it is checked against this file.
Note
Overview
Adds
TELEMETRY-CONTRACT.md, a specification for making the six Python handler packages emit the same OpenTelemetry spans and attributes as the TypeScript SDK atjs-ai-sdkcommit5178db1. No runtime code changes—this is the authority document for upcoming parity work.The contract spells out the full span tree (
invoke_agent→chat {model}/execute_tool {tool_name}), verbatimgen_ai.*andlaunchdarkly.*keys, and handler-specific rules that correct common misconceptions: four of six handlers put the requested model ingen_ai.response.model(onlyopenai-messagesreads the answering model); OpenAI handlers derive finish reasons from Responses API output instead of a shared mapping table; Anthropic vs OpenAI/LangChain cache token folding must happen at call sites, not in shared writers.It also documents streaming teardown (
GeneratorExit,launchdarkly.stream.abandoned, generatoracloseforclaude-agents, run cancel foropenai-agents), content capture carriers (canonical + OpenLLMetry + legacy events), LangChaingen_ai.system=langchainparity, retirement ofset_openllmetry_*, and section 12’s implicit work (newSpanUsage,parse_usageshape, ~121 tests to rewrite).Reviewed by Cursor Bugbot for commit 79f0697. Bugbot is set up for automated code reviews on this repo. Configure here.