LlamaIndex Instrumentation

Warnings

• gotcha 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.
  Fix: Always ensure you initialize and set an OpenTelemetry `TracerProvider` with appropriate `SpanProcessor` and `SpanExporter` before enabling LlamaIndex instrumentation. See the quickstart example.
• deprecated 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.
  Fix: Upgrade your Python environment to 3.10 or newer. Python 3.11+ is generally recommended for optimal performance.
• breaking 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`.
  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.

Install

• pip install llama-index-instrumentation Install package
• pip install opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-exporter-jaeger Install OpenTelemetry dependencies (example)

Imports

• OpenTelemetryInstrumentation

  from llama_index_instrumentation.opentelemetry import OpenTelemetryInstrumentation

• Settings

  from llama_index.core.settings import Settings

  LlamaIndex has largely migrated from `ServiceContext` to the global `Settings` object for configuration.
• TracerProvider

  from opentelemetry.sdk.trace import TracerProvider

  A core OpenTelemetry class required for setting up the tracing backend.

Quickstart

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()