> ## Documentation Index
> Fetch the complete documentation index at: https://www.adaline.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# LlamaIndex

> Observe LlamaIndex workflows with Adaline.

# LlamaIndex

Use the Adaline LlamaIndex callback handler to send LlamaIndex events into Adaline. The integration attaches through LlamaIndex's callback manager and works well for LLM, retrieval, and workflow events emitted by the framework.

## Prerequisites

Before you start, make sure you have:

* An [Adaline account](https://app.adaline.ai/sign-up?utm_source=adaline.ai).
* A **workspace API key** — create one under **Settings → API keys**.
* Your **project ID** — copy it from **Monitor → Copy Project ID**.

See [Integrate your AI Agent](/get-started/integrate-your-ai-agent) for a full walkthrough.

Set both as environment variables before running the examples on this page:

```bash theme={null}
export ADALINE_API_KEY="your-api-key"
export ADALINE_PROJECT_ID="your-project-id"
```

## Install

```bash theme={null}
pip install adaline-client adaline-llama-index llama-index llama-index-llms-openai
```

Install LlamaIndex and the model-provider packages your application already uses alongside the Adaline integration package. If you use the OpenAI example below, make sure the corresponding LlamaIndex OpenAI package is also installed in your environment.

## Initialize Adaline

Create an Adaline client, then initialize a monitor for the target project.

```python theme={null}
import os

from adaline import Adaline

adaline = Adaline(api_key=os.environ["ADALINE_API_KEY"])
monitor = adaline.init_monitor(project_id=os.environ["ADALINE_PROJECT_ID"])
```

<Note>
  For production guidance — buffering, batching, retries, serverless flushing, and graceful shutdown — see [Instrument with the Adaline SDK](/instrument/with-adaline-sdks).
</Note>

## Attach the LlamaIndex callback handler

Create an `AdalineLlamaIndexCallbackHandler`, then add it to a `CallbackManager`.

```python theme={null}
from llama_index.core.callbacks import CallbackManager

from adaline_llama_index import AdalineLlamaIndexCallbackHandler

handler = AdalineLlamaIndexCallbackHandler(monitor=monitor)
callback_manager = CallbackManager([handler])
```

## Basic example

This example keeps the integration intentionally small: one `OpenAI` completion with the Adaline callback handler attached through the callback manager.

```python theme={null}
import asyncio
from llama_index.core.callbacks import CallbackManager
from llama_index.llms.openai import OpenAI as LlamaOpenAI

from adaline_llama_index import AdalineLlamaIndexCallbackHandler

async def main():
    parent_trace = monitor.log_trace(
        name="llamaindex-run",
        reference_id="llamaindex-run-1",
    )

    handler = AdalineLlamaIndexCallbackHandler(
        monitor=monitor,
        parent_trace=parent_trace,
        tags=["llamaindex"],
    )
    callback_manager = CallbackManager([handler])

    llm = LlamaOpenAI(
        model="gpt-4o-mini",
        max_tokens=20,
        callback_manager=callback_manager,
    )

    response = llm.complete("Say hello in one word.")

    parent_trace.end()
    await monitor.flush()


asyncio.run(main())
```

## Use an existing parent trace or span

The LlamaIndex handler accepts:

* `parent_trace`
* `parent_span`

Pass one or the other, but not both.

## Optional event filtering

The handler also accepts:

* `event_starts_to_ignore`
* `event_ends_to_ignore`

Use these when you want to suppress specific LlamaIndex callback event types from being observed.

## What the handler captures

The LlamaIndex callback handler is designed to capture LlamaIndex callback events, including:

* root trace creation for a LlamaIndex run
* nested event observations created during that run
* framework and trace metadata stored as Adaline attributes
* child spans under an Adaline parent when provided

This page focuses on wiring the callback manager. The exact span tree depends on the LlamaIndex events your application emits.

## Next steps

<CardGroup cols={2}>
  <Card title="Instrument with the Adaline SDK" icon="code" href="/instrument/with-adaline-sdks">
    Monitor lifecycle, buffering and batching, retries, serverless flushing, and graceful shutdown.
  </Card>

  <Card title="SDK reference" icon="braces" href="/reference/sdk/v2/overview">
    Full class and type reference for the TypeScript and Python SDKs.
  </Card>

  <Card title="All integrations" icon="layout-grid" href="/integrations/introduction">
    Browse every framework and AI-provider integration Adaline supports.
  </Card>

  <Card title="View your logs" icon="line-chart" href="https://app.adaline.ai">
    Open Adaline to see traces and spans land in your project.
  </Card>
</CardGroup>