Skip to content

feat(observability): group agent storage spans#2

Draft
Ankcorn wants to merge 1 commit into
stack/pr-1860-basefrom
tankcorn/group-agent-spans
Draft

feat(observability): group agent storage spans#2
Ankcorn wants to merge 1 commit into
stack/pr-1860-basefrom
tankcorn/group-agent-spans

Conversation

@Ankcorn

@Ankcorn Ankcorn commented Jul 15, 2026

Copy link
Copy Markdown
Owner

Why

cloudflare#1860 makes inference and tool work visible, but SDK-managed chat flows still emit dozens of Durable Object spans beside the useful invoke_agent path.

This groups storage work into semantic phases so raw DO spans remain available without burying model and tool activity.

Trace shape

agent_initialization
└── initialize_agent_storage
    └── DO schema/migration spans...

think_start
├── initialize_think_session
├── hydrate_think_session
├── initialize_think_chat
├── agent_start
│   ├── restore_agent_state
│   ├── restore_mcp_connections
│   ├── recover_agent_work
│   └── run_user_on_start
├── reconcile_think_schedules
└── recover_think_durable_work

chat_interaction
├── clear_previous_chat_state
├── persist_chat_request_context
├── load_chat_history
├── persist_incoming_messages
├── schedule_agent_alarm
└── chat_turn
    ├── initialize_fiber
    ├── persist_fiber_snapshot
    ├── prepare_agent
    │   └── tools/skills/session/prompt/config DO spans...
    ├── invoke_agent
    │   └── chat
    │       └── execute_tool
    ├── persist_chat_result
    ├── finalize_fiber
    └── schedule_agent_alarm

prepare_agent closes before invoke_agent starts, keeping them as siblings. No known SDK SQLite spans remain as direct siblings of invoke_agent.

Durable submissions similarly group acceptance/execution around a nested chat_turn.

Attributes

Every SDK span carries agent identity plus:

cloudflare.agents.operation.name
cloudflare.agents.storage.grouped = true
cloudflare.agents.storage.system = "durable_object"
cloudflare.agents.storage.phase

Chat phases also carry request ID, trigger, admission, generation, channel and continuation where available. Initialization/startup spans add schema, hydration and recovery metadata. Conversation content, tool payloads and error messages are not recorded.

A phase typically groups 3–15 DO operations; full schema migration groups roughly 45, while streaming and recovery are unbounded.

One runtime-level KV read can remain between initialization and startup: PartyServer privately hydrates its legacy __ps_name before invoking onStart, outside Agent lifecycle hooks.

Stacked on cloudflare#1860. This fork PR targets an exact mirror of that PR head because this account cannot open a PR directly against Cloudflare's branch.

@Ankcorn Ankcorn force-pushed the tankcorn/group-agent-spans branch 4 times, most recently from 0058371 to 52de5f8 Compare July 15, 2026 14:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant