Set Up Agent Tracing

With Sentry Agent Tracing, you can monitor and debug your AI systems with full-stack context. You'll be able to track key insights like token usage, latency, tool usage, and error rates — and group multi-turn chats in Conversations. Agent Tracing data is fully connected to your other Sentry data like logs, errors, and traces.

npx @sentry/ai install

Getting Started

Enable tracing and pass dataCollection so generative AI content follows the SDK defaults (including prompts and responses when left unconfigured).

dataCollection: {} also opts into other permissive defaults (bodies, cookies, user info, and more). Tighten via dataCollection.

import * as Sentry from "@sentry/cloudflare";

export default Sentry.withSentry(
  (env) => ({
    dsn: "___PUBLIC_DSN___",
    tracesSampleRate: 1.0,
    dataCollection: {},
  }),
  {
    async fetch(request, env, ctx) {
      // your worker
    },
  },
);

import * as Sentry from "@sentry/cloudflare";

export default Sentry.withSentry(
  (env) => ({
    dsn: "___PUBLIC_DSN___",
    tracesSampleRate: 1.0,
    dataCollection: {},
  }),
  {
    async fetch(request, env, ctx) {
      // your worker
    },
  },
);

Instrumentation

Pick your AI stack. Some libraries auto-instrument; others need a short setup — each page has the details.

Tracking Conversations

Conversations groups multi-turn AI activity into a single replay of messages and tool calls. Use setConversationId() so every AI span in a chat session shares the same gen_ai.conversation.id.

Some integrations infer a conversation ID automatically. For everything else (including Workers AI), set it yourself at the start of every request or operation that makes AI calls, before those calls run. Reuse the same session ID across messages in the chat. The ID is applied to AI-related spans on the current isolation scope (which is typically request-scoped). Pass null to unset it.

Sentry.setConversationId("conv_abc123");

Sentry.setConversationId("conv_abc123");

Identifying Users in Conversations

The Conversations view includes a User column. To populate it, call setUser once per request or session, before any AI calls:

Sentry.setUser({
  id: "user_123",
  email: "jane@example.com",
  username: "jane",
});

Sentry.setUser({
  id: "user_123",
  email: "jane@example.com",
  username: "jane",
});

Any of id, email, or username is sufficient — the Conversations view displays whichever fields are present. See the setUser API reference for the full list of supported fields.

Options

Privacy Controls

With dataCollection: {} (or any dataCollection config), generative AI inputs and outputs default to on. To turn them off:

export default Sentry.withSentry(
  (env) => ({
    dsn: "___PUBLIC_DSN___",
    tracesSampleRate: 1.0,
    dataCollection: {
      genAI: { inputs: false, outputs: false },
    },
  }),
  {
    async fetch(request, env, ctx) {
      /* ... */
    },
  },
);

export default Sentry.withSentry(
  (env) => ({
    dsn: "___PUBLIC_DSN___",
    tracesSampleRate: 1.0,
    dataCollection: {
      genAI: { inputs: false, outputs: false },
    },
  }),
  {
    async fetch(request, env, ctx) {
      /* ... */
    },
  },
);

Streaming Gen AI Spans

From SDK 10.61.0, gen_ai spans are sent as standalone envelope items (avoids large-payload drops; required for Conversations).

Self-hosted Sentry users should set streamGenAiSpans: false if standalone gen_ai spans may not be ingested.

export default Sentry.withSentry(
  (env) => ({
    dsn: "___PUBLIC_DSN___",
    tracesSampleRate: 1.0,
    streamGenAiSpans: false,
  }),
  {
    async fetch(request, env, ctx) {
      /* ... */
    },
  },
);

export default Sentry.withSentry(
  (env) => ({
    dsn: "___PUBLIC_DSN___",
    tracesSampleRate: 1.0,
    streamGenAiSpans: false,
  }),
  {
    async fetch(request, env, ctx) {
      /* ... */
    },
  },
);

Manual Instrumentation

You can also instrument agent spans yourself. See manual instrumentation.

MCP Server Monitoring

If you're building MCP (Model Context Protocol) servers, Sentry can also track tool executions, prompt retrievals, and resource access. See Instrument MCP Servers for setup instructions.