Registry / llm-agents / llama-index-instrumentation

llama-index-instrumentation

JSON →
library0.5.0pypypi✓ verified 24d ago

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.

pip install llama-index-instrumentation
INSTALL
IMPORT
SIG · LLAMA-INDEX-INSTRU
L
llama-index-instrumentation
llm-agentspythonv0.5.0
Install
5.9s avg
Import
532ms
Disk
27MB
Pass rate
6/ 10
Env Coverage6 / 10
glibc
3.93.13
musl
3.93.13
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
musl
glibc
py 3.10
✓ —
✓ 5.1s
py 3.11
1/2 runs
1/2 runs
py 3.12
1/2 runs
1/2 runs
py 3.13
✓ —
✓ 5.25s
py 3.9
✓ —
✓ 7.25s
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.
fix
Always 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.
fix
Upgrade 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`.
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.
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).
Agent activity
18 hits · last 30 days
node
14
OpenAI (training)
2
Resources