← Back to Cookbook

Instrument Flue agents with Sentry

Use Flue's official Sentry blueprint to trace agent runs, inspect tool calls, correlate logs, and capture terminal failures.

Watch the video Jump to recipe
Features
AI Observability ,  Agent Tracing ,  Logs ,  Issues
SDKs
Node.js
Category Monitoring
Time
15 minutes
Complexity
Intermediate
Steps
5 steps

Before you start

SDKs & packages
  • A working Flue project with at least one agent
  • The Flue CLI available in the project
Accounts & access
Knowledge
  • Basic familiarity with Flue agents and environment variables

1
Add Flue's Sentry tooling

Run Flue's official blueprint from your project root. It installs the correct Sentry SDK for your target, adds @flue/opentelemetry, and wires the Sentry bridge into your application. You do not need to add Sentry calls to each agent or tool.

Flue's Sentry tooling
Bash
flue add tooling sentry

2
Configure Sentry

Copy your DSN from Settings > Projects > your project > Client Keys (DSN). Add it to your environment, then set the trace sample rate to 1 while you verify the setup. Flue sends logs and terminal failures when only the DSN is set, but AI traces require a sample rate above 0.

Sentry DSNs
Bash
SENTRY_DSN=https://<public-key>@o<org-id>.ingest.sentry.io/<project-id>
SENTRY_TRACES_SAMPLE_RATE=1
SENTRY_ENVIRONMENT=development

3
Record prompts and responses

Enable input and output capture so Explore > Agents includes the full transcript, tool arguments, and tool results. Review the data your agent handles before you use these settings in production.

Bash
SENTRY_AI_RECORD_INPUTS=true
SENTRY_AI_RECORD_OUTPUTS=true

4
Run a tool-using agent

Start Flue and run a task that calls a tool. Need a starting point? Try Sentry's Flue pull request review example. To test Issues, trigger a terminal failure in a safe environment. A recovered tool error stays on the trace; a failed operation creates an Issue.

Flue PR review example

5
Inspect the run in Sentry

Open Explore > Agents and open your test conversation. Check the transcript and tool calls, then use Timeline or the Trace link to inspect the span tree. Open Logs for the correlated Flue logs and Issues for the terminal failure.

Sentry AI agent monitoring
A Flue code review conversation in Sentry Explore Agents with model output and tool calls in the Transcript tab

That's it.

Your Flue agent is observable end to end.

One agent run now produces a connected record of model calls, tool executions, logs, and terminal failures in Sentry.

  • Added Flue's official Sentry tooling to an agent project
  • Configured traces and AI content capture
  • Generated a tool-using agent trace and a terminal failure
  • Connected Flue traces, logs, and issues in Sentry

Pro tips

  • 💡 Use a distinct SENTRY_ENVIRONMENT for local, staging, and production runs so test failures do not mix with production data.
  • 💡 Set SENTRY_RELEASE in deployments to connect agent failures with the code version that introduced them.
  • 💡 Filter by gen_ai.agent.name to compare token use and latency across a lead agent and its subagents.
  • 💡 Reduce SENTRY_TRACES_SAMPLE_RATE after verification if your agent runs at high volume.

Common pitfalls

  • ⚠️ Leaving SENTRY_TRACES_SAMPLE_RATE unset. Its default is 0, so logs and terminal failures arrive but AI traces do not.
  • ⚠️ Enabling input or output capture before reviewing your data policy. Prompts, tool arguments, and results can contain sensitive data.
  • ⚠️ Adding a second AI tracing integration. Flue already emits the model and tool spans, so a second producer can double-count tokens and cost.
  • ⚠️ Expecting every tool error to create an Issue. A recovered tool error stays on the trace; terminal operation and submission failures create Issues.

Frequently asked questions

No. The blueprint registers Flue's instrumentation at the application boundary. Agents, model calls, tools, and subagents use that shared setup.

With a valid DSN and a trace sample rate of 0, Flue still sends Sentry Logs and terminal failures as Issues. Set the rate above 0 to add AI traces.

Yes. The blueprint selects @sentry/cloudflare and wraps each generated agent Durable Object. Node.js targets use @sentry/node.

Flue leaves content capture off by default. This recipe enables SENTRY_AI_RECORD_INPUTS and SENTRY_AI_RECORD_OUTPUTS so the Agents transcript includes prompts, responses, tool arguments, and results. Disable either setting if that data should not leave your application.

What's next?

Review Flue observability

Compare Flue's Sentry, OpenTelemetry, and Braintrust options and understand the span model that the framework emits.
Read the Flue observability guide →

Monitor agent spend

Create a dashboard and monitors for cost, tokens, users, models, and conversations.
Build the spend dashboard →

Fix it, don't observe it.

Get started with the only application monitoring platform that empowers developers to fix application problems without compromising on velocity.

Try Sentry for Free Explore our Sandbox