{"id":2102,"library":"llama-index-instrumentation","title":"LlamaIndex Instrumentation","description":"The `llama-index-instrumentation` library provides robust observability tools for LlamaIndex applications, enabling tracing and logging capabilities, particularly through OpenTelemetry. It helps developers understand the flow and performance of their RAG pipelines. The current version is 0.5.0, and it's part of the frequently updated LlamaIndex ecosystem.","status":"active","version":"0.5.0","language":"en","source_language":"en","source_url":"https://github.com/run-llama/llama_index/tree/main/llama-index-instrumentation","tags":["LLM","LlamaIndex","Observability","Instrumentation","Tracing","OpenTelemetry"],"install":[{"cmd":"pip install llama-index-instrumentation","lang":"bash","label":"Install package"},{"cmd":"pip install opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-exporter-jaeger","lang":"bash","label":"Install OpenTelemetry dependencies (example)"}],"dependencies":[{"reason":"Provides core LlamaIndex functionalities that are being instrumented.","package":"llama-index-core","optional":false},{"reason":"Required for interacting with the OpenTelemetry tracing API.","package":"opentelemetry-api","optional":false},{"reason":"Required for implementing OpenTelemetry tracing (e.g., creating a TracerProvider).","package":"opentelemetry-sdk","optional":false}],"imports":[{"symbol":"OpenTelemetryInstrumentation","correct":"from llama_index_instrumentation.opentelemetry import OpenTelemetryInstrumentation"},{"note":"LlamaIndex has largely migrated from `ServiceContext` to the global `Settings` object for configuration.","wrong":"from llama_index.core.service_context import ServiceContext","symbol":"Settings","correct":"from llama_index.core.settings import Settings"},{"note":"A core OpenTelemetry class required for setting up the tracing backend.","symbol":"TracerProvider","correct":"from opentelemetry.sdk.trace import TracerProvider"}],"quickstart":{"code":"import os\nfrom llama_index.core.llms import MockLLM\nfrom llama_index.core.settings import Settings\nfrom llama_index_instrumentation.opentelemetry import OpenTelemetryInstrumentation\n\n# OpenTelemetry setup (CRITICAL for traces to be visible)\n# For a real application, you'd configure an OTLP/Jaeger exporter, etc.\n# This example prints traces to console.\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\n\nresource = Resource.create({\"service.name\": \"my-llama-app\"})\nprovider = TracerProvider(resource=resource)\nprovider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))\ntrace.set_tracer_provider(provider)\n\n# 1. Initialize OpenTelemetry Instrumentation\ninstrumentation = OpenTelemetryInstrumentation(tracer_provider=trace.get_tracer_provider())\n\n# 2. Enable instrumentation\ninstrumentation.enable()\n\n# 3. Configure LlamaIndex LLM\nSettings.llm = MockLLM()\n\n# 4. Perform a LlamaIndex operation\nresponse = Settings.llm.complete(\"Tell me a short story about a dragon.\")\nprint(f\"LLM Response: {response.text[:50]}...\")\n\n# 5. (Optional) Disable instrumentation when no longer needed\ninstrumentation.disable()\n","lang":"python","description":"This quickstart demonstrates how to set up `OpenTelemetryInstrumentation` for a LlamaIndex application. It includes the essential OpenTelemetry configuration to ensure traces are emitted (in this case, to the console), then enables the LlamaIndex instrumentation, performs a simple LLM call, and finally disables the instrumentation. The `opentelemetry-sdk` and an exporter (like `ConsoleSpanExporter` or `OTLPSpanExporter`) must be installed for traces to be processed."},"warnings":[{"fix":"Always ensure you initialize and set an OpenTelemetry `TracerProvider` with appropriate `SpanProcessor` and `SpanExporter` before enabling LlamaIndex instrumentation. See the quickstart example.","message":"Instrumentation requires a properly configured OpenTelemetry SDK `TracerProvider` to be set globally via `opentelemetry.trace.set_tracer_provider()`. Without this, no traces will be collected or exported, even if `instrumentation.enable()` is called.","severity":"gotcha","affected_versions":"All versions of llama-index-instrumentation using OpenTelemetry."},{"fix":"Upgrade your Python environment to 3.10 or newer. Python 3.11+ is generally recommended for optimal performance.","message":"Python 3.9 support has been deprecated across the LlamaIndex ecosystem. While older versions of `llama-index-instrumentation` might still function, official support is being phased out.","severity":"deprecated","affected_versions":"llama-index-core < 0.14.18 (and related packages, including instrumentation, are following this trend)."},{"fix":"Replace `ServiceContext` instantiation and usage with `llama_index.core.settings.Settings`. For example, instead of `ServiceContext.from_defaults(...)`, use `Settings.llm = ...`, `Settings.embed_model = ...` etc.","message":"LlamaIndex has largely migrated from using `ServiceContext` for global configurations (LLM, Embeddings, etc.) to a new `Settings` object. While `ServiceContext` might still exist in some legacy paths, new development should use `Settings`.","severity":"breaking","affected_versions":"llama-index-core >= 0.10.0 (and related packages including instrumentation)"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}