Instructor integration

Instructor wraps OpenAI / Anthropic clients to enforce structured output against a Pydantic schema. It retries the LLM call when validation fails. Spanlens captures the underlying LLM HTTP calls plus the retry count and the validation error per retry, so you can see when one bad prompt is triggering three expensive retries.

Install (Python)

pip install spanlens instructor openai
bash

Minimal setup

from spanlens.integrations.openai import create_openai
import instructor
from pydantic import BaseModel

# Spanlens-instrumented OpenAI client
openai_client = create_openai()

# Wrap it with Instructor
client = instructor.from_openai(openai_client)

class UserInfo(BaseModel):
    name: str
    age: int

result = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=UserInfo,
    messages=[{"role": "user", "content": "Alex is 30."}],
)
python

Each underlying LLM call (including retries) lands in Spanlens as a separate request. They share the same trace ID so you can see all attempts for one logical operation in one trace view.

What gets captured

  • One request per attempt (initial call + every retry).
  • The response schema name (e.g. UserInfo) as a tag on the trace.
  • The validation error message on retries, captured in the request metadata.
  • Total trace cost = sum of all retry costs. Spanlens surfaces this as one number in the trace view so retry waste is visible.

Detecting expensive retry loops

Sort the trace list by retry_count desc to find prompts that are routinely retrying. A high-retry prompt is usually a schema mismatch (the schema is too strict for the model output style) or an underspecified prompt. Both are fixable in the prompt or schema without touching Instructor.

Where to go next