add diagnostics_channel publish at initialization time

docs/Hooks.md

@@ -564,3 +564,38 @@ fastify.route({
 ```
 
 **Note**: both options also accept an array of functions.
+
+## Diagnostics Channel Hooks
+
+Currently, one
+[`diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html) publish
+event, `'fastify:initialized'`, happens at initialization time. The Fastify
+instance is passed into the hook as a property of the object passed in. At this
+point, the instance can be interacted with to add hooks, plugins, routes or any
+other sort of modification.
+
+For example, a tracing package might do something like the following (which is,
+of course, a simplification). This would be in a file loaded in the
+initialization of the tracking package, in the typical "require instrumentation
+tools first" fashion.
+
+```js
+const tracer = /* retrieved from elsehwere in the package */
+const dc = require('diagnostics_channel')
+const channel = dc.channel('fastify:initialized')
+const spans = new WeakMap()
+
+channel.subscribe(function ({ fastify }) {
+  fastify.addHook('onRequest', (request, reply, done) => {
+    const span = tracer.startSpan('fastify.request')
+    spans.set(reqest, span)
+    done()
+  })
+
+  fastify.addHook('onResponse', (request, reply, done) => {
+    const span = spans.get(request)
+    span.finish()
+    done()
+  })
+})
+```

fastify.js

@@ -399,6 +399,17 @@ function fastify (options) {
   // Delay configuring clientError handler so that it can access fastify state.
   server.on('clientError', options.clientErrorHandler.bind(fastify))
 
+  try {
+    const dc = require('diagnostics_channel')
+    const initChannel = dc.channel('fastify:initialized')
+    if (initChannel.hasSubscribers) {
+      initChannel.publish({ fastify })
+    }
+  } catch {
+    // This only happens if `diagnostics_channel` isn't available, i.e. earlier
+    // versions of Node.js. In that event, we don't care, so ignore the error.
+  }
+
   return fastify
 
   function throwIfAlreadyStarted (msg) {

test/diagnostics-channel.test.js

@@ -0,0 +1,29 @@
+'use strict'
+
+const t = require('tap')
+const test = t.test
+let dc
+try {
+  dc = require('diagnostics_channel')
+} catch {
+  // Not available in this version of Node.js
+}
+
+test('diagnostics_channel', t => {
+  if (!dc) {
+    t.plan(1)
+    t.skip('diagnostics_channel is not available')
+    return
+  }
+  t.plan(2)
+
+  let fastifyInHook
+
+  const channel = dc.channel('fastify:initialized')
+  channel.subscribe(function ({ fastify }) {
+    t.pass('message passed to channel')
+    fastifyInHook = fastify
+  })
+  const fastify = require('../fastify')()
+  t.equal(fastifyInHook, fastify)
+})