{"id":7474,"library":"openinference-instrumentation-llama-index","title":"OpenInference LlamaIndex Instrumentation","description":"OpenInference LlamaIndex Instrumentation is a Python auto-instrumentation library for LlamaIndex. It provides comprehensive observability for AI applications by generating OpenTelemetry-compatible traces for LlamaIndex operations such as queries, retrievals, LLM calls, and embeddings. The library is actively maintained with frequent updates across the OpenInference project.","status":"active","version":"4.3.9","language":"en","source_language":"en","source_url":"https://github.com/Arize-ai/openinference/tree/main/python/instrumentation/openinference-instrumentation-llama-index","tags":["observability","tracing","LLM","LlamaIndex","OpenTelemetry","AI","RAG"],"install":[{"cmd":"pip install openinference-instrumentation-llama-index","lang":"bash","label":"Install core package"},{"cmd":"pip install \"llama-index>=0.12.3\" openinference-instrumentation-llama-index opentelemetry-sdk opentelemetry-exporter-otlp","lang":"bash","label":"Install with compatible LlamaIndex and OpenTelemetry dependencies"}],"dependencies":[{"reason":"Required Python version range.","package":"python","version":"<3.15,>=3.10","optional":false},{"reason":"The core LlamaIndex library to be instrumented. Specific versions of this instrumentation are compatible with specific LlamaIndex versions.","package":"llama-index","version":">=0.12.3 (for openinference-instrumentation-llama-index >=4.0)","optional":false},{"reason":"Part of the OpenTelemetry Python SDK for tracing.","package":"opentelemetry-sdk","optional":false},{"reason":"OpenTelemetry OTLP HTTP exporter for sending traces to a collector.","package":"opentelemetry-exporter-otlp","optional":false},{"reason":"A popular OpenTelemetry collector and observability platform for viewing traces, often used in examples.","package":"arize-phoenix","optional":true}],"imports":[{"note":"Main class to initialize LlamaIndex instrumentation.","symbol":"LlamaIndexInstrumentor","correct":"from openinference.instrumentation.llama_index import LlamaIndexInstrumentor"},{"note":"Standard OpenTelemetry tracer provider setup.","symbol":"TracerProvider","correct":"from opentelemetry.sdk.trace import TracerProvider"},{"note":"Standard OpenTelemetry exporter for OTLP over HTTP.","symbol":"OTLPSpanExporter","correct":"from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter"},{"note":"Standard OpenTelemetry span processor.","symbol":"SimpleSpanProcessor","correct":"from opentelemetry.sdk.trace.export import SimpleSpanProcessor"},{"note":"Used to add resource attributes like project name to traces.","symbol":"Resource","correct":"from opentelemetry.sdk.resources import Resource"}],"quickstart":{"code":"import os\nfrom openinference.instrumentation.llama_index import LlamaIndexInstrumentor\nfrom openinference.semconv.resource import ResourceAttributes\nfrom opentelemetry import trace as trace_api\nfrom opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import SimpleSpanProcessor\n\nfrom llama_index.core import VectorStoreIndex, SimpleDirectoryReader\nfrom llama_index.llms.openai import OpenAI\nfrom llama_index.embeddings.openai import OpenAIEmbedding\nfrom llama_index.core import Settings\n\n# Set up OpenTelemetry for tracing\ndef setup_tracing():\n    collector_endpoint = os.environ.get(\"COLLECTOR_ENDPOINT\", \"http://localhost:6006/v1/traces\")\n    resource = Resource(attributes={ResourceAttributes.PROJECT_NAME: \"llama-index-demo\"})\n    tracer_provider = TracerProvider(resource=resource)\n    span_exporter = OTLPSpanExporter(endpoint=collector_endpoint)\n    span_processor = SimpleSpanProcessor(span_exporter=span_exporter)\n    tracer_provider.add_span_processor(span_processor=span_processor)\n    trace_api.set_tracer_provider(tracer_provider=tracer_provider)\n    LlamaIndexInstrumentor().instrument()\n    print(\"🔭 OpenInference LlamaIndex instrumentation enabled.\")\n\n# Main application logic\ndef main():\n    setup_tracing()\n\n    # Ensure OPENAI_API_KEY is set\n    if not os.environ.get(\"OPENAI_API_KEY\"):\n        print(\"Please set the OPENAI_API_KEY environment variable.\")\n        return\n\n    # Configure LLM and embeddings for LlamaIndex\n    Settings.llm = OpenAI(model=\"gpt-3.5-turbo\", temperature=0.1)\n    Settings.embed_model = OpenAIEmbedding(model=\"text-embedding-3-small\")\n\n    # Create a dummy data directory and file for demonstration\n    if not os.path.exists(\"data\"):\n        os.makedirs(\"data\")\n    with open(\"data/sample.txt\", \"w\") as f:\n        f.write(\"The quick brown fox jumps over the lazy dog. This is a sample document for LlamaIndex.\")\n\n    # Load documents and create an index\n    documents = SimpleDirectoryReader('data').load_data()\n    index = VectorStoreIndex.from_documents(documents)\n\n    # Query the index\n    query_engine = index.as_query_engine()\n    response = query_engine.query(\"What did the fox do?\")\n    print(f\"Response: {response}\")\n\n    print(\"\\nVisit your OpenTelemetry collector (e.g., Phoenix at http://localhost:6006) to see traces.\")\n\nif __name__ == \"__main__\":\n    main()","lang":"python","description":"This quickstart demonstrates how to instrument a basic LlamaIndex query engine with OpenInference. It sets up an OpenTelemetry `TracerProvider` and `OTLPSpanExporter` to send traces to a collector (e.g., Arize Phoenix). It then initializes the `LlamaIndexInstrumentor` and performs a simple query using LlamaIndex with OpenAI as the LLM, showing how operations like document loading, indexing, and querying are automatically traced."},"warnings":[{"fix":"Refer to the official OpenInference LlamaIndex documentation for the exact compatibility matrix. Ensure your `llama-index` version aligns with the `openinference-instrumentation-llama-index` version you are using.","message":"OpenInference LlamaIndex Instrumentation versions have specific compatibility requirements with LlamaIndex versions. Upgrading LlamaIndex without checking compatibility with the instrumentation can lead to runtime errors or incomplete tracing.","severity":"breaking","affected_versions":"<4.0 (requires LlamaIndex <0.12.3), >=4.0 (requires LlamaIndex >=0.12.3)"},{"fix":"To disable this logging, set the `TRACELOOP_TRACE_CONTENT` environment variable to `false`. Consult OpenInference documentation for more granular control over data masking.","message":"By default, OpenInference LlamaIndex instrumentation logs sensitive data such as prompts, completions, and embeddings to span attributes. This can be a privacy concern or lead to large trace payloads.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure OpenTelemetry context is properly propagated across threads. This often involves using a context manager or explicit context passing mechanisms provided by OpenTelemetry, or consulting the OpenInference documentation for best practices with async/threaded applications.","message":"When running LlamaIndex instrumentation within Python threads (e.g., in a FastAPI application), traces might appear 'malformed' or incomplete if context propagation is not properly handled.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Keep `openinference-instrumentation-llama-index` updated to the latest version. If using custom event types or advanced LlamaIndex workflows, check for specific support in the instrumentation's changelog or consider contributing to add support.","message":"The OpenInference LlamaIndex instrumentation may not handle all LlamaIndex event types, especially newer ones introduced in LlamaIndex Workflows, leading to 'Unhandled event of type' warnings and missing trace details.","severity":"gotcha","affected_versions":"Versions prior to updates addressing new LlamaIndex Workflow events (e.g., WorkflowStepOutputEvent)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `os.environ[\"OPENAI_API_KEY\"] = \"your_api_key\"` is called *before* any `llama_index` or `openai` imports, or that the `OPENAI_API_KEY` environment variable is set in your shell/deployment environment.","cause":"The OpenAI API key is not correctly set or is not accessible in the environment where LlamaIndex is being initialized, or it's being imported before the key is set.","error":"openai.error.AuthenticationError: No API key provided."},{"fix":"Update `openinference-instrumentation-llama-index` to the latest version. The OpenInference team frequently adds support for new LlamaIndex features. Check the project's GitHub issues or releases for specific updates.","cause":"The OpenInference instrumentation for LlamaIndex has encountered an event type (like `WorkflowStepOutputEvent` from LlamaIndex Workflows) that it doesn't currently explicitly handle, leading to a gap in tracing.","error":"WARNING Unhandled event of type WorkflowStepOutputEvent"},{"fix":"Verify the package is installed correctly using `pip show openinference-instrumentation-llama-index`. Correct the import statement to `from openinference.instrumentation.llama_index import LlamaIndexInstrumentor` if necessary.","cause":"The `openinference-instrumentation-llama-index` package is not installed, or there is a typo in the import statement.","error":"ImportError: cannot import name 'LlamaIndexInstrumentor' from 'openinference.instrumentation.llama_index'"}]}