# Agent Tracing: See Every Step of Your AI Agent Run

> Trace every AI agent run from model calls and tool executions to sub-agent handoffs, all inside your existing Sentry traces

**URL:** https://sentry.io/product/tracing/ai-agent/

---

Building with AI is unreliable. A dozen things can go wrong per run. Sentry traces the whole execution, linked to your app context, so you see the session, the run, and where it broke.

## Features

### See agent decisions and broader application context all in one trace

A bad agent response might stem from a slow database query, a failed API call, or a frontend timeout. Your gen_ai.* spans appear within your existing application traces. Model calls, tool executions, and handoffs sit alongside your regular HTTP, database, and queue spans in the same hierarchy.

### Replay every user session as a readable conversation

Conversations turn raw AI spans into a chat-like replay of any user session with your AI assistant. See the full message history as the user experienced it: inputs, responses, and tool calls in order. Click any message to jump to the underlying LLM generation and tool execution spans with timing and error context.

### Know what your agents cost and where the tokens go

Pre-built dashboards show agent runs, error rates, model costs, token breakdowns (input, output, cached, reasoning), and per-tool execution stats. See which models are expensive, which tools fail often, and whether your prompt caching is working.

### Find the tool that's quietly breaking your agent

Surface per-tool error rates, P95 latency, and invocation frequency. A tool failing 5% of the time may not move your overall error rate, but it causes 1 in 20 agent runs to produce bad output. Catch it here first.

## More Features

- **Auto-instrument 10+ agent frameworks**: Sentry auto-instruments OpenAI Agents, Vercel AI SDK, LangChain, LangGraph, Pydantic AI, Anthropic, Google GenAI, Laravel AI and more. Install the SDK, enable tracing, and spans show up — no manual instrumentation needed. — [Learn more](https://docs.sentry.io/platforms/python/agent-tracing/)

- **Trace MCP server interactions**: MCP tool calls appear as spans inside your agent traces. See which MCP servers your agent called, what they returned, how long they took, and whether they failed, all connected to the rest of the agent run. — [Learn more](https://sentry.io/resources/mcp-observability/)

- **Monitor cost per user, feature or agent**: Build custom dashboards to track cost per user tier, per feature, or per agent. Tag spans with user_tier, feature_flag, or whatever dimensions matter to your business, and query against them. — [Learn more](https://docs.sentry.io/product/agents/dashboards/)

## FAQ

**What is agent tracing?**

Agent tracing follows a single AI agent run from start to finish as a connected trace, capturing every LLM call, tool execution, MCP interaction, and handoff as a span with its inputs, outputs, token counts, cost, and timing. Because agents make decisions across many steps, a flat log isn't enough: agent tracing shows the full execution path so you can see exactly which step failed or stalled. [See how agent tracing works in Sentry](https://docs.sentry.io/product/agents/).

**How is agent tracing different from LLM monitoring?**

LLM monitoring measures individual model calls: latency, tokens, errors. Agent tracing tracks the complete agent lifecycle: multi-step reasoning, tool execution, sub-agent transfers, and how individual calls combine into workflows. Sentry does both. Individual LLM call data feeds into the same traces and dashboards as the full agent execution.

**How does agent tracing work with eval tools?**

Sentry agent tracing is complementary to eval workflows. Evals catch regressions against known test cases; agent traces show you the execution behind the score — which model was called, what the tool returned, where context was lost. When an eval flags a quality drop, the trace tells you why, and when something breaks that you didn't write an eval for, traces are how you find it first. [Read more about evals and traces](https://blog.sentry.io/spot-checking-ai-agents/).

**Does agent tracing work with my existing Sentry setup?**

Yes. Agent traces are part of your existing Sentry distributed traces. Your gen_ai.* spans appear alongside your HTTP, database, and queue spans in the same trace hierarchy. No separate product, no additional system. Add the SDK integration for your agent framework and agent spans start appearing in traces you already have.

**What agent frameworks are supported?**

Sentry auto-instruments OpenAI Agents, Vercel AI SDK, LangChain, LangGraph, Pydantic AI, Anthropic SDK, Google GenAI, and more — in both Python and JavaScript/Node.js. If your framework isn't auto-instrumented, manual instrumentation takes about 10 lines per span type. [See the full list](https://docs.sentry.io/ai/).

**Can I trace MCP server interactions?**

Yes. MCP tool calls appear as gen_ai.execute_tool spans inside your agent traces. You see which MCP servers were called, what data they returned, how long they took, and whether they errored — all connected to the agent run that triggered them. [Get started with MCP observability](https://sentry.io/resources/mcp-observability/).

**What does Conversations do?**

Conversations turns raw AI spans into a chat-like replay of any user session with your AI assistant. See the full message history as the user experienced it, and click any message to see the underlying spans. A single conversation can span multiple traces, Sentry stitches them using a stable gen_ai.conversation.id.

**Is agent tracing included in Sentry's free plan?**

Yes. Agent tracing, dashboards, and cost tracking are available on every Sentry plan, including the free Developer plan. [See pricing](https://sentry.io/pricing/).

## More on agent tracing

- [AI agent observability: The developer's guide to agent tracing](https://blog.sentry.io/ai-agent-observability-developers-guide-to-agent-monitoring/): Dashboards, traces, auto-instrumentation, and best practices for monitoring AI agents in production.

- [Reading the agent traces is how you make the call your eval can't](https://blog.sentry.io/spot-checking-ai-agents/): Why reading traces matters more than eval scores when you're making model, routing, and cost tradeoffs.

- [Sample AI traces at 100% without sampling everything](https://blog.sentry.io/sample-ai-traces-at-100-percent-without-sampling-everything/): How to capture every agent run while keeping baseline sampling for the rest of your app.

- [Debugging multi-agent AI: When the failure is in the space between agents](https://blog.sentry.io/debugging-multi-agent-ai-when-the-failure-is-in-the-space-between-agents/): Multi-agent observability is exponentially harder than single-agent monitoring. Here's how to trace, debug, and monitor AI systems where agents orchestrate other agents.

- [When agents orchestrate agents, who's watching?](https://blog.sentry.io/scaling-observability-for-multi-agent-ai-systems/): Multi-agent AI systems fail silently. Learn what proper observability looks like when agents orchestrate agents, and how Sentry keeps you in control.

- [Debugging our AI search assistant with agent tracing](https://blog.sentry.io/debugging-our-ai-search-assistant-with-agent-tracing/): How Sentry engineers used AI Conversations to debug a natural language search assistant and fix a tricky query generation bug.

- [Agent tracing docs](https://docs.sentry.io/product/agents/): Setup guides, supported frameworks, and reference for Sentry's agent tracing.

## Use Cases

- [Track AI SDK costs in Next.js](https://sentry.io/cookbook/monitor-ai-agent-costs-nextjs/)

- [Send AI SDK telemetry via OpenTelemetry](https://sentry.io/cookbook/vercel-ai-sdk-otel-sentry/)

- [Monitor Claude Code costs](https://sentry.io/cookbook/monitor-claude-code-with-sentry/)

- [Monitor OpenCode sessions](https://sentry.io/cookbook/monitor-opencode-with-sentry/)

- [Monitor Pi agent sessions](https://sentry.io/cookbook/monitor-pi-with-sentry/)

- [Monitor your MCP server](https://sentry.io/cookbook/monitor-mcp-server/)

- [Monitor Neon Functions](https://sentry.io/cookbook/monitor-neon-functions-sentry/)

- [Automate triage with Claude Routines](https://sentry.io/cookbook/automate-ai-agent-triage-claude-routines/)

- [Agent conversations to evals](https://sentry.io/cookbook/agent-conversations-to-evals/)

## Testimonials

> Sentry played a significant role in helping us develop [Claude] Sonnet

> — Nova DasSarma, Anthropic

## Quick Start

### Python

Install the Sentry Python SDK with pip

```bash
pip install sentry-sdk
```

Configuration should happen as early as possible in your application's lifecycle.

```python
import sentry_sdk

sentry_sdk.init(
  dsn="https://examplePublicKey@o0.ingest.sentry.io/0",
  # Add data like request headers and IP for users, if applicable;
  # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info
  send_default_pii=True,
  # Set traces_sample_rate to 1.0 to capture 100%
  # of transactions for tracing.
  traces_sample_rate=1.0,
  #Enable logs to be sent to Sentry
  enable_logs=True,
  # To collect profiles for all profile sessions,
  # set profile_session_sample_rate to 1.0.
  profile_session_sample_rate=1.0,
  # Profiles will be automatically collected while
  # there is an active span.
  profile_lifecycle="trace",
)
```

### JavaScript

Install the Sentry JavaScript SDK with npm

```bash
npm install @sentry/browser --save
```

Configuration should happen as early as possible in your application's lifecycle.

```javascript
import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  // Adds request headers and IP for users, for more info visit:
  // https://docs.sentry.io/platforms/javascript/configuration/options/#sendDefaultPii
  sendDefaultPii: true,
  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for tracing.
  tracesSampleRate: 1.0,
  // Set tracePropagationTargets to control for which URLs trace propagation should be enabled
  tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],
  // Enable logs to be sent to Sentry
  enableLogs: true,
  // Set profilesSampleRate to 1.0 to profile every transaction.
  // Since profilesSampleRate is relative to tracesSampleRate,
  // the final profiling rate can be computed as tracesSampleRate * profilesSampleRate
  // For example, a tracesSampleRate of 0.5 and profilesSampleRate of 0.5 would
  // result in 25% of transactions being profiled (0.5*0.5=0.25)
  profilesSampleRate: 1.0,
  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.browserProfilingIntegration(),
  ],
});
```

### React

Run the command for your preferred package manager to add the Sentry SDK to your application:

```bash
npm install @sentry/react --save
```

To import and initialize Sentry, create a file in your project's root directory, for example, `instrument.js`, and add the following code:

```javascript
import * as Sentry from "@sentry/react";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  // Adds request headers and IP for users, for more info visit:
  // https://docs.sentry.io/platforms/javascript/guides/react/configuration/options/#sendDefaultPii
  sendDefaultPii: true,
  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for tracing.
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
  tracesSampleRate: 1.0,
  // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled
  tracePropagationTargets: [/^//, /^https://yourserver.io/api/],
  // Enable logs to be sent to Sentry
  enableLogs: true,
  // Set profilesSampleRate to 1.0 to profile every transaction.
  // Since profilesSampleRate is relative to tracesSampleRate,
  // the final profiling rate can be computed as tracesSampleRate * profilesSampleRate
  // For example, a tracesSampleRate of 0.5 and profilesSampleRate of 0.5 would
  // result in 25% of transactions being profiled (0.5*0.5=0.25)
  profilesSampleRate: 1.0,
  integrations: [
    // If you're using react router, use the integration for your react router version instead.
    // Learn more at
    // https://docs.sentry.io/platforms/javascript/guides/react/features/react-router/
    Sentry.browserTracingIntegration(),
    Sentry.browserProfilingIntegration(),
  ],
});
```

Initialize Sentry as early as possible in your application. We recommend putting the import of your initialization code as the first import in your app's entry point:

```javascript
// Sentry initialization should be imported first!
import "./instrument";
import App from "./App";
import { createRoot } from "react-dom/client";

const container = document.getElementById("app");
const root = createRoot(container);
root.render(<App />);
```

To make sure Sentry captures all your app's errors, configure error handling based on your React version. 
 For React versions 19 and up:  

```javascript
import { createRoot } from "react-dom/client";
import * as Sentry from '@sentry/react';

const container = document.getElementById("app");
const root = createRoot(container, {
  // Callback called when an error is thrown and not caught by an ErrorBoundary.
  onUncaughtError: Sentry.reactErrorHandler((error, errorInfo) => {
    console.warn('Uncaught error', error, errorInfo.componentStack);
  }),
  // Callback called when React catches an error in an ErrorBoundary.
  onCaughtError: Sentry.reactErrorHandler(),
  // Callback called when React automatically recovers from errors.
  onRecoverableError: Sentry.reactErrorHandler(),
});
root.render();
```

For React versions 18 and below, use the ErrorBoundary component to automatically send errors from specific component trees to Sentry and provide a fallback UI:

```javascript
import React from "react";
import * as Sentry from "@sentry/react";

<Sentry.ErrorBoundary fallback={<p>An error has occurred</p>}>
  <Example />
</Sentry.ErrorBoundary>;
```

### Next.js

To install Sentry using the installation wizard, run thrun the following command and step through the prompts:

```bash
npx @sentry/wizard@latest -i nextjs
```

For manual installation run the following command and use the following configurations:

```bash
npm install @sentry/nextjs --save
```

Extend your app's default Next.js options by adding code with `withSentryConfig` into your `next.config.(js|mjs)` file:

```javascript
const { withSentryConfig } = require("@sentry/nextjs");
const nextConfig = {
  // Your existing Next.js configuration
};
// Make sure adding Sentry options is the last code to run before exporting
module.exports = withSentryConfig(nextConfig, {
  org: "example-org",
  project: "example-project",
  // Only print logs for uploading source maps in CI
  // Set to `true` to suppress logs
  silent: !process.env.CI,
  // Automatically tree-shake Sentry logger statements to reduce bundle size
  disableLogger: true,
});
```

#### Client-Side Configuration

```javascript
import * as Sentry from "@sentry/nextjs";
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  // Adds request headers and IP for users, for more info visit:
  // https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/options/#sendDefaultPii
  sendDefaultPii: true,
  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for tracing.
  // We recommend adjusting this value in production
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
  tracesSampleRate: 1.0,
  // Enable logs to be sent to Sentry
  enableLogs: true,
  // Set profilesSampleRate to 1.0 to profile every transaction.
  // Since profilesSampleRate is relative to tracesSampleRate,
  // the final profiling rate can be computed as tracesSampleRate * profilesSampleRate
  // For example, a tracesSampleRate of 0.5 and profilesSampleRate of 0.5 would
  // result in 25% of transactions being profiled (0.5*0.5=0.25)
  profilesSampleRate: 1.0,
});

// This export will instrument router navigations, and is only relevant if you enable tracing.
// `captureRouterTransitionStart` is available from SDK version 9.12.0 onwards
export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;
```

#### Server-Side Configuration

```javascript
import * as Sentry from "@sentry/nextjs";
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  // Adds request headers and IP for users, for more info visit:
  // https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/options/#sendDefaultPii
  sendDefaultPii: true,
  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for tracing.
  // We recommend adjusting this value in production
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
  tracesSampleRate: 1.0,
  // Enable logs to be sent to Sentry
  enableLogs: true,
});
```

#### Register Sentry Server-Side SDK Initialization

Create a Next.js Instrumentation file named `instrumentation.(js|ts)` in your project root or inside the `src` folder if you have one. Import your server and edge configurations, making sure that the imports point to your specific files:

```javascript
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./sentry.server.config");
  }
  if (process.env.NEXT_RUNTIME === "edge") {
    await import("./sentry.edge.config");
  }
}
```

### Go

Grab the Sentry Go SDK:

```bash
go get "github.com/getsentry/sentry-go"
```

Configuration should happen as early as possible in your application's lifecycle.

```text
err := sentry.Init(sentry.ClientOptions{
  Dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  // Enable printing of SDK debug messages.
  // Useful when getting started or trying to figure something out.
  Debug: true,
  // Adds request headers and IP for users,
  // visit: https://docs.sentry.io/platforms/go/data-management/data-collected/ for more info
  SendDefaultPII: true,
  EnableTracing: true,
  // Set TracesSampleRate to 1.0 to capture 100%
  // of transactions for tracing.
  TracesSampleRate: 1.0,
})
if err != nil {
  log.Fatalf("sentry.Init: %s", err)
}
// Flush buffered events before the program terminates.
// Set the timeout to the maximum duration the program can afford to wait.
defer sentry.Flush(2 * time.Second)
```

### Ruby

Add the sentry-ruby gem to your Gemfile:

```ruby
gem "sentry-ruby"
```

Configuration should happen as early as possible in your application's lifecycle.

```ruby
require 'sentry-ruby'

Sentry.init do |config|
  config.dsn = 'https://examplePublicKey@o0.ingest.sentry.io/0'

  # get breadcrumbs from logs
  config.breadcrumbs_logger = [:sentry_logger, :http_logger]

  # Add data like request headers and IP for users, if applicable;
  # see https://docs.sentry.io/platforms/ruby/data-management/data-collected/ for more info
  config.send_default_pii = true
  # enable tracing
  # we recommend adjusting this value in production
  config.traces_sample_rate = 1.0
  # Enable logs to be sent to Sentry
  config.enable_logs = true
  # enable profiling
  # this is relative to traces_sample_rate
  config.profiles_sample_rate = 1.0
end
```

### PHP

Install the Sentry SDK using Composer:

```bash
composer require sentry/sentry
```

To use Profiling, you'll also need to install the Excimer extension via PECL:

```bash
pecl install excimer
```

To capture all errors, even the one during the startup of your application, you should initialize the Sentry PHP SDK as soon as possible.

```php
\Sentry\init([
  'dsn' => 'https://examplePublicKey@o0.ingest.sentry.io/0',
  // Add request headers, cookies and IP address,
  // see https://docs.sentry.io/platforms/php/data-management/data-collected/ for more info
  'send_default_pii' => true,
  // Specify a fixed sample rate
  'traces_sample_rate' => 1.0,
  // Enable logs to be sent to Sentry
  'enable_logs' => true,
  // Set a sampling rate for profiling - this is relative to traces_sample_rate
  'profiles_sample_rate' => 1.0,
]);
```

### .NET

Install the NuGet package to add the Sentry dependency:

```shell
dotnet add package Sentry -v 5.16.2
```

To use Profiling, you'll also need to install the Sentry.Profiling package:

```shell
dotnet add package Sentry.Profiling -v 5.16.2
```

To capture all errors, even the one during the startup of your application, you should initialize the Sentry .NET SDK as soon as possible.

```csharp
SentrySdk.Init(options =>
{
    options.Dsn = "https://examplePublicKey@o0.ingest.sentry.io/0";
    options.Debug = true;
    // Adds request URL and headers, IP and name for users, etc.
    options.SendDefaultPii = true;
    // A fixed sample rate of 1.0 - 100% of all transactions are getting sent
    options.TracesSampleRate = 1.0f;
    // A sample rate for profiling - this is relative to TracesSampleRate
    options.ProfilesSampleRate = 1.0f;
});
```

---

*Source: [sentry.io/product/tracing/ai-agent/](https://sentry.io/product/tracing/ai-agent/)*