Registry / observability / opentelemetry-instrumentation-llamaindex

opentelemetry-instrumentation-llamaindex

JSON →
library0.62.3pypypi✓ verified 23d ago

This library provides OpenTelemetry tracing for applications built with LlamaIndex. It allows developers to observe the full lifecycle of LLM-based applications, including RAG pipelines, agents, and underlying LLM calls, by generating OpenTelemetry-compliant spans. The project is actively maintained with frequent releases, often aligning with the evolving OpenTelemetry GenAI semantic conventions.

pip install opentelemetry-instrumentation-llamaindex llama-index-core openai
INSTALL
IMPORT
SIG · OPENTELEMETRY-INST
O
opentelemetry-instrumentation-llamaindex
observabilitypythonv0.62.3
Install
21.5s avg
Import
Disk
276MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.62.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 265.1MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 21.5s · import 0.000s · 261MB
276MB installed
● package 276MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

LlamaIndexInstrumentor
from opentelemetry.instrumentation.llamaindex import LlamaIndexInstrumentor

This quickstart demonstrates how to set up OpenTelemetry to collect traces from a LlamaIndex application. It initializes a `TracerProvider` with a `ConsoleSpanExporter` (for easy demonstration), then enables the `LlamaIndexInstrumentor`. A simple LlamaIndex query is performed, and its operations are traced and printed to the console. Remember to install `llama-index-core` and an LLM provider like `openai`.

import os from opentelemetry import trace from opentelemetry.sdk.resources import Resource from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import ( ConsoleSpanExporter, SimpleSpanProcessor ) from opentelemetry.instrumentation.llamaindex import LlamaIndexInstrumentor # For the LlamaIndex example from llama_index.core import VectorStoreIndex, SimpleDirectoryReader from llama_index.llms.openai import OpenAI # --- OpenTelemetry Setup (for console output) --- # Resource for your service resource = Resource.create({"service.name": "llamaindex-app"}) # Configure TracerProvider provider = TracerProvider(resource=resource) trace.set_tracer_provider(provider) # Configure Span Exporter to print traces to console exporter = ConsoleSpanExporter() span_processor = SimpleSpanProcessor(exporter) provider.add_span_processor(span_processor) # --- Instrument LlamaIndex --- LlamaIndexInstrumentor().instrument() print("LlamaIndex instrumentation enabled.") # --- LlamaIndex Application Example --- # Ensure OpenAI API key is set for the example # Replace with your actual key or set as an environment variable os.environ["OPENAI_API_KEY"] = os.environ.get("OPENAI_API_KEY", "sk-YOUR_OPENAI_API_KEY") # Create a dummy document for LlamaIndex dummy_data_dir = "./data" os.makedirs(dummy_data_dir, exist_ok=True) with open(os.path.join(dummy_data_dir, "test_doc.txt"), "w") as f: f.write("The quick brown fox jumps over the lazy dog. LlamaIndex is great for RAG applications.") # Load documents and create an index documents = SimpleDirectoryReader(dummy_data_dir).load_data() llm = OpenAI(model="gpt-3.5-turbo") index = VectorStoreIndex.from_documents(documents, llm=llm) query_engine = index.as_query_engine(llm=llm) print("\nPerforming LlamaIndex query...") response = query_engine.query("What is LlamaIndex good for?") print(f"LlamaIndex Response: {response}") print("\nTraces should be visible in the console.") # Clean up dummy data (optional) # import shutil # if os.path.exists(dummy_data_dir): # shutil.rmtree(dummy_data_dir)
Debug
Known issues
breakingThe OpenTelemetry GenAI semantic conventions are actively evolving. Recent versions (0.53.x and later) of `opentelemetry-instrumentation-llamaindex` have migrated span attributes to align with these newer conventions (e.g., OpenTelemetry GenAI Semantic Conventions 0.5.0).
fix
Review the latest OpenTelemetry GenAI semantic conventions documentation and update any custom dashboards, alerts, or queries that rely on specific span attribute names. You might need to adjust your observability backend's processing rules.
affects: >=0.53.0
gotchaThis instrumentation specifically targets the LlamaIndex library. It does not automatically instrument all underlying LLM calls (e.g., directly made `openai` or `anthropic` client calls outside of LlamaIndex's abstraction).
fix
For complete end-to-end tracing of your LLM application, ensure you also install and enable specific OpenTelemetry instrumentations for your LLM providers (e.g., `opentelemetry-instrumentation-openai`) if you interact with them directly.
affects: All
gotchaBy default, the LlamaIndex instrumentation captures and logs sensitive data such as prompts, completions, and embedding inputs/outputs as span attributes. This data will be visible in your tracing backend.
fix
If data privacy is a concern, consult the OpenTelemetry documentation for how to configure redaction or filtering of sensitive attributes. For `opentelemetry-instrumentation-llamaindex`, check for configuration options to disable or mask specific attribute collection if available, or implement custom `SpanProcessor` logic.
affects: All
gotchaSimply calling `LlamaIndexInstrumentor().instrument()` is insufficient for traces to be collected and exported. A full OpenTelemetry SDK setup, including a `TracerProvider`, `SpanProcessor`, and `SpanExporter`, must be configured and registered.
fix
Always ensure your application code initializes and configures the OpenTelemetry SDK components before enabling any instrumentations. Refer to the OpenTelemetry Python SDK documentation for proper setup of `TracerProvider`, `Resource`, `SpanProcessor`, and an appropriate `SpanExporter` (e.g., OTLP, Jaeger, Zipkin).
affects: All
Upgrade
Version history
0.62.3latest on PyPI · released Aug 10, 2026
Audit
Dependencies
llama-index-corerequiredRequired for LlamaIndex core functionalities which this library instruments.
openaioptionalCommonly used LLM provider for LlamaIndex applications; required for the quickstart example.
opentelemetry-sdkrequiredCore OpenTelemetry SDK components (TracerProvider, SpanProcessor, etc.) are implicitly required for a functional tracing setup.
PythonrequiredRequires Python 3.10 or newer, but less than 4.
Agent activity
30 hits · last 30 days
node
28
OpenAI (training)
1
Resources
opentelemetry-instrumentation-llamaindex — pip install opentelemetry-instrumentation-llamaindex · libregistry