[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

Merged · refreshed 2026-09-13 22:36 UTC

Status above doesn't look right?

• Anything look wrong? 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