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.
• 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 for a full walkthrough.

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

export ADALINE_API_KEY="your-api-key"
export ADALINE_PROJECT_ID="your-project-id"

Install

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.

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"])

For production guidance — buffering, batching, retries, serverless flushing, and graceful shutdown — see Instrument with the Adaline SDK.

Attach the DSPy callback handler

Create an AdalineDSPyCallbackHandler, then register it through configure_dspy_observability.

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:

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.

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

Instrument with the Adaline SDK

Monitor lifecycle, buffering and batching, retries, serverless flushing, and graceful shutdown.

SDK reference

Full class and type reference for the TypeScript and Python SDKs.

All integrations

Browse every framework and AI-provider integration Adaline supports.

View your logs

Open Adaline to see traces and spans land in your project.