# Instrument Flue agents with Sentry

> Add Sentry to a Flue agent. Trace model calls and tools, correlate logs, and capture terminal agent failures as Sentry Issues.

**URL:** https://sentry.io/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.

**Time:** 15 minutes | **Difficulty:** Intermediate

## What You'll Learn

- 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

**Topics:** AI Observability, Agent Tracing, Logs, Issues, Tracing

**SDKs:** Node.js

## Before you start

**SDKs & packages**

- A working [Flue](https://flueframework.com/) project with at least one agent

- The Flue CLI available in the project

**Accounts & access**

- A [Sentry account](https://sentry.io/signup/) with a Node.js project

**Knowledge**

- Basic familiarity with Flue agents and environment variables

## Steps

### 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.

```bash
flue add tooling sentry
```

[Flue's Sentry tooling](https://flueframework.com/docs/ecosystem/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`.

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

[Sentry DSNs](https://docs.sentry.io/concepts/key-terms/dsn-explainer/)

### 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](https://github.com/getsentry/sentry-agent-tracing-examples/tree/main/github-harness-flue). 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](https://github.com/getsentry/sentry-agent-tracing-examples/tree/main/github-harness-flue)

### 5. Inspect the run in Sentry

Open [Explore > Agents](https://sentry.io/orgredirect/organizations/:orgslug/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](https://sentry.io/orgredirect/organizations/:orgslug/explore/logs/) for the correlated Flue logs and [Issues](https://sentry.io/orgredirect/organizations/:orgslug/issues/) for the terminal failure.

[Sentry AI agent monitoring](https://docs.sentry.io/product/agents/)

## Summary

**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.

## 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.

## FAQ

**Do I need to instrument every Flue agent and tool?**

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

**What does Flue send when tracing is disabled?**

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.

**Does this work on Cloudflare?**

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

**Are prompts and tool results sent by default?**

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.

## Next Steps

- [Review Flue observability](https://flueframework.com/docs/guide/observability/): Compare Flue's Sentry, OpenTelemetry, and Braintrust options and understand the span model that the framework emits.

- [Monitor agent spend](/cookbook/monitor-ai-agent-spend-with-dashboards-and-alerts/): Create a dashboard and monitors for cost, tokens, users, models, and conversations.

---

*Source: [sentry.io/cookbook/instrument-flue-agents-with-sentry/](https://sentry.io/cookbook/instrument-flue-agents-with-sentry/)*