[Feature]: Add gen_ai.conversation.id for cross-turn session correlation in OTel export

[FTDGRT]

Summary

Add a session_id field to 8 turn-lifecycle ObserverEvent variants (AgentStart, AgentEnd, LlmRequest, LlmResponse, ToolCallStart, ToolCall, MemoryRecall, MemoryStore), exported via OTel as gen_ai.conversation.id; rename the existing zeroclaw.turn_id to gen_ai.turn.id.

Problem statement

#7385 established single-turn span correlation via turn_id (gen_ai.agent.invoke parent span + llm.call/tool.call children). #6641's Non-goals explicitly excluded cross-turn session correlation. Nothing today links multiple turns of the same conversation — each turn is its own trace, and operators reconstruct conversations by hand from timestamps and channel/sender metadata. gen_ai.conversation.id is the OTel GenAI semantic convention's field for exactly this.

Proposed solution

1. Add session_id: Option<String> to the 8 variants (not RagRetrieve).
2. Thread session_id as an explicit field, same as turn_id today: ToolLoop/TurnCtx/TurnMeta gain the field, each construction site fills it from a value it already holds locally (history_key, session_key, memory_session_id, or process_message's existing session_id parameter). No Tokio task-local reads — see Alternatives.
3. In OtelObserver, replace every KeyValue::new("zeroclaw.turn_id", ...) with two lines: gen_ai.turn.id (renamed existing value) + gen_ai.conversation.id (new value).
4. render_memory_context gets a new session_id: Option<&str> parameter, distinct from the existing multi-scope sessions list — one is "which conversation this call belongs to," the other is "which memory partitions to search."
5. Extend the assert_all_events_share_turn_id-style regression helpers in both agent.rs and loop_.rs (two independently maintained copies) with the same existence + consistency checks for session_id.

Non-goals / out of scope

• RagRetrieve — independent hardware-retrieval path, not part of this.
• No turn_id or parent-span nesting added to memory/RAG events — that's feat(obs): nest memory and RAG spans under the turn trace #8752 (open PR).
• No change to process_message's lifecycle restructure (feat(obs): add process_message turn lifecycle for memory span nesting #8844's scope).
• No new user-facing config; no change to OTel content-capture policy.

Acceptance criteria

• The 8 variants carry session_id: Option<String>.
• Every turn-minting entry point populates it without adding new task-local scoping.
• OTel exports gen_ai.turn.id + gen_ai.conversation.id.
• Non-OTel Observers (Prometheus/Verbose/Noop/eval) compile unchanged.
• Both agent.rs and loop_.rs regression tests cover session_id.
• Two-turn e2e check: both traces share one gen_ai.conversation.id, each keeps a distinct gen_ai.turn.id.

Architecture impact

zeroclaw-api::observability_traits (ObserverEvent), zeroclaw-runtime::agent::turn (TurnCtx/TurnMeta/ToolLoop), agent.rs/loop_.rs/tool_execution.rs/memory_inject.rs, construction sites in the channel orchestrator / gateway WS / ACP / RPC turn paths, observability/otel.rs, zeroclaw-log/observer_bridge.rs.

Risk and rollback

High: The risk comes from blast radius — session_id threads through the main runtime turn-lifecycle files (agent.rs, loop_.rs, turn/*, tool_execution.rs, memory_inject.rs) and every construction site across channel orchestrator / gateway WS / ACP / RPC turn paths, plus the regression tests in both agent.rs and loop_.rs need matching updates. All new ObserverEvent fields are additive Options and non-OTel Observers are unaffected, so the risk is scope/coordination, not compatibility.

Breaking change?

Yes, OTel span attribute rename only — no config/CLI impact.

Related work

• feat(observability): add turn metadata to observer events and correlate OTel spans by turn_id #7385: introduced turn_id and span parent/child nesting (merged)
• [Feature]: Turn-level OTel trace correlation — nest llm.call / tool.call / memory.* spans under a single turn trace #6641: asked for that nesting to extend to memory/RAG and listed session-level correlation as a Non-goal — this proposal fills that Non-goal
• feat(obs): nest memory and RAG spans under the turn trace #8752: attaches turn_id to memory/RAG (open PR)
• feat(obs): add process_message turn lifecycle for memory span nesting #8844: process_message turn lifecycle restructure; does not block this proposal

Data hygiene checks

• I removed personal/sensitive data from examples, payloads, and logs.
• I used neutral, project-focused wording and placeholders.

[kapoo202061-ctrl]

في الجمعة، ١٠ يوليو ٢٠٢٦، ٧:١٠ ص Chunpeng Yan ***@***.***> كتب:

…

*FTDGRT* created an issue (zeroclaw-labs/zeroclaw#8933) <#8933> Summary Add a session_id field to 8 turn-lifecycle ObserverEvent variants ( AgentStart, AgentEnd, LlmRequest, LlmResponse, ToolCallStart, ToolCall, MemoryRecall, MemoryStore), exported via OTel as gen_ai.conversation.id; rename the existing zeroclaw.turn_id to gen_ai.turn.id. Problem statement #7385 <#7385> established single-turn span correlation via turn_id (gen_ai.agent.invoke parent span + llm.call/tool.call children). #6641 <#6641>'s Non-goals explicitly excluded cross-turn session correlation. Nothing today links multiple turns of the same conversation — each turn is its own trace, and operators reconstruct conversations by hand from timestamps and channel/sender metadata. gen_ai.conversation.id is the OTel GenAI semantic convention's field for exactly this. Proposed solution 1. Add session_id: Option<String> to the 8 variants (not RagRetrieve). 2. Thread session_id as an explicit field, same as turn_id today: ToolLoop/TurnCtx/TurnMeta gain the field, each construction site fills it from a value it already holds locally (history_key, session_key, memory_session_id, or process_message's existing session_id parameter). No Tokio task-local reads — see Alternatives. 3. In OtelObserver, replace every KeyValue::new("zeroclaw.turn_id", ...) with two lines: gen_ai.turn.id (renamed existing value) + gen_ai.conversation.id (new value). 4. render_memory_context gets a new session_id: Option<&str> parameter, distinct from the existing multi-scope sessions list — one is "which conversation this call belongs to," the other is "which memory partitions to search." 5. Extend the assert_all_events_share_turn_id-style regression helpers in both agent.rs and loop_.rs (two independently maintained copies) with the same existence + consistency checks for session_id. Non-goals / out of scope - RagRetrieve — independent hardware-retrieval path, not part of this. - No turn_id or parent-span nesting added to memory/RAG events — that's #8752 <#8752> (open PR). - No change to process_message's lifecycle restructure (#8844 <#8844>'s scope). - No new user-facing config; no change to OTel content-capture policy. Acceptance criteria - The 8 variants carry session_id: Option<String>. - Every turn-minting entry point populates it without adding new task-local scoping. - OTel exports gen_ai.turn.id + gen_ai.conversation.id. - Non-OTel Observers (Prometheus/Verbose/Noop/eval) compile unchanged. - Both agent.rs and loop_.rs regression tests cover session_id. - Two-turn e2e check: both traces share one gen_ai.conversation.id, each keeps a distinct gen_ai.turn.id. Architecture impact zeroclaw-api::observability_traits (ObserverEvent), zeroclaw-runtime::agent::turn (TurnCtx/TurnMeta/ToolLoop), agent.rs/ loop_.rs/tool_execution.rs/memory_inject.rs, construction sites in the channel orchestrator / gateway WS / ACP / RPC turn paths, observability/otel.rs, zeroclaw-log/observer_bridge.rs. Risk and rollback High: The risk comes from blast radius — session_id threads through the main runtime turn-lifecycle files (agent.rs, loop_.rs, turn/*, tool_execution.rs, memory_inject.rs) and every construction site across channel orchestrator / gateway WS / ACP / RPC turn paths, plus the regression tests in both agent.rs and loop_.rs need matching updates. All new ObserverEvent fields are additive Options and non-OTel Observers are unaffected, so the risk is scope/coordination, not compatibility. Breaking change? Yes, OTel span attribute rename only — no config/CLI impact. Related work - #7385 <#7385>: introduced turn_id and span parent/child nesting (merged) - #6641 <#6641>: asked for that nesting to extend to memory/RAG and listed session-level correlation as a Non-goal — this proposal fills that Non-goal - #8752 <#8752>: attaches turn_id to memory/RAG (open PR) - #8844 <#8844>: process_message turn lifecycle restructure; does not block this proposal Data hygiene checks - I removed personal/sensitive data from examples, payloads, and logs. - I used neutral, project-focused wording and placeholders. — Reply to this email directly, view it on GitHub <#8933?email_source=notifications&email_token=BWHIP376OHAEVJ7462K6ZRT5EBUFDA5CNFSL4Z3JMQ5C6L3HNF2C22DVMIXUS43TOVSS6NBYGUYTSMRSGY4TBJTSMVQXG33OVJZXKYTTMNZGSYTFMSSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BWHIP3YAS3DW7U25DQCMIML5EBUFDAVCNFSNUABGKJSXA33TNF2G64TZHMYTCNJWHE2TMOBZGA5US43TOVSTWNBYGUYTSMRSGY4TBILWAI> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/BWHIP36PK5HRAD5R7D3FLRL5EBUFDA5CNFSL4Z3JMQ5C6L3HNF2C22DVMIXUS43TOVSS6NBYGUYTSMRSGY4TBJTSMVQXG33OVJZXKYTTMNZGSYTFMSSWK5TFNZ2KUZTPN52GK4S7NFXXG> and Android <https://github.com/notifications/mobile/android/BWHIP36SAFM2EW3O5SAJKTL5EBUFDA5CNFSL4Z3JMQ5C6L3HNF2C22DVMIXUS43TOVSS6NBYGUYTSMRSGY4TBJTSMVQXG33OVJZXKYTTMNZGSYTFMSSWK5TFNZ2K4ZTPN52GK4S7MFXGI4TPNFSA>. Download it today! You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>