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

# Flue | Sentry for Cloudflare

[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/cloudflare/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.

## [Installation](https://docs.sentry.io/platforms/javascript/guides/cloudflare/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/cloudflare/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.                           |

Set the DSN as a Worker secret and the remaining values as variables in `wrangler.jsonc`:

```bash
wrangler secret put SENTRY_DSN
```

*Other available variations of the above snippet: json*

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/cloudflare/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/cloudflare/agent-tracing/flue.md#how-it-works)

On Cloudflare, each agent conversation runs in its own Durable Object isolate, so the generated `sentry.ts` does not call `Sentry.init`. Instead, it exports a `cloudflare` extension that wraps every generated agent Durable Object with [`instrumentDurableObjectWithSentry`](https://docs.sentry.io/platforms/javascript/guides/cloudflare/features/durableobject.md). The wrapper initializes the SDK once per isolate from the Worker's bindings. This abridged example omits helper definitions, so use the file generated by the blueprint rather than copying it:

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

// The per-isolate `env` bindings exist only inside the wrapper below, so the
// module-scope `instrument` gate reads `process.env` instead.
const tracesSampleRate = clampRate(
  process.env.SENTRY_TRACES_SAMPLE_RATE,
  0,
);

export const cloudflare = extend({
  wrap: (Final) =>
    Sentry.instrumentDurableObjectWithSentry(
      (env: Env) => ({
        dsn: env.SENTRY_DSN,
        enabled: Boolean(env.SENTRY_DSN),
        environment: env.SENTRY_ENVIRONMENT,
        release: env.SENTRY_RELEASE,
        tracesSampleRate: clampRate(env.SENTRY_TRACES_SAMPLE_RATE, 0),
        traceLifecycle: "stream",
        streamGenAiSpans: true,
        enableLogs: true,
        integrations: (defaults) =>
          defaults.filter(
            (i) => !SENTRY_AI_PROVIDER_INTEGRATIONS.has(i.name),
          ),
      }),
      Final,
    ),
});

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

Each agent module re-exports the extension so the build applies it:

```typescript
export { cloudflare } from "../sentry.ts";
```

The wrapper covers the agent Durable Objects only. It does not instrument the outer Worker or an authored Hono application. Wrap the Worker with [`withSentry`](https://docs.sentry.io/platforms/javascript/guides/cloudflare.md) if you also need request instrumentation. Don't use `@sentry/node` on Cloudflare.

The SDK sends traces and issues during the run and flushes logs on a best-effort basis through the platform's event lifecycle. An isolate shutdown can cut off very recently buffered logs.

### [Correlation Tags](https://docs.sentry.io/platforms/javascript/guides/cloudflare/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/cloudflare/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/cloudflare/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.

Also confirm that a wrapped agent delivers spans, logs, and issues from `workerd`, for example by running `wrangler dev`.

## [Troubleshooting](https://docs.sentry.io/platforms/javascript/guides/cloudflare/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/cloudflare/agent-tracing/vercelai.md) or [Anthropic integration](https://docs.sentry.io/platforms/javascript/guides/cloudflare/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/cloudflare/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/cloudflare/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.