crewAI/docs/edge/en/observability/tracing.mdx

---
title: CrewAI Tracing
description: Built-in tracing for CrewAI Crews and Flows with the CrewAI AMP platform
icon: magnifying-glass-chart
mode: "wide"
---

# CrewAI Built-in Tracing

CrewAI provides built-in tracing capabilities that allow you to monitor and debug your Crews and Flows in real-time. This guide demonstrates how to enable tracing for both **Crews** and **Flows** using CrewAI's integrated observability platform.

> **What is CrewAI Tracing?** CrewAI's built-in tracing provides comprehensive observability for your AI agents, including agent decisions, task execution timelines, tool usage, and LLM calls - all accessible through the [CrewAI AMP platform](https://app.crewai.com). Tracing is managed independently from [telemetry](/en/telemetry).

![CrewAI Tracing Interface](/images/crewai-tracing.png)

## Prerequisites

Before you can use CrewAI tracing, you need:

1. **CrewAI AMP Account**: Sign up for a free account at [app.crewai.com](https://app.crewai.com)
2. **CLI Authentication**: Use the CrewAI CLI to authenticate your local environment

```bash
crewai login
```

## Setup Instructions

### Step 1: Create Your CrewAI AMP Account

Visit [app.crewai.com](https://app.crewai.com) and create your free account. This will give you access to the CrewAI AMP platform where you can view traces, metrics, and manage your crews.

### Step 2: Install CrewAI CLI and Authenticate

If you haven't already, install CrewAI with the CLI tools:

```bash
uv add 'crewai[tools]'
```

Then authenticate your CLI with your CrewAI AMP account:

```bash
crewai login
```

This command will:

1. Open your browser to the authentication page
2. Prompt you to enter a device code
3. Authenticate your local environment with your CrewAI AMP account
4. Enable tracing capabilities for your local development

### Step 3: Enable Tracing in Your Crew

You can enable tracing for your Crew by setting the `tracing` parameter to `True`:

```python
from crewai import Agent, Crew, Process, Task
from crewai_tools import SerperDevTool

# Define your agents
researcher = Agent(
    role="Senior Research Analyst",
    goal="Uncover cutting-edge developments in AI and data science",
    backstory="""You work at a leading tech think tank.
    Your expertise lies in identifying emerging trends.
    You have a knack for dissecting complex data and presenting actionable insights.""",
    verbose=True,
    tools=[SerperDevTool()],
)

writer = Agent(
    role="Tech Content Strategist",
    goal="Craft compelling content on tech advancements",
    backstory="""You are a renowned Content Strategist, known for your insightful and engaging articles.
    You transform complex concepts into compelling narratives.""",
    verbose=True,
)

# Create tasks for your agents
research_task = Task(
    description="""Conduct a comprehensive analysis of the latest advancements in AI in 2024.
    Identify key trends, breakthrough technologies, and potential industry impacts.""",
    expected_output="Full analysis report in bullet points",
    agent=researcher,
)

writing_task = Task(
    description="""Using the insights provided, develop an engaging blog
    post that highlights the most significant AI advancements.
    Your post should be informative yet accessible, catering to a tech-savvy audience.""",
    expected_output="Full blog post of at least 4 paragraphs",
    agent=writer,
)

# Enable tracing in your crew
crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    process=Process.sequential,
    tracing=True,  # Enable built-in tracing
    verbose=True
)

# Execute your crew
result = crew.kickoff()
```

### Step 4: Enable Tracing in Your Flow

Similarly, you can enable tracing for CrewAI Flows:

```python
from crewai.flow.flow import Flow, listen, start
from pydantic import BaseModel

class ExampleState(BaseModel):
    counter: int = 0
    message: str = ""

class ExampleFlow(Flow[ExampleState]):
    def __init__(self):
        super().__init__(tracing=True)  # Enable tracing for the flow

    @start()
    def first_method(self):
        print("Starting the flow")
        self.state.counter = 1
        self.state.message = "Flow started"
        return "continue"

    @listen("continue")
    def second_method(self):
        print("Continuing the flow")
        self.state.counter += 1
        self.state.message = "Flow continued"
        return "finish"

    @listen("finish")
    def final_method(self):
        print("Finishing the flow")
        self.state.counter += 1
        self.state.message = "Flow completed"

# Create and run the flow with tracing enabled
flow = ExampleFlow(tracing=True)
result = flow.kickoff()
```

### Step 5: View Traces in the CrewAI AMP Dashboard

Traces are uploaded only after a successful authenticated export or an explicitly approved anonymous upload. A run whose local buffer is discarded has no uploaded trace.
For traces associated with your account, open the [Traces tab in the CrewAI AMP dashboard](https://app.crewai.com/crewai_plus/trace_batches) to view agent interactions, tool usage, and LLM calls.
![CrewAI Tracing Interface](/images/view-traces.png)

### Alternative: Environment Variable Configuration

You can also enable tracing globally by setting an environment variable:

```bash
export CREWAI_TRACING_ENABLED=true
```

Or add it to your `.env` file:

```env
CREWAI_TRACING_ENABLED=true
```

When this environment variable is set, all Crews and Flows will automatically have tracing enabled, even without explicitly setting `tracing=True`.

## Viewing traces after your first run

The first time you run a Crew or Flow, an interactive terminal may ask:

```text
Share this execution trace with CrewAI? [y/N]
```

Choose **yes** to upload the buffered trace to CrewAI. Traces may contain
prompts, inputs, and outputs. Declining, timing out, or running without an
interactive consent prompt discards the buffer. You can change tracing later
with `crewai traces enable` or `crewai traces disable`, or by setting `tracing`
on the Crew or Flow.

### Local buffering and authenticated export

First-run trace collection stays in process memory until you agree to share,
even if you have saved login credentials. Unauthenticated tracing uses the same
consent flow. Before consent, CrewAI requests no upload grant and sends no
execution spans.

The buffer retains up to **1,000 spans** and **8 MiB of encoded OTLP data**.
Set `CREWAI_EPHEMERAL_TRACE_MAX_SPANS` and
`CREWAI_EPHEMERAL_TRACE_MAX_BYTES` to positive integers to adjust these limits.
Overflow drops the oldest spans; a span larger than the byte limit is dropped.
The buffer is cleared after sharing or discarding it.

When tracing is enabled and credentials are available, CrewAI exchanges your
CLI login, `CREWAI_USER_PAT`, or platform integration credential with AMP for
an execution-specific grant. It then exports OpenTelemetry spans directly to
Wharf using that grant. Invalid credentials do not fall back to anonymous upload.

### Hosted execution sessions

Hosts can wrap execution with `telemetry_session` from
`crewai.telemetry.tracing`. The session uses CrewAI lifecycle events to create
and finish spans, preserving their timestamps, parent relationships, and HITL
pause/resume links. Pass an existing provider with `providers=` to retain the
host's tracer and logging integration. Pass span processors with `processors=`
and a host logging callback with `log_emitter=`. The host owns any redaction
in these integrations.
Each session owns its tracing lifecycle and leaves the application's global
OpenTelemetry provider unchanged.

## Viewing Your Traces

### Access the CrewAI AMP Dashboard

1. Visit [app.crewai.com](https://app.crewai.com) and log in to your account
2. Navigate to your project dashboard
3. Click on the **Traces** tab to view execution details

### What You'll See in Traces

CrewAI tracing provides comprehensive visibility into:

- **Agent Decisions**: See how agents reason through tasks and make decisions
- **Task Execution Timeline**: Visual representation of task sequences and dependencies
- **Tool Usage**: Monitor which tools are called and their results
- **LLM Calls**: Track all language model interactions, including prompts and responses
- **Performance Metrics**: Execution times, token usage, and costs
- **Error Tracking**: Detailed error information and stack traces

### Trace Features

- **Execution Timeline**: Click through different stages of execution
- **Detailed Logs**: Access comprehensive logs for debugging
- **Performance Analytics**: Analyze execution patterns and optimize performance
- **Export Capabilities**: Download traces for further analysis

### Authentication Issues

If you encounter authentication problems:

1. Ensure you're logged in: `crewai login`
2. Check your internet connection
3. Verify your account at [app.crewai.com](https://app.crewai.com)

### Traces Not Appearing

If traces aren't showing up in the dashboard:

1. Confirm `tracing=True` is set in your Crew/Flow
2. Check that `CREWAI_TRACING_ENABLED=true` if using environment variables
3. For authenticated export, verify your CLI login, `CREWAI_USER_PAT`, or platform integration credential. For anonymous sharing, explicitly approve the consent prompt; login is not required
4. Verify your crew/flow executed and the trace export succeeded. Declining consent, timing out, or running without an interactive consent prompt discards the local buffer without uploading it