Registry /
llm-agents / llama-index-instrumentation
Install & Compatibility
Where this runs
tested against v0.5.0 · 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
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Dispatcher
✓ from llama_index_instrumentation import Dispatcher
✗ from llama_index_instrumentation import OpenTelemetryInstrumentation
root_dispatcher
✓ from llama_index_instrumentation import root_dispatcher
Manager
✓ from llama_index_instrumentation import Manager
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.
import os
from llama_index.core.llms import MockLLM
from llama_index.core.settings import Settings
from llama_index_instrumentation.opentelemetry import OpenTelemetryInstrumentation
# OpenTelemetry setup (CRITICAL for traces to be visible)
# For a real application, you'd configure an OTLP/Jaeger exporter, etc.
# This example prints traces to console.
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
resource = Resource.create({"service.name": "my-llama-app"})
provider = TracerProvider(resource=resource)
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider)
# 1. Initialize OpenTelemetry Instrumentation
instrumentation = OpenTelemetryInstrumentation(tracer_provider=trace.get_tracer_provider())
# 2. Enable instrumentation
instrumentation.enable()
# 3. Configure LlamaIndex LLM
Settings.llm = MockLLM()
# 4. Perform a LlamaIndex operation
response = Settings.llm.complete("Tell me a short story about a dragon.")
print(f"LLM Response: {response.text[:50]}...")
# 5. (Optional) Disable instrumentation when no longer needed
instrumentation.disable()
Debug
Known issues
gotchaInstrumentation 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.fixAlways ensure you initialize and set an OpenTelemetry `TracerProvider` with appropriate `SpanProcessor` and `SpanExporter` before enabling LlamaIndex instrumentation. See the quickstart example.
affects: All versions of llama-index-instrumentation using OpenTelemetry.
deprecatedPython 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.fixUpgrade your Python environment to 3.10 or newer. Python 3.11+ is generally recommended for optimal performance.
affects: llama-index-core < 0.14.18 (and related packages, including instrumentation, are following this trend).
breakingLlamaIndex 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`.fixReplace `ServiceContext` instantiation and usage with `llama_index.core.settings.Settings`. For example, instead of `ServiceContext.from_defaults(...)`, use `Settings.llm = ...`, `Settings.embed_model = ...` etc.
affects: llama-index-core >= 0.10.0 (and related packages including instrumentation)
Upgrade
Version history
0.5.0latest on PyPI · released Mar 12, 2026
Audit
Dependencies
llama-index-corerequiredProvides core LlamaIndex functionalities that are being instrumented.
opentelemetry-apirequiredRequired for interacting with the OpenTelemetry tracing API.
opentelemetry-sdkrequiredRequired for implementing OpenTelemetry tracing (e.g., creating a TracerProvider).