feat: experimental built-in tracing channel support

[pi0]

This PR adds a new nitro config tracingChannel: true (or options) to enable built-in tracing channel support for internals.

Currently adding for h3 and srvx + db0 and unstorage comming soon thanks to @logaretm ❤️)

Node.js tracing channel is availabe in Node.js, Deno, Bun and also Cloudflare workers so it is kinda a universal and very lightweight standard for tracing events.

TODO:

• Node.js (prod)
• Deno and Bun
• Dev server

---

Example events:

[tracing:h3.request] asyncStart event={app,req,url,context}, type=middleware, result=undefined
[tracing:h3.request] asyncEnd event={app,req,url,context}, type=middleware, result=undefined
[tracing:h3.request] asyncStart event={app,req,url,context}, type=middleware, result=undefined
[tracing:h3.request] asyncEnd event={app,req,url,context}, type=middleware, result=undefined
[tracing:srvx.request] asyncStart request={runtime,waitUntil,context}, server={runtime,options,node,serveOptions,fetch}, result=Response(200 OK)
[tracing:srvx.request] asyncEnd request={runtime,waitUntil,context}, server={runtime,options,node,serveOptions,fetch}, result=Response(200 OK)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nitro.build	Ready	Preview, Comment	Apr 13, 2026 9:52pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: dbb772c8-5678-4d81-a5a6-372a35ecb5fa

📥 Commits

Reviewing files that changed from the base of the PR and between cf14fa7 and 3df7dda.

📒 Files selected for processing (1)

• docs/3.config/0.index.md

✅ Files skipped from review due to trivial changes (1)

• docs/3.config/0.index.md

---

📝 Walkthrough

Walkthrough

Adds a new top-level tracingChannel configuration, types, resolver, virtual template, runtime exports, and preset wiring to enable diagnostics_channel-based request tracing for srvx and h3; includes documentation updates.

Changes

Cohort / File(s)	Summary
Documentation docs/3.config/0.index.md	Adds documentation for tracingChannel config (default false, boolean or { srvx?: boolean, h3?: boolean }) with example.
Type Definitions src/types/config.ts	Adds TracingOptions and tracingChannel fields to NitroConfig/NitroOptions types.
Config Resolution src/config/resolvers/tracing.ts, src/config/loader.ts	Adds resolveTracingOptions resolver to normalize tracingChannel to object form and append #nitro/virtual/tracing plugin.
Virtual Template Generation src/build/virtual/tracing.ts, src/build/virtual/_all.ts	New virtual template #nitro/virtual/tracing that conditionally generates code for srvx/h3 tracing; added to virtualTemplates list.
Runtime Virtual Module src/runtime/virtual/tracing.ts	Introduces runtime module exporting default NitroAppPlugin and declared tracingSrvxPlugins array for imports.
Preset Integration src/presets/_nitro/runtime/nitro-dev.ts, src/presets/bun/runtime/bun.ts, src/presets/deno/runtime/deno-server.ts, src/presets/node/runtime/node-server.ts, src/presets/standard/preset.ts	Imports and spreads tracingSrvxPlugins into several runtime serve/preset plugin lists and adds srvx/tracing alias.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• perf!: resolve virtual templates with single plugin #3819: Adds/extends the virtual template system that this change builds on by introducing a new tracing virtual template and integrating it into the virtualTemplates pipeline.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title follows conventional commits format with 'feat:' prefix and clearly describes the main change: adding experimental built-in tracing channel support.
Description check	✅ Passed	The description is directly related to the changeset, explaining the new tracingChannel config option, supported integrations, and example events emitted.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/tracing

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/nitro@4001

commit: 7a1bbcd

[logaretm]

Looking good! The Sentry SDK is ready for release, but I see we have these items to tick down before release:

• Deno and Bun support
• Dev server (currently only h3 is traced, we need to migrate dev to srvx)
• Add tests

No rush or anything but can I help with those?

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

src/config/resolvers/tracing.ts (1)

5-9: Use defu for config merging in tracing resolver.

This resolver should use defu to align with the coding guideline for src/config/**/*.{ts,js} files and match the pattern used in other resolvers like runtime-config.ts and assets.ts.

defu(options.tracingChannel, { srvx: true, h3: true })

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/config/resolvers/tracing.ts` around lines 5 - 9, Replace the manual
object spread merge for options.tracingChannel with defu-based merging: import
and use defu to merge the defaults { srvx: true, h3: true } into
options.tracingChannel (i.e., call defu(options.tracingChannel, { srvx: true,
h3: true })) so the tracing resolver follows the same merge pattern as
runtime-config.ts and assets.ts and avoids overriding nested values; ensure defu
is imported where tracing.ts uses options.tracingChannel.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/3.config/0.index.md`:
- Line 1204: Update the documentation text that describes TracingChannel so it
explicitly states the runtime support scope: change the Node.js-only phrasing to
indicate that the tracingChannel instrumentation is wired for Node.js and also
supports Bun, Deno, and the development preset; reference the configuration
key/name tracingChannel (or tracingChannel option) and update the sentence to
mention the published channels `srvx.request` and `h3.request` remain available
across those runtimes so readers know the feature is not Node-exclusive.

In `@src/config/resolvers/tracing.ts`:
- Around line 10-11: The code always pushes the plugin id
"#nitro/virtual/tracing" onto options.plugins, which can cause duplicate
registrations; update the logic around options.plugins (where options.plugins is
initialized and where you push) to first ensure options.plugins exists and then
only push "#nitro/virtual/tracing" if it's not already present (e.g., check with
includes/indexOf) so the tracing plugin is registered exactly once.

---

Nitpick comments:
In `@src/config/resolvers/tracing.ts`:
- Around line 5-9: Replace the manual object spread merge for
options.tracingChannel with defu-based merging: import and use defu to merge the
defaults { srvx: true, h3: true } into options.tracingChannel (i.e., call
defu(options.tracingChannel, { srvx: true, h3: true })) so the tracing resolver
follows the same merge pattern as runtime-config.ts and assets.ts and avoids
overriding nested values; ensure defu is imported where tracing.ts uses
options.tracingChannel.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 21f3decf-16b8-4a0d-bfc6-3a98468bd075

📥 Commits

Reviewing files that changed from the base of the PR and between d054369 and cf14fa7.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (12)

• docs/3.config/0.index.md
• src/build/virtual/_all.ts
• src/build/virtual/tracing.ts
• src/config/loader.ts
• src/config/resolvers/tracing.ts
• src/presets/_nitro/runtime/nitro-dev.ts
• src/presets/bun/runtime/bun.ts
• src/presets/deno/runtime/deno-server.ts
• src/presets/node/runtime/node-server.ts
• src/presets/standard/preset.ts
• src/runtime/virtual/tracing.ts
• src/types/config.ts