spike: gen_ai.conversation_root — native + OTel ingest paths

[adityamehra]

Summary

• OTel path (src/splunk_ao/otel.py): Added GEN_AI_CONVERSATION_ROOT = "gen_ai.conversation_root" constant and root-detection in start_splunk_ao_span(). Root status is sampled before entering the new span context, so a WorkflowSpan/AgentSpan with no valid OTel parent automatically receives gen_ai.conversation_root = True.
• Native path (src/splunk_ao/schema/logged.py, src/splunk_ao/logger/logger.py): LoggedWorkflowSpan and LoggedAgentSpan gain a conversation_root: bool | None field. add_workflow_span() / add_agent_span() auto-detect the root by checking whether current_parent() is a LoggedTrace; if so, conversation_root=True is set on the span and mirrored into user_metadata["gen_ai.conversation_root"] as a bridge until the backend schema is updated.
• Example (examples/agent/langchain-agent-http/): FastAPI HTTP wrapper around the LangChain agent example (mirrors PR #236 scenarios). Verified end-to-end against rc0.

Reference

• splunk-otel-python-contrib PR #236 — opentelemetry-util-genai reference implementation
• Root detection heuristic: a Workflow/AgentInvocation span is the conversation root if it has no immediate GenAI parent (OTel: no valid parent SpanContext; native: parent is LoggedTrace)

What this spike establishes

Path	Detection	Attribute written
OTel (start_splunk_ao_span)	No valid OTel parent before entering span	gen_ai.conversation_root = True (OTel attribute)
Native (add_workflow_span)	current_parent() is LoggedTrace	LoggedWorkflowSpan.conversation_root = True + user_metadata["gen_ai.conversation_root"] = "true"
Native (add_agent_span)	current_parent() is LoggedTrace	LoggedAgentSpan.conversation_root = True + user_metadata["gen_ai.conversation_root"] = "true"

Test plan

• Confirm root WorkflowSpan (parent = LoggedTrace) → conversation_root=True ✓ (verified locally)
• Confirm nested WorkflowSpan (parent = another span) → conversation_root=None ✓ (verified locally)
• Confirm OTel root span → gen_ai.conversation_root=True attribute ✓ (verified via in-memory exporter)
• Confirm OTel nested span → no attribute ✓ (verified via in-memory exporter)
• End-to-end traces reach rc0 console with gen_ai.conversation_root in user_metadata ✓ (manual run against rc0)
• Add unit tests for both paths before merging full implementation
• Confirm backend can consume/index the user_metadata bridge value
• Align with galileo-core schema update once backend schema ships the proper field

TODOs before full implementation

• Unit tests (tests/) covering root vs nested detection for both paths
• Handler verification (SplunkAOCallback, LangGraph, CrewAI, etc.) — each framework callback's first GenAI span should be auto-detected as root
• Backend schema change to accept conversation_root as a first-class field (currently bridged via user_metadata)
• Remove user_metadata bridge once backend schema is updated

Made with Cursor