OpenTelemetry LlamaIndex Instrumentation

0.58.0 · active · verified Thu Apr 09

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.

Warnings

breaking The 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.
gotcha This 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.
gotcha By 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.
gotcha Simply 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).

Install

pip install opentelemetry-instrumentation-llamaindex llama-index-core openai Install core and example dependencies

Imports

LlamaIndexInstrumentor

from opentelemetry.instrumentation.llamaindex import LlamaIndexInstrumentor

Quickstart

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)

view raw JSON →