> ## 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.

# DSPy

> Observe DSPy programs with Adaline.

# DSPy

Use the Adaline DSPy integration to send DSPy callback activity into Adaline. The integration registers a DSPy callback handler and observes the predictor or module calls that DSPy emits.

## 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-dspy dspy
```

Install DSPy itself alongside the Adaline integration package.

## 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 DSPy callback handler

Create an `AdalineDSPyCallbackHandler`, then register it through `configure_dspy_observability`.

```python theme={null}
from adaline_dspy import (
    AdalineDSPyCallbackHandler,
    configure_dspy_observability,
)

handler = AdalineDSPyCallbackHandler(monitor=monitor)
configure_dspy_observability(handler)
```

`configure_dspy_observability` can also construct the handler for you if you pass `monitor=` directly:

```python theme={null}
from adaline_dspy import configure_dspy_observability

configure_dspy_observability(monitor=monitor)
```

## Basic example

This example keeps the integration intentionally small: one trivial `dspy.Predict` call after the Adaline handler has been registered.

```python theme={null}
import asyncio
import dspy

from adaline_dspy import (
    AdalineDSPyCallbackHandler,
    configure_dspy_observability,
)

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

    handler = AdalineDSPyCallbackHandler(
        monitor=monitor,
        parent_trace=parent_trace,
        tags=["dspy"],
    )
    configure_dspy_observability(handler)

    dspy.configure(lm=dspy.LM("openai/gpt-4o-mini", max_tokens=20))
    predictor = dspy.Predict("question -> answer")
    result = predictor(question="Say hello in one word.")

    parent_trace.end()
    await monitor.flush()


asyncio.run(main())
```

## Use an existing parent trace or span

The DSPy handler accepts:

* `parent_trace`
* `parent_span`

Pass one or the other, but not both.

## What the DSPy integration captures

The DSPy callback handler is designed to capture DSPy execution activity, including:

* predictor and module calls
* nested child calls under the active DSPy callback context
* framework, call, and instance metadata stored as Adaline attributes
* child spans under an Adaline parent when provided

This page focuses on how to register the handler. The exact span tree depends on the DSPy callbacks your program 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>