docs(telemetry): pin the span contract the TypeScript SDK already implements - #27
docs(telemetry): pin the span contract the TypeScript SDK already implements#27apucacao wants to merge 2 commits into
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.
1 participant
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, the authoritative span/attribute contract the six Python handlers must match against the TypeScript SDK (js-ai-sdk@5178db1). No runtime code changes.The doc pins the
invoke_agent/chat {model}/execute_tooltree, per-handlergen_ai.*andlaunchdarkly.*attributes, finish-reason rules (including OpenAI Responses derivation), content-capture carriers, provider-specific token folding, and abandoned-stream teardown. It also calls out known gaps (e.g. retiringset_openllmetry_*, addingSpanUsage) and the ~121 existing tests that will need rewriting when the port lands.Reviewed by Cursor Bugbot for commit 3f629c6. Bugbot is set up for automated code reviews on this repo. Configure here.