Diagnostics Channel

node:diagnostics_channel is the runtime's built-in pub/sub for instrumentation. evlog can publish every wide event on the evlog.event channel, so a consumer subscribes by channel name alone — no evlog import, no entry in initLogger().

It is off by default. Turn it on once, at startup:

import { enableDiagnosticsChannel } from 'evlog/diagnostics'

export default defineNitroPlugin(async () => {
  await enableDiagnosticsChannel()
})

enableDiagnosticsChannel() is async because it loads node:diagnostics_channel lazily — that is what keeps the built-in out of the main bundle for Convex, workerd and other non-Node targets. Events emitted before the promise settles are not published, so call it at startup rather than inside a request.

Subscribing

The point of the channel is that a consumer needs nothing from evlog but the channel name:

import { subscribe } from 'node:diagnostics_channel'

subscribe('evlog.event', ({ event }) => {
  if (event.level === 'error') metrics.increment('errors', { path: event.path })
})

If you already depend on evlog and want the payload typed:

import { subscribeToWideEvents } from 'evlog/diagnostics'

const stop = await subscribeToWideEvents((event) => {
  //                                       ^? WideEvent
  if (typeof event.status === 'number' && event.status >= 500) {
    alerts.push({ path: String(event.path ?? '-'), requestId: String(event.requestId ?? '-') })
  }
})

Fields beyond the base event are typed unknown, and events emitted outside a request carry no HTTP fields at all — narrow before using them rather than casting.

What a subscriber receives

The same object a drain receives: post-audit, post-redaction, post-enrich. Requests carry everything enrichers added — geo, user agent, trace context:

{
  "timestamp": "2026-08-02T10:23:45.612Z",
  "level": "error",
  "service": "checkout",
  "environment": "production",
  "method": "POST",
  "path": "/api/checkout",
  "status": 500,
  "duration": "1.20s",
  "requestId": "4a8ff3a8-...",
  "user": { "id": "usr_123", "plan": "premium" },
  "error": { "name": "PaymentDeclined", "message": "Card declined" }
}

Events emitted outside a request (log.info({ ... }), createLogger().emit()) arrive without the HTTP fields, and events from log.fork() carry operation and _parentRequestId.

In pretty mode (the dev default), tagged logs like log.info('auth', 'User logged in') are written straight to the console and never become wide events, so they do not appear on the channel. Wide events themselves are published in both modes.

Cloudflare Workers

Workers forwards every diagnostics channel message to a Tail Worker automatically. Enable the channel and your wide events leave the isolate with no drain, no waitUntil, and their own CPU budget:

export default {
  tail(events) {
    for (const event of events) {
      for (const message of event.diagnosticsChannelEvents ?? []) {
        if (message.channel === 'evlog.event') forward(message.message.event)
      }
    }
  },
}

Requires the nodejs_compat flag, and forwarded values must be structured-cloneable.

When a plugin is the better tool

The channel is not a replacement for plugins — it is narrower on purpose:

diagnostics_channel is in-process: nothing attaches to a running process from the outside. A subscriber's code has to be loaded by your app either way — the channel saves it a line of configuration, not a dependency.