CrewAI

CrewAI Tracing Tutorial (Google Colab)

​

Prerequisites

• Python 3.10+
• An Arize AX account (sign up)
• An OPENAI_API_KEY from the OpenAI Platform
• CrewAI 1.0+ (this guide uses the native-SDK routing model introduced in 1.0; for 0.x see Troubleshooting)

​

Launch Arize AX

1. Sign in to your Arize AX account.
2. From Space Settings, copy your Space ID and API Key. You will set them as ARIZE_SPACE_ID and ARIZE_API_KEY below.

​

Install

pip install arize-otel \
  openinference-instrumentation-crewai \
  openinference-instrumentation-openai \
  crewai

​

Which instrumentor do I need?

​

Configure credentials

export ARIZE_SPACE_ID="<your-space-id>"
export ARIZE_API_KEY="<your-api-key>"
export ARIZE_PROJECT_NAME="crewai-tracing-example"
export OPENAI_API_KEY="<your-openai-api-key>"

​

Setup tracing

# instrumentation.py
import os

from arize.otel import register
from openinference.instrumentation.crewai import CrewAIInstrumentor
from openinference.instrumentation.openai import OpenAIInstrumentor

tracer_provider = register(
    space_id=os.environ["ARIZE_SPACE_ID"],
    api_key=os.environ["ARIZE_API_KEY"],
    project_name=os.environ["ARIZE_PROJECT_NAME"],
)

# Both instrumentors monkey-patch their target libraries — they must run
# before any `from crewai import ...` or any LLM client construction.
CrewAIInstrumentor().instrument(tracer_provider=tracer_provider)
OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)
print("Arize AX tracing initialized for CrewAI.")

​

Run CrewAI

# example.py

# Importing instrumentation first ensures both instrumentors run before
# CrewAI is imported. Out-of-order imports silently drop spans.
from instrumentation import tracer_provider

from crewai import Agent, Crew, LLM, Task

# `openai/gpt-5.5` tells CrewAI 1.0+ to use the native OpenAI SDK, which
# OpenAIInstrumentor patches. It reads OPENAI_API_KEY from the env.
llm = LLM(model="openai/gpt-5.5")

researcher = Agent(
    role="Ocean researcher",
    goal="Explain ocean facts to a general audience.",
    backstory="You are a marine scientist who values brevity.",
    llm=llm,
    allow_delegation=False,
    verbose=False,
)

writer = Agent(
    role="Science writer",
    goal="Turn researcher notes into a clean two-sentence summary.",
    backstory="You write clear, concise prose for a general audience.",
    llm=llm,
    allow_delegation=False,
    verbose=False,
)

research_task = Task(
    description=(
        "Explain why the ocean is salty. List the two primary mechanisms."
    ),
    expected_output="A short factual paragraph naming the two mechanisms.",
    agent=researcher,
)

writeup_task = Task(
    description=(
        "Using the researcher's notes, produce exactly two sentences "
        "for a general reader. No preamble."
    ),
    expected_output="Exactly two sentences, no headings.",
    agent=writer,
)

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writeup_task],
    verbose=False,
)

result = crew.kickoff()
print(result)

​

Expected output

Arize AX tracing initialized for CrewAI.
The ocean is salty because rivers continuously dissolve mineral salts from rocks and soil and carry them to the sea, where they accumulate over millions of years. Water leaves the ocean through evaporation but the salts remain, steadily concentrating until reaching today's roughly 3.5% salinity.

​

Verify in Arize AX

1. Open your Arize AX space and select project crewai-tracing-example.
2. You should see a new trace within ~30 seconds with this shape: a Crew_<uuid>.kickoff root span (CHAIN) wraps Crew Created, per-agent <role>._execute_core (AGENT), and per-task Task Created / Task Execution spans. Each task’s Task Execution wraps a ChatCompletion LLM span (model gpt-5.5, with prompt, response, and token usage attached).
3. If no traces appear, see Troubleshooting.

​

Check from the skill, CLI, or SDK

npx skills add Arize-ai/arize-skills

ax spans export "$ARIZE_PROJECT_NAME" --space "$ARIZE_SPACE_ID" \
  --limit 5 --stdout | jq 'length'

import os
from arize import ArizeClient

client = ArizeClient(api_key=os.environ["ARIZE_API_KEY"])
resp = client.spans.list(
    project=os.environ["ARIZE_PROJECT_NAME"],
    space=os.environ["ARIZE_SPACE_ID"],
    limit=5,
)
count = len(resp.spans)
print(
    f"{count} span(s) found" if count else "No spans yet — recheck setup"
)

// Reads ARIZE_API_KEY from the environment.
import { listSpans } from "@arizeai/ax-client";

const { data: spans } = await listSpans({
  project: process.env.ARIZE_PROJECT_NAME!,
  space: process.env.ARIZE_SPACE_ID!,
  limit: 5,
});
const count = spans.length;
console.log(
  count ? `${count} span(s) found` : "No spans yet — recheck setup",
);

client, err := arize.NewClient(
    arize.Config{APIKey: os.Getenv("ARIZE_API_KEY")},
)
if err != nil {
    log.Fatal(err)
}
resp, err := client.Spans.List(ctx, spans.ListRequest{
    Project: os.Getenv("ARIZE_PROJECT_NAME"),
    Space:   os.Getenv("ARIZE_SPACE_ID"),
    Limit:   5,
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%d span(s) found\n", len(resp.Spans))

​

Troubleshooting

• No traces in Arize AX. Confirm ARIZE_SPACE_ID and ARIZE_API_KEY are set in the same shell that runs example.py. Enable OpenTelemetry debug logs with export OTEL_LOG_LEVEL=debug and re-run.
• Crew / Agent / Task spans appear but no LLM spans. The LLM-level instrumentor doesn’t match the provider CrewAI is calling. CrewAI 1.0+ routes by model-string prefix:
  • openai/<model> (or no prefix) → install openinference-instrumentation-openai
  • anthropic/<model> → install openinference-instrumentation-anthropic
  • Groq / Together / providers without a native CrewAI SDK → install openinference-instrumentation-litellm (CrewAI falls back to LiteLLM for these)
• All spans missing — no Crew, no LLM. This is almost always import order. CrewAIInstrumentor().instrument(...) and the LLM-level instrumentor both monkey-patch class methods or module functions; if crewai (or the LLM library) is imported before instrument() runs, the patches land on stale references and never fire. Make sure instrumentation.py is the first import in your entry point — and watch for transitive imports (importing your own crew.py module that has from crewai import ... at the top has the same effect).
• 401 from OpenAI. Verify OPENAI_API_KEY is set and has access to gpt-5.5. Swap openai/gpt-5.5 in LLM(model=...) for a model your key can call.
• Version-check error from CrewAIInstrumentor. If you’re on a CrewAI release candidate that’s outside the instrumentor’s supported range, escape-hatch with CrewAIInstrumentor().instrument(skip_dep_check=True, tracer_provider=tracer_provider).
• You’re on CrewAI 0.x. 0.x routes every LLM call through LangChain or LiteLLM rather than provider-native SDKs. Pair the CrewAI instrumentor with both openinference-instrumentation-langchain and openinference-instrumentation-litellm instead of openinference-instrumentation-openai. The Setup tracing call list becomes CrewAIInstrumentor().instrument(...) + LangChainInstrumentor().instrument(...) + LiteLLMInstrumentor().instrument(...). Upgrade to 1.0+ when you can — the LiteLLM removal guide covers the migration.

​

Resources