Repository navigation
Stamp session.id on Cloudflare agent spans for cross-conversation trace grouping #908
astrobot-houston
started this conversation in
Feature Request
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Summary
The Cloudflare tracing adapter now writes a stable
session.idon everyinvoke_agent,chat, andexecute_toolspan. Its value is the agent's root conversation id. Every delegated subagent task (at any depth), model turn, and tool span under that root carries the same value. Each conversation keeps its owngen_ai.conversation.id.Background & motivation
A subagent task runs in a fresh conversation, so its spans report a new
gen_ai.conversation.id. That is correct under the GenAI definition. The parent link (parentConversationId) exists only in Flue's durable records, never on spans. Each turn is also its own Trace. A backend that wants "everything this conversation did", including token totals across its subagents, today has to rebuild ancestry from the span-parent graph. That is expensive and breaks across Trace boundaries.Products that group traces into Sessions (Laminar, Langfuse, LangSmith Threads, Arize Phoenix) do it with an explicit session id. The id is set once and propagated to every child span, not reconstructed from parentage. This PR gives Flue spans that id.
Goals
gen_ai.conversation.idkeeps its current per-conversation meaning.Example
Design
gen_ai.conversation.id: differs for every delegate.FlueExecutionContext.rootConversationId:Harness.loadSessionsets it from arootconversation.CreateTaskSessionOptions.rootConversationIdcarries it into subagent tasks, on both the fresh path and the recovery-reattach path.createCloudflareTracingwrites it as the first attribute when a span opens, ahead of content. It therefore survives workerd's per-span attribute cap and is always set beforeend(). When the context has no root, the attribute is omitted.Semantic conventions
session.idis from OpenTelemetry's general session convention, not the GenAI registry, which defines nosession.*key. It is Development status and Opt-In.gen_ai.conversation.idkeeps its GenAI registry meaning: "used to store and correlate messages within this conversation".session.idis Flue's mapping. OpenTelemetry does not prescribe it. The general convention describes client-side sessions that roll over on inactivity. Flue's Session doesn't roll over; it lasts as long as its root conversation. The inline docs say so.Changes
packages/runtime/src/execution-interceptor.ts: optionalrootConversationIdonFlueExecutionContext. This is additive on a public type.packages/runtime/src/harness.ts: sets the value for root sessions and inherits it for action-scoped children and task sessions.packages/runtime/src/session.ts: passes the root to both task-creation call sites.packages/runtime/src/cloudflare/tracing/attributes.ts:ATTR.sessionId = 'session.id'. Linked convention docs on it and onATTR.conversationId.packages/runtime/src/cloudflare/tracing/index.ts: writes the attribute when a span opens.apps/docs/src/content/docs/guide/cloudflare-target.md: documents the attribute.Testing
The repository ships no tests, so none are included. Verified locally with a vitest suite that runs the real runtime (
start(), in-memory SQLite, Pi's faux provider) against a recording mock ofcloudflare:workerstracing:invoke_agent, 6chat, and 2execute_toolspans carry the root conversation id.end(), with no late writes.gen_ai.conversation.idvalues stay distinct.session.id.session.id.session.id.Also passing:
tsc --noEmit,pnpm build,pnpm check:types, biome, and prettier on the touched files.Notes and follow-ups (not in this PR)
main. Model calls made throughharness.prompt()insideharness: truetools anduseAgentStart/useAgentFinishhooks emit no Cloudflare spans. The cause: action-scoped events carryharness: 'default', while their interception context carriesdefault:action:inv_…, so the adapter's identity keys never match.@flue/opentelemetryuses the same keys; its spans exist but aren't activated, so auto-instrumented children mis-nest. Once that is fixed, those spans pick upsession.idautomatically. I will file it separately.session.idfrom@flue/opentelemetry.Original implementation from #907 by @msmps
All reactions