h3 tracing/diagnostic channels

[logaretm]

Part of covering Nitro's ecosystem with first-party support for tracing using tracing channels which is built on top of diagnostic channels.

I'm looking at fastify's diagnostic channel hooks since it does have a wide array of tracing events that are actively used by the community right now.

I think we could make use of both diagnostic and tracing channels here for various use-cases, this is my proposal for the events and scenarios to cover:

Hooking into the initialization of the H3 instance

This doesn't require a full tracing channel, just a diagnostic event that passes the h3 instance as an argument.

A good use-case for this event is registering global error handlers or adding global config:

import diag from 'node:diagnostics_channel';

// example name, but no point in having it follow the `tracing:` since it is not used for that.
const channel = diag.channel('h3.init');

channel.subscribe(({ app }) => {
  // Register a global error handler
  app.config.onError = onGlobalError;
});

Useful information to include in the payload:

• app the app instance that got initialized, listener can then configure it or read its properties.

Other than that, maybe those situations also need their own diagnostic event:

• Mounting a nested app: h3.mount

Request Handler Events

This would be a typical use-case for tracing channels since it would need to cover both sync/async use-cases and usually this is where spans gets created by instrumentations.

• tracing:h3.request.handler:start: Always fires
• tracing:h3.request.handler:end: Always fires, listeners will need to either use this or asyncEnd depending on the handler.
• tracing:h3.request.handler:asyncStart: Fires for promise/async handlers, usually start will be used most of the time here.
• tracing:h3.request.handler:asyncEnd: Fires for promise/async handlers
• tracing:h3.request.handler:error: Fires when an error occurs.

Since the tracingChannel function prefixes/postfixes those events, the main channel name would be h3.request.handler which would result in the set of 5 channels outlined above.

The payload itself for the event would typically include:

• request: the standard Request object.
• event: the h3 event object, probably redundant with request but no harm in including more info.
• A way to identify the nature of the handler being executed, could be either:
  • isMiddleware/isRoute: Very useful to identify if the handler being executed is a middleware or a route.
  • type instead of booleans, a string literal can be better here (type HandlerType = 'middleware' | 'route')

For the response, I'm not sure since it could be grabbed from the event but then again responses could be tricky to expose now, typically from an APM standpoint, you need a status code, status text and headers but rarely the response itself. So maybe the event is good enough here.

The error channel can contain the H3 error or whatever kind of error thrown by the pipeline.

I will work on a simple POC for this similar to the other work done around the other libraries.