Skip to main content
The LlamaIndex integration installs a span handler on LlamaIndex’s instrumentation dispatcher (v0.12.0+). Every query engine call, every retriever hop, every LLM synthesis step is captured.

Install

Requires llama-index-core>=0.12.0.

Use

Runs are filed under llamaindex-agent unless you say otherwise. To name the agent for the whole process, install by hand instead of through the flag:
Call instrument() once. LlamaIndex’s dispatcher takes span handlers additively and never gives one back, so a second call double-traces every query from then on — one query, two traces.

Several agents in one process

Because there is one handler for the whole process, the install-time name can’t be the answer for a service that answers for more than one agent — a multi-tenant API, or a router that picks between a support index and a billing index. Name the run instead:
Each run gets its own name and its own manifest — two agents that happen to share a model and a retriever still version independently. The scope is per-context, not global, so concurrent runs stay separate: open it inside each thread or asyncio task and eight in-flight requests produce eight correctly-labelled traces. Open it inside the worker, not around the dispatch — a ThreadPoolExecutor worker starts from a fresh context.
Nothing above is required for the single-agent case: with no scope open, runs keep the name instrument() was given.
LlamaIndex’s own instrument_tags({"agent_name": "..."}) names a run the same way, and wins over agent_run when both are set. Use whichever you already reach for; agent_run is the one that works identically across every DecimalAI rail.

What gets captured

  • Query engine, retriever, and synthesizer spans
  • Embedding calls with token counts
  • LLM calls with the full resolved prompt
  • Auto-detected manifest from the query engine config, per agent

Caveats

  • Auto-detected manifest captures tool names only — not full schemas. If you need schema-aware manifests, register them explicitly with register_manifest().
  • The floor is llama-index-core>=0.12.0 — earlier releases either lack the instrumentation dispatcher entirely (pre-0.10.20) or drive span handlers with an incompatible early signature, so spans never reach the handler.

What’s next

Tracing guide

Conceptual model: what a span is and how trees are built.

Manifests

Register a manifest explicitly to capture tool schemas.