feat: publish wide events on a node:diagnostics_channel

[HugoRCD]

🔗 Linked issue

📚 Description

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

Summary by CodeRabbit

• New Features

  • Added optional diagnostics-channel support for consuming enriched, audited, and redacted wide events.
  • Added typed subscription and unsubscribe APIs through the new evlog/diagnostics entry point.
  • Diagnostics publishing is disabled by default and loads only when enabled.
  • Events are delivered synchronously without delaying application processing.
  • Added support for forwarding events to Cloudflare Tail Workers.

• Documentation

  • Added setup guidance, compatibility details, usage examples, and recommendations for diagnostics-channel consumers.

[changeset-bot]

🦋 Changeset detected

Latest commit: d4a860d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
evlog	Minor
@evlog/cli	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
evlog-docs	Ready	Preview, v0	Aug 2, 2026 2:24pm
evlog-render-lab	Ready	Preview	Aug 2, 2026 2:24pm

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
evlog-telemetry	Skipped		Aug 2, 2026 2:24pm
just-use-evlog	Skipped		Aug 2, 2026 2:24pm

[github-actions]

Thank you for following the naming conventions! 🙏

[pkg-pr-new]

npm i https://pkg.pr.new/@evlog/cli@495

npm i https://pkg.pr.new/evlog@495

npm i https://pkg.pr.new/@evlog/nuxthub@495

npm i https://pkg.pr.new/@evlog/telemetry@495

commit: d4a860d

[coderabbitai]

Warning

Review limit reached

@HugoRCD, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 16 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 7a6809cc-77ca-40d6-a79e-c21a3e0827d7

📥 Commits

Reviewing files that changed from the base of the PR and between 7673eea and d4a860d.

📒 Files selected for processing (1)

• apps/docs/content/6.extend/11.diagnostics-channel.md

📝 Walkthrough

Walkthrough

Adds an opt-in evlog/diagnostics API that publishes post-audit, post-redaction, and post-enrichment wide events through node:diagnostics_channel. The change includes lazy loading, typed subscriptions, lifecycle controls, tests, benchmarks, package wiring, and documentation.

Changes

Diagnostics Channel

Layer / File(s)	Summary
Diagnostics API and lazy Node integration packages/evlog/src/diagnostics.ts, packages/evlog/src/shared/diagnostics-channel.node.ts, packages/evlog/tsdown.config.ts, packages/evlog/package.json	Adds channel enablement, typed subscriptions, unsubscribe disposers, Node channel helpers, and the ./diagnostics package export.
Wide-event publication pipeline packages/evlog/src/shared/wideEventChannel.ts, packages/evlog/src/logger.ts, packages/evlog/src/shared/middleware.ts	Publishes wide events before drain processing and contains publisher failures without interrupting logging.
Behavior, import, and performance validation packages/evlog/test/shared/diagnostics-channel.test.ts, packages/evlog/test/build/node-imports.test.ts, packages/evlog/bench/core/logger.bench.ts	Tests lifecycle, event contents, redaction, failures, subscriptions, lazy imports, and enabled or disabled emission costs.
Diagnostics channel documentation .changeset/diagnostics-channel.md, apps/docs/content/6.extend/0.overview.md, apps/docs/content/6.extend/11.diagnostics-channel.md	Documents setup, subscriptions, payload timing, synchronous delivery, Cloudflare forwarding, and extension-point selection.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Application
  participant Evlog
  participant DiagnosticsChannel
  participant Subscriber
  Application->>Evlog: emit wide event
  Evlog->>Evlog: audit, redact, and enrich
  Evlog->>DiagnosticsChannel: publish { event }
  DiagnosticsChannel->>Subscriber: synchronously deliver event
  Evlog->>Application: continue drain processing

Loading

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description contains only the template and does not explain the change, link an issue, or mark the documentation checklist.	Add a concise change summary, explain the purpose, link an issue or discussion if applicable, and mark the documentation checklist because docs were updated.
Docstring Coverage	⚠️ Warning	Docstring coverage is 69.23% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title uses a conventional feat prefix and accurately summarizes publishing wide events on node:diagnostics_channel.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch evl-202

---

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

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/docs/content/6.extend/11.diagnostics-channel.md`:
- Around line 52-58: Update the subscribeToWideEvents callback in the metrics.ts
example to handle events where event.path is absent, using a fallback or an API
compatible with an optional path instead of casting it directly to string.
Preserve the existing duration fallback and timing metric behavior.
- Around line 61-78: Update the typed examples in the diagnostics-channel
documentation to reference the canonical event.duration field instead of
event.durationMs, matching the formatted duration property shown in the JSON
payload. Preserve the existing WideEvent example structure and update every
affected typed usage.

In `@packages/evlog/src/shared/diagnostics-channel.node.ts`:
- Line 1: Update subscribeToChannel to obtain the diagnostics channel instance
with channel(name) and call its subscribe and unsubscribe methods with
onMessage, removing reliance on the top-level subscribe/unsubscribe imports.
Preserve the existing behavior used by subscribeToWideEvents and its tests
across all supported Node 18 versions.

🪄 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: ASSERTIVE

Plan: Pro Plus

Run ID: 880b206b-13a6-49c2-ab7d-d61f3986a365

📥 Commits

Reviewing files that changed from the base of the PR and between 31e5084 and 62d0a91.

⛔ Files ignored due to path filters (1)

• packages/evlog/test/toolkit/__snapshots__/api-surface.test.ts.snap is excluded by !**/*.snap

📒 Files selected for processing (13)

• .changeset/diagnostics-channel.md
• apps/docs/content/6.extend/0.overview.md
• apps/docs/content/6.extend/11.diagnostics-channel.md
• packages/evlog/bench/core/logger.bench.ts
• packages/evlog/package.json
• packages/evlog/src/diagnostics.ts
• packages/evlog/src/logger.ts
• packages/evlog/src/shared/diagnostics-channel.node.ts
• packages/evlog/src/shared/middleware.ts
• packages/evlog/src/shared/wideEventChannel.ts
• packages/evlog/test/build/node-imports.test.ts
• packages/evlog/test/shared/diagnostics-channel.test.ts
• packages/evlog/tsdown.config.ts