docs(javascript): Give Flue its own guide with SDK-based setup - #19528
Open
RulaKhaled wants to merge 6 commits into
Open
RulaKhaled wants to merge 6 commits into
RulaKhaled wants to merge 6 commits into
Conversation
The Flue page documented the `flue add tooling sentry` blueprint, which wires Sentry up through `@flue/opentelemetry`. The SDK now instruments Flue directly, so this replaces it with a guide per runtime — the two setups differ enough that one page with platform sections was hiding the important parts. On Node the SDK is registered with `instrument(Sentry.createFlueInstrumentation())`. On Cloudflare the Vite plugin registers it at build time, but each agent runs in its own Durable Object, so the guide leads with the wrapper that gets `Sentry.init()` into that isolate — without it nothing is captured and nothing errors, which is the failure people hit first. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
github-actions
Bot
added
the
Priority: Needs Triage
github-actions
Bot
added
Priority: Normal
…ing content forward The rework dropped sections the old page got right. Conversations come back as `gen_ai.conversation.id`, corrected from the blueprint's `flue.*` correlation tags, which the SDK does not emit. Adds `flue.turn.purpose` to the captured table, the doubling and missing-span troubleshooting entries, and Flue's own observability guide to next steps. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The Flue guide extends the Node guide through `fallbackGuide`, but `PlatformSection` doesn't resolve that, so `javascript.flue` has to be enumerated wherever `javascript.eve` already is — in both directions. Without it the inherited Node sections don't render in the Flue guide and browser-only content isn't hidden from it. 102 frontmatter entries and 37 PlatformSection arrays across 106 files, matching what #19445 does for `javascript.mastra`. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Master landed the same move for Mastra that this branch makes for Flue: lifting it out of the Agent Tracing page into its own guide. Almost every conflict was the two registrations landing on the same line. Resolutions: - Platform lists that gained `javascript.flue` here and `javascript.mastra` on master keep both, Flue first, matching the position after `javascript.eve`. - Master replaced the long explicit server-platform lists with `notSupportedCategories: server-only`. Took master's version and dropped the lists, which needed the Flue guide's `categories` fixed: it had `javascript` and `server-node`, neither of which is a `PlatformCategory`, so no category rule matched it. Now `server` and `server-only`, the same as Eve and Mastra. - `common/agent-tracing/mastra.mdx` is deleted on master, so this branch's edit to it goes away with the file. - `redirects.js` keeps both redirect blocks and drops the stale comment this branch had written to introduce Mastra's. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ides Master added `STANDALONE_AGENT_TRACING_GUIDES` when it lifted Mastra into its own guide, so every JavaScript guide's Agent Tracing section keeps a link-only entry pointing at the dedicated guide. This branch forked before that existed and deletes `common/agent-tracing/flue.mdx`, so Flue was dropping out of those sidebars entirely. `sidebar_order: 28` is the order the deleted page carried, which keeps Flue after Mastra and Eve where readers already expect it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Checked every claim in the guide against the SDK source and against a real `flue build` app (`@sentry/node@11.0.0-rc.1`, `@flue/runtime@2.0.3`, Node 24.11.1, live provider). What did not hold up: - "Instrument HTTP and Database Calls" is gone. Running the app with and without `NODE_OPTIONS='--import=@sentry/node/import'` produced the same spans both times: `http.server`, two `http.client` to the provider, and the full `gen_ai` set. The Node client constructor already calls `registerDiagnosticsChannelInjection()`, so `Sentry.init()` installs the hooks itself. The database half could never be true either — Flue's default `sqlite()` adapter is `node:sqlite`, which has no entry in `SENTRY_RUNTIME_INSTRUMENTATIONS`. - Registering twice does not stack observers. `createFlueInstrumentation()` sets `key: FLUE_INSTRUMENTATION_KEY`, so Flue throws `InstrumentationAlreadyInstalledError` in production and swaps the registration in dev. The warning described the keyless case. - "before Flue loads your agents" is not the requirement. A real `flue build` hoists `@flue/runtime` above the bundle body that runs `Sentry.init()`, and the spans still arrive. Running before a turn is what matters. - The conversation id is per conversation, not per agent instance. Two chat ids against one agent in one process produced two different `gen_ai.conversation.id` values. - `gen_ai.agent.name` lands only on the `invoke_agent` span, so it cannot be used to compare token use, which is recorded on the `chat` span. - Tool errors are always captured. `endToolSpan()` calls `captureToolError()` whenever `isError` is set, and the recovered case is exactly the one Flue hands back to the model, so nothing "stays on the trace as context". - The Cloudflare floor was wrong. `sentryFlueRuntimeProviderPlugin` is absent from `@sentry/cloudflare@11.0.0-rc.0` and first ships in rc.1. `@sentry/node`'s `createFlueInstrumentation` is in rc.0, so that floor stays. Verified and left alone: the `dataCollection.genAI` defaults (both `true` in `resolveDataCollectionOptions`), the operation mapping table, the `auto.ai.flue` origin, `flue.turn.purpose`, the `instrument.server.ts` troubleshooting note, and every API name on the Cloudflare page. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
JPeer264
reviewed
Sep 22, 2026
|
|
||
| ## Supported Versions | ||
|
|
||
| - `@sentry/node`: `>=11.0.0-rc.0` |
Member
There was a problem hiding this comment.
l: Maybe it's better to keep just one RC version in the docs, even if rc.0 is already supporting it. Or just move to v11: https://github.com/getsentry/sentry-docs/pull/19528/changes#r4071017479
Suggested change
| - `@sentry/node`: `>=11.0.0-rc.0` | |
| - `@sentry/node`: `>=11.0.0-rc.1` |
|
|
||
| - A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/). The project's DSN tells the SDK where to send data. | ||
| - A Flue application using `@flue/runtime` version `2.0.0` or later. Flue requires Node.js `22.19` or later. | ||
| - `@sentry/node` version `11.0.0-rc.0` or later, or [`@sentry/cloudflare@^11.0.0-rc.1` when running on Cloudflare](./cloudflare). Browser runtimes are not supported. |
Member
There was a problem hiding this comment.
l: Maybe we should wait 1 day and just move it to v11 right away?
Suggested change
| - `@sentry/node` version `11.0.0-rc.0` or later, or [`@sentry/cloudflare@^11.0.0-rc.1` when running on Cloudflare](./cloudflare). Browser runtimes are not supported. | |
| - `@sentry/node` or `@sentry/cloudflare` version `11.0.0` or later. Browser runtimes are not supported. |
| @@ -0,0 +1,122 @@ | |||
| --- | |||
Member
There was a problem hiding this comment.
q: Do we already have flue prepared to be part of platformicons? Would be nice to have a dedicated logo there
Collaborator
Author
There was a problem hiding this comment.
yah will open it separately
|
|
||
| Create a file that calls `Sentry.init()` and registers the Flue instrumentation. Flue is instrumented by registering with it rather than by patching, so this `instrument()` call is what connects the two: | ||
|
|
||
| ```typescript {filename:sentry-init.ts} |
Member
There was a problem hiding this comment.
l/q: Shouldn't this rather be instrumentation.ts or instrument.server.ts or something like that? Never seen sentry-init.ts before
Collaborator
Author
There was a problem hiding this comment.
oh true renamed to instrument.ts
|
|
||
| export const cloudflare = extend({ | ||
| wrap: (Final) => | ||
| Sentry.instrumentDurableObjectWithSentry( |
Member
There was a problem hiding this comment.
q: Do we need to wrap this? The Vite plugin should automatically instrument it actually. We would only need our Vite plugin and a instrument.server.ts - if it doesn't work we have to fix it, but could leave it as a first step.
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
DESCRIBE YOUR PR
Gives Flue its own JavaScript guide on the Sentry SDK-based setup, mirroring the Mastra guide (#19445). Based on the
node-flueandcloudflare-fluee2e test apps.fallbackGuide: javascript.node), so the Flue guide inherits the Node common pages. Adds theflueicon. Deletescommon/agent-tracing/flue.mdxand redirects it, Cloudflare page first.flue add tooling sentryblueprint, which wires Sentry up through@flue/opentelemetry. The SDK instruments Flue directly now. Adds a warning to remove the blueprint'screateOpenTelemetryInstrumentationcall, which double-countsgen_aispans.Sentry.init()plusinstrument(Sentry.createFlueInstrumentation()), imported as the first line ofsrc/app.ts. Flue is registered rather than patched, so that call is the wiring.sentryCloudflareVitePlugin()registers the instrumentation at build time, so there's noinstrument()call. Each agent runs in its own Durable Object, so the guide leads with theextend({ wrap })wrapper that getsSentry.init()into that isolate — without it the agent runs fine, turns settle, nothing errors, and nothing is captured.instrument.server.tsdoes nothing for Flue. That convention needs a worker entry in Wrangler'smain; Flue supplies its own virtual entry instead. Verified againstcloudflare-flue.@sentry/node/@sentry/cloudflare>=11.0.0-rc.0and@flue/runtime>=2.0.0 <3.0.0. Corrects the old Correlation Tags section: the SDK emitsgen_ai.conversation.id,gen_ai.agent.name, andflue.turn.purpose, not the blueprint'sflue.instance.id/flue.agent.name/flue.submission.id.javascript.flueto everysupported/notSupportedlist in JS common content whereverjavascript.eveappears (106 files), so inherited Node sections render and browser-only content is hidden from the Flue guide.PlatformSectiondoesn't resolvefallbackGuide, sojavascript.fluemust be enumerated alongsidejavascript.node/javascript.evein both directions.Follow-ups: Flue needs a
STANDALONE_AGENT_TRACING_GUIDESentry (sidebar_order: 28) once #19445 lands; the version pins need revisiting once getsentry/sentry-javascript#24476 ships; and the double-counting warning is reasoned from both instrumentations registering throughinstrument()under different keys, not run against the blueprint.IS YOUR CHANGE URGENT?
Help us prioritize incoming PRs by letting us know when the change needs to go live.
Select exactly one option. For deadlines, replace
YYYY-MM-DDwith the due date. You can update this information later by editing the PR description.SLA
Thanks in advance for your help!
PRE-MERGE CHECKLIST
Make sure you've checked the following before merging your changes: