Skip to main content
LlamaIndex is a data framework for LLM applications to ingest, structure, and access private or domain-specific data. For more details on LlamaIndex, refer to the official LlamaIndex documentation. LangWatch can capture traces generated by LlamaIndex by leveraging its built-in OpenTelemetry support. This guide will show you how to set it up.

​
Prerequisites

  1. Install LangWatch SDK: 
    pip install langwatch
  2. Install LlamaIndex and OpenInference instrumentor: 
    pip install llama-index openinference-instrumentation-llama-index
  3. Set up your LLM provider: You’ll need to configure your preferred LLM provider (OpenAI, Anthropic, etc.) with the appropriate API keys.

​
Instrumentation with OpenInference

LangWatch supports seamless observability for LlamaIndex using the OpenInference LlamaIndex instrumentor. This approach automatically captures traces from your LlamaIndex applications and sends them to LangWatch.

​
Basic Setup (Automatic Tracing)

Here’s the simplest way to instrument your application: 
import langwatch
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.llms.openai import OpenAI
from openinference.instrumentation.llama_index import LlamaIndexInstrumentor
import os

# Initialize LangWatch with the LlamaIndex instrumentor
langwatch.setup(
    instrumentors=[LlamaIndexInstrumentor()]
)

# Set up environment variables
os.environ["OPENAI_API_KEY"] = "your-openai-api-key"

# Create documents
documents = SimpleDirectoryReader('data').load_data()

# Create index
index = VectorStoreIndex.from_documents(documents)

# Create query engine
query_engine = index.as_query_engine()

# Use the query engine as usual—traces will be sent to LangWatch automatically
def run_query(user_question: str):
    response = query_engine.query(user_question)
    return response

# Example usage
if __name__ == "__main__":
    user_question = "What is the main topic of the documents?"
    response = run_query(user_question)
    print(f"Question: {user_question}")
    print(f"Answer: {response}")
That’s it! All LlamaIndex activity will now be traced and sent to your LangWatch dashboard automatically.

​
Optional: Using Decorators for Additional Context

If you want to add additional context or metadata to your traces, you can optionally use the @langwatch.trace() decorator: 
import langwatch
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.llms.openai import OpenAI
from openinference.instrumentation.llama_index import LlamaIndexInstrumentor
import os

langwatch.setup(
    instrumentors=[LlamaIndexInstrumentor()]
)

# ... index setup code ...

@langwatch.trace(name="LlamaIndex Query")
def run_query(user_question: str):
    # Update the current trace with additional metadata
    current_trace = langwatch.get_current_trace()
    if current_trace:
        current_trace.update(
            metadata={
                "user_id": "user_123",
                "session_id": "session_abc",
                "index_name": "my_documents",
                "model": "gpt-5"
            }
        )

    response = query_engine.query(user_question)
    return response

​
How it Works

  1. langwatch.setup(): Initializes the LangWatch SDK, which includes setting up an OpenTelemetry trace exporter. This exporter is ready to receive spans from any OpenTelemetry-instrumented library in your application.
  2. LlamaIndexInstrumentor(): The OpenInference instrumentor automatically patches LlamaIndex components to create OpenTelemetry spans for their operations, including:
    • Document loading and processing
    • Index creation and updates
    • Query execution
    • LLM calls
    • Retrieval operations
  3. Optional Decorators: You can optionally use @langwatch.trace() to add additional context and metadata to your traces, but it’s not required for basic functionality.
With this setup, all document processing, indexing, querying, and LLM interactions will be automatically traced and sent to LangWatch, providing comprehensive visibility into your LlamaIndex-powered applications.

​
Notes

  • You do not need to set any OpenTelemetry environment variables or configure exporters manually—langwatch.setup() handles everything.
  • You can combine LlamaIndex instrumentation with other instrumentors (e.g., OpenAI, LangChain) by adding them to the instrumentors list.
  • The @langwatch.trace() decorator is optional - the OpenInference instrumentor will capture all LlamaIndex activity automatically.
  • For advanced configuration (custom attributes, endpoint, etc.), see the Python integration guide.

​
Troubleshooting

  • Make sure your LANGWATCH_API_KEY is set in the environment.
  • If you see no traces in LangWatch, check that the instrumentor is included in langwatch.setup() and that your LlamaIndex code is being executed.
  • Ensure you have the correct API keys set for your chosen LLM provider.

​
Interoperability with LangWatch SDK

You can use this integration together with the LangWatch Python SDK to add additional attributes to the trace: 
import langwatch
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.llms.openai import OpenAI
from openinference.instrumentation.llama_index import LlamaIndexInstrumentor

langwatch.setup(
    instrumentors=[LlamaIndexInstrumentor()]
)

@langwatch.trace(name="Custom LlamaIndex Application")
def my_custom_llamaindex_app(user_question: str):
    # Your LlamaIndex code here
    documents = SimpleDirectoryReader('data').load_data()
    index = VectorStoreIndex.from_documents(documents)
    query_engine = index.as_query_engine()

    # Update the current trace with additional metadata
    current_trace = langwatch.get_current_trace()
    if current_trace:
        current_trace.update(
            metadata={
                "user_id": "user_123",
                "session_id": "session_abc",
                "index_name": "custom_index",
                "model": "gpt-5"
            }
        )

    # Run your query
    response = query_engine.query(user_question)

    return response
This approach allows you to combine the automatic tracing capabilities of LlamaIndex with the rich metadata and custom attributes provided by LangWatch.
⌘I