Add LlamaIndex retrieval instrumentation

[eternalcuriouslearner]

Summary

Adds OpenTelemetry retrieval spans for LlamaIndex synchronous and asynchronous BaseRetriever operations. Captures query text and retrieved documents when content capture is enabled, records top-k, preserves retrieval errors, and adds tests, conformance coverage, and documentation.\n\nProvider model calls remain delegated to provider instrumentations.

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on the author · refreshed 2026-09-12 20:03 UTC

Wait for the required status checks to report; this pull request moves to reviewers once the results are clean.

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Should this be with reviewers? Comment /dashboard route:reviewers to route it to them.
• Anything wrong — including the routing? Report it with what you expected; it helps us improve the dashboard.

[Copilot]

🟡 Changes recommended

A critical document-capture bug and compatibility/schema issues remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds LlamaIndex synchronous and asynchronous retrieval span instrumentation with optional query/document capture.

Changes:

• Adds retrieval telemetry, errors, and top-k attributes.
• Adds shared document typing, tests, conformance coverage, documentation, and changelogs.

File summaries

File	Summary
util/opentelemetry-util-genai/src/opentelemetry/util/genai/types.py	Adds retrieval document model. Moderate (3 votes): use the pinned schema-backed dataclass representation. Nit (1 vote): link the pinned semconv model.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_retrieval_invocation.py	Uses typed retrieval documents. Moderate (1 vote): preserve compatibility with existing mapping-based consumers.
util/opentelemetry-util-genai/.changelog/697.added	Documents the utility addition.
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/test_retrieval.py	Adds retrieval behavior tests.
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/test_conformance.py	Registers retrieval conformance coverage.
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/conformance/retrieval.py	Defines the retrieval conformance scenario.
instrumentation/opentelemetry-instrumentation-genai-llama-index/src/opentelemetry/instrumentation/genai/llama_index/_handler.py	Instruments retriever operations. Critical (1 vote): retrieve document content from the wrapped node. Nit (2 votes): add QueryBundle regression coverage.
instrumentation/opentelemetry-instrumentation-genai-llama-index/README.rst	Documents retrieval instrumentation.
instrumentation/opentelemetry-instrumentation-genai-llama-index/.changelog/697.added	Documents the instrumentation addition.

Review details

Suppressed comments (2)

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_retrieval_invocation.py:83

• Changing this public documents attribute from Sequence[Mapping[str, Any]] to Sequence[RetrievalDocument] narrows the existing contract. The in-repo LangChain and DSPy instrumentations still assign ordinary mappings (for example, instrumentation/opentelemetry-instrumentation-genai-langchain/src/opentelemetry/instrumentation/genai/langchain/callback_handler.py:751), and downstream instrumentations can do the same; preserve a compatible accepted type or update every consumer before making this narrowing change.

        self.documents: Sequence[RetrievalDocument] | None = None

util/opentelemetry-util-genai/src/opentelemetry/util/genai/types.py:54

• The docstring says this follows the retrieval-document schema but does not cite the concrete semconv model. Link the model at the pinned SEMCONV_GENAI_REF so future field and optionality changes can be checked against the version this package supports.

    This model follows the GenAI retrieval document schema and is shared by
    instrumentations so document attributes retain a consistent shape.

• Files reviewed: 9/9 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Retrieval document typing and exception isolation must be corrected before approval.

Get a fresh assessment by requesting another Copilot review.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 4
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

Retrieval documents must use a shared util-genai semantic-convention model rather than ad-hoc dictionaries.

Review details

Suppressed comments (1)

instrumentation/opentelemetry-instrumentation-genai-llama-index/src/opentelemetry/instrumentation/genai/llama_index/_handler.py:327

• The retrieval document is a semantic-convention structured model, but this helper exposes it as dict[str, Any]. The instrumentation semantic-convention rule requires these values to use the corresponding opentelemetry.util.genai.types dataclass rather than an ad-hoc mapping. Please add a retrieval-document model to util-genai, update RetrievalInvocation.documents/serialization to accept it, and construct that model here.

def _retrieval_documents(
    result: object,
) -> list[dict[str, Any]] | None:

• Files reviewed: 6/6 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[lmolkova]

This exception guard adds special handling for a hypothetical getter failure; other attribute reads in this handler are unguarded. Keep the same pattern here.

Suggested change

	try:
	top_k = getattr(retriever, "similarity_top_k", None)
	except BaseException:
	return None
	top_k = getattr(retriever, "similarity_top_k", None)

[lmolkova]

This artificial KeyboardInterrupt case only supports the unnecessary exception guard. Remove the test along with it.

Suggested change

	def test_similarity_top_k_getter_failure_is_ignored() -> None:
	class _FailingRetriever:
	@property
	def similarity_top_k(self) -> int:
	raise KeyboardInterrupt
	assert _retrieval_top_k(cast(BaseRetriever, _FailingRetriever())) is None