---
title: "Flue"
description: "Learn how to send Flue agent traces, logs, and errors to Sentry."
url: https://docs.sentry.io/platforms/javascript/guides/node/agent-tracing/flue/
---

# Flue | Sentry for Node.js

[Flue](https://flueframework.com/) is an open TypeScript framework for building AI agents, made by the Astro team. Flue ships an official Sentry blueprint that installs the Sentry SDK, wires Flue's OpenTelemetry instrumentation into it, and bridges Flue's runtime events to Sentry. You don't need to add Sentry calls to each agent or tool.

With a valid `SENTRY_DSN`, Flue can send three connected signals to Sentry:

* **Traces**: When `SENTRY_TRACES_SAMPLE_RATE` is above `0`, Flue sends its `invoke_agent`, `chat`, and `execute_tool` span hierarchy with token usage, following the OpenTelemetry GenAI semantic conventions. Sentry shows these traces in [trace explorer](https://docs.sentry.io/product/trace-explorer.md), and builds a wider view for debugging your [agents](https://docs.sentry.io/product/agents.md).
* **Logs**: With `enableLogs: true` in the generated Sentry SDK configuration, every `log.info`, `log.warn`, and `log.error` call from your tools and hooks appears as [Sentry Logs](https://docs.sentry.io/platforms/javascript/guides/node/logs.md). When tracing is enabled, Sentry correlates these logs with the trace.
* **Issues**: The generated bridge captures terminal failures, such as a failed prompt, skill, task, or shell operation, as Sentry error issues. Recovered tool errors remain diagnostic context on the trace when tracing is enabled and don't create issues.

The blueprint installs `@sentry/node` for the Node.js target and `@sentry/cloudflare` for the Cloudflare target. Read the [Cloudflare version](https://docs.sentry.io/platforms/javascript/guides/cloudflare/agent-tracing/flue.md) of this page if you deploy Flue agents to Cloudflare.

## [Installation](https://docs.sentry.io/platforms/javascript/guides/node/agent-tracing/flue.md#installation)

From your project root, ask your coding agent to run the Sentry blueprint. The agent follows the blueprint to create a `sentry.ts` module next to `app.ts`, import it once, and install `@flue/opentelemetry` together with the Sentry SDK for your target:

```bash
flue add tooling sentry
```

If you start from a regular terminal, pipe the blueprint to your coding agent's CLI, replacing `<agent-command>` with its command:

```bash
flue add tooling sentry --print | <agent-command>
```

## [Configuration](https://docs.sentry.io/platforms/javascript/guides/node/agent-tracing/flue.md#configuration)

The generated module reads its configuration from environment variables. Only `SENTRY_DSN` is required.

| Variable                    | Default | Purpose                                                                                                                    |
| --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `SENTRY_DSN`                |         | Your project's [DSN](https://docs.sentry.io/concepts/key-terms/dsn-explainer.md). Without it, all Sentry calls are no-ops. |
| `SENTRY_ENVIRONMENT`        |         | The deployment environment, such as `production` or `staging`.                                                             |
| `SENTRY_RELEASE`            |         | The release identifier, such as a commit SHA.                                                                              |
| `SENTRY_TRACES_SAMPLE_RATE` | `0`     | A value from `0` to `1`. At `0`, Flue sends errors and logs only. Above `0`, Flue also sends AI traces.                    |
| `SENTRY_AI_RECORD_INPUTS`   | `false` | Set to `true` to include prompts, system instructions, and tool definitions and arguments in spans.                        |
| `SENTRY_AI_RECORD_OUTPUTS`  | `false` | Set to `true` to include model output, tool results, and exception messages and stacks in spans.                           |

```bash
SENTRY_DSN="https://<key>@o<orgId>.ingest.sentry.io/<projectId>"
SENTRY_TRACES_SAMPLE_RATE=1
```

Set `SENTRY_TRACES_SAMPLE_RATE=1` while you verify the setup. Lower it afterwards if your agent runs at high volume.

### [Record Prompts and Responses](https://docs.sentry.io/platforms/javascript/guides/node/agent-tracing/flue.md#record-prompts-and-responses)

By default, spans carry timing, token usage, model identifiers, and correlation IDs, but no message or tool content. Set `SENTRY_AI_RECORD_INPUTS` and `SENTRY_AI_RECORD_OUTPUTS` to `true` so the Agent Tracing transcript includes the full conversation, tool arguments, and tool results. The blueprint scrubs keys such as `token`, `secret`, and `password` and truncates each attribute to 16 KiB.

Review the data your agent handles before you enable these options in production.

## [How It Works](https://docs.sentry.io/platforms/javascript/guides/node/agent-tracing/flue.md#how-it-works)

On Node.js, the generated `sentry.ts` calls `Sentry.init` at module scope. Sentry becomes the global OpenTelemetry tracer provider, so the spans from `@flue/opentelemetry` flow to Sentry without extra wiring. The following abridged example shows the core of the generated file. It omits helper definitions and the terminal-failure capture implementation, so use the file generated by the blueprint rather than copying this example:

```typescript
import { createOpenTelemetryInstrumentation } from "@flue/opentelemetry";
import { instrument } from "@flue/runtime";
import * as Sentry from "@sentry/node";

// `clampRate` keeps the value between 0 and 1 and falls back to 0.
const tracesSampleRate = clampRate(
  process.env.SENTRY_TRACES_SAMPLE_RATE,
  0,
);

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  enabled: Boolean(process.env.SENTRY_DSN),
  tracesSampleRate,
  traceLifecycle: "stream",
  streamGenAiSpans: true,
  enableLogs: true,
  // Flue already emits one `chat` span per model call, so Sentry's
  // AI provider integrations are removed to avoid double counting.
  integrations: (defaults) =>
    defaults.filter((i) => !SENTRY_AI_PROVIDER_INTEGRATIONS.has(i.name)),
});

if (tracesSampleRate > 0) {
  instrument(
    createOpenTelemetryInstrumentation({ content: contentPolicy() }),
  );
}

instrument({
  key: Symbol.for("flue.sentry.bridge"),
  observe(event) {
    if (event.type === "operation" && event.isError) {
      // Terminal failures become issues.
    }
    if (event.type === "log") {
      Sentry.logger[event.level](event.message, logAttributes(event));
    }
  },
  interceptor: (_operation, _ctx, next) => next(),
  async dispose() {
    await Sentry.flush(2000);
  },
});
```

Because `Sentry.init` runs after the application starts importing modules, the blueprint does not enable Sentry's HTTP or database auto-instrumentation. If you need those, add the [preload setup](https://docs.sentry.io/platforms/javascript/guides/node/install.md) before your application imports and verify it against the built Flue server.

### [Correlation Tags](https://docs.sentry.io/platforms/javascript/guides/node/agent-tracing/flue.md#correlation-tags)

Issues, logs, and spans share the `flue.instance.id`, `flue.agent.name`, and `flue.submission.id` attributes. The conversation identifier is `flue.conversation.id` on issues and logs and `gen_ai.conversation.id` on spans. Search for a shared `flue.*` value in Sentry to find every signal from a single agent instance. Filter by `gen_ai.agent.name` to compare token use and latency across a lead agent and its subagents.

## [Verify](https://docs.sentry.io/platforms/javascript/guides/node/agent-tracing/flue.md#verify)

Set `SENTRY_TRACES_SAMPLE_RATE=1` against a non-production project, then:

1. Prompt a tool-using agent. Open [Agent Tracing](https://docs.sentry.io/product/agents.md) and confirm one trace with `invoke_agent`, `chat`, and `execute_tool` spans and token usage on the `chat` span.
2. Call `log.info` from a tool. Confirm the line appears in [Logs](https://docs.sentry.io/platforms/javascript/guides/node/logs.md) on the same trace.
3. Trigger one terminal failure. Confirm exactly one issue with the original error and stack trace.
4. Confirm that the application still starts without a configured DSN.

## [Troubleshooting](https://docs.sentry.io/platforms/javascript/guides/node/agent-tracing/flue.md#troubleshooting)

* **Logs and issues arrive but no traces.** `SENTRY_TRACES_SAMPLE_RATE` defaults to `0`. Set it above `0`.
* **Token and cost values are doubled.** Don't add a second AI tracing integration such as the [Vercel AI integration](https://docs.sentry.io/platforms/javascript/guides/node/agent-tracing/vercelai.md) or [Anthropic integration](https://docs.sentry.io/platforms/javascript/guides/node/agent-tracing/anthropic.md). The blueprint removes them on purpose because Flue already emits the model spans.
* **A tool error did not create an issue.** Only terminal operation and submission failures create issues. A recovered tool error stays on the trace as diagnostic context.

## [Supported Versions](https://docs.sentry.io/platforms/javascript/guides/node/agent-tracing/flue.md#supported-versions)

* `@sentry/node` or `@sentry/cloudflare`: `>=10.64.0`
* `@flue/opentelemetry`: the version that matches your Flue project

## [Next Steps](https://docs.sentry.io/platforms/javascript/guides/node/agent-tracing/flue.md#next-steps)

* [Instrument Flue agents with Sentry](https://sentry.io/cookbook/instrument-flue-agents-with-sentry/): a step-by-step cookbook with screenshots of the result in Sentry.
* [Monitor AI agent spend with dashboards and alerts](https://sentry.io/cookbook/monitor-ai-agent-spend-with-dashboards-and-alerts/): build a dashboard for cost, tokens, models, and conversations.
* [Flue's Sentry tooling page](https://flueframework.com/docs/ecosystem/tooling/sentry/) and [observability guide](https://flueframework.com/docs/guide/observability/): the same setup from the Flue side, and the event model behind it.