Maple agent tracing: LlamaIndex (Python)

Goal: every conversation = one Maple Agent Session. Each agent.run() / workflow.run() = one turn (one trace) with transcript, one model span per model call with tokens, FunctionTool.acall tool spans with results, failed tools marked failed, sub-agents in their own lanes.

Mechanism: openinference-instrumentation-llama-index (scope openinference.instrumentation.llama_index). Maple reads the session (session.id from using_session), transcript, tokens and tool calls from its spans. TraceConfig(enable_genai_semconv=True) is recommended: it also emits standard GenAI attributes (gen_ai.*, incl. gen_ai.conversation.id).

Step 0: Detect

1. Versions: python -c "import llama_index.core as c; print(c.__version__)" (or pyproject.toml / uv.lock / requirements*.txt).
   • Need llama-index-core >= 0.14.19 (tested 0.14.25). Older: the instrumentor logs DependencyConflict and does nothing. Tell the user to upgrade.
   • Python >= 3.10.
2. Existing tracing. Search for LlamaIndexOpenTelemetry, llama_index.observability.otel, LlamaIndexInstrumentor, set_global_handler, TracerProvider(, set_tracer_provider, opentelemetry-instrument, logfire.configure, sentry_sdk.init, langfuse, phoenix.otel.register.
   • LlamaIndexOpenTelemetry (native llama-index-observability-otel) present → replace it with Step 2 (it puts content in span events, loses reply and usage on streamed calls, ignores OTEL_EXPORTER_OTLP_*). Never run both: every span doubles. Ask before removing if it also feeds another backend.
   • LlamaIndexInstrumentor already used (Phoenix/Langfuse/Arize) → keep it, reuse its provider, add config=TraceConfig(enable_genai_semconv=True) and the Maple processor to that provider.
   • Another TracerProvider exists → add the Maple processor chain to it; do NOT create a second provider.
3. Other instrumentors on the model client (openinference-instrumentation-openai, -litellm, OpenLLMetry Traceloop.init, logfire.instrument_openai) → duplicate model spans with their own usage. Remove for LlamaIndex models (ask if they serve other code).
4. Find: every agent.run( / workflow.run( / AgentWorkflow( call, where the chat/thread id lives in the request, every FunctionAgent(/ReActAgent(/CodeActAgent( construction, every tool that runs another agent, every ctx.wait_for_event( (HITL).
5. LLM class: OpenAILike/OpenRouter need is_function_calling_model=True or tools silently never run (no tool spans). Check it's set.