feat: undici and fetch() instrumentation (#2858)

Instrument the undici HTTP client library and Node's core `fetch()`.

Closes: #2383

Author: trentm

.ci/.jenkins_tav.yml

@@ -31,4 +31,5 @@ TAV:
   - redis
   - restify
   - tedious
+  - undici
   - ws

.tav.yml

@@ -551,3 +551,11 @@ aws-sdk:
     - node test/instrumentation/modules/aws-sdk/sns.test.js
     - node test/instrumentation/modules/aws-sdk/sqs.test.js
     - node test/instrumentation/modules/aws-sdk/dynamodb.test.js
+
+# - [email protected] added its diagnostics_channel support.
+# - In [email protected] the `request.origin` property was added, which we need
+#   in the 'undici:request:create' diagnostic message.
+undici:
+  versions: '>=4.7.1 <6'
+  commands: node test/instrumentation/modules/undici/undici.test.js
+  node: '>=12.18'

CHANGELOG.asciidoc

@@ -39,6 +39,14 @@ Notes:
 [float]
 ===== Features
 
+- Add instrumentation for the https://undici.nodejs.org[undici] HTTP client
+  library. This also adds instrumentation of Node.js v18's
+  https://nodejs.org/api/all.html#all_globals_fetch[`fetch()`], which uses
+  undici under the hood. For the instrumentation to work one must be using
+  node v14.17.0 or later, or have installed the
+  https://www.npmjs.com/package/diagnostics_channel['diagnostics_channel' polyfill].
+  ({issues}2383[#2383])
+
 - Added `exitSpanMinDuration` configuration field, allowing end users to
   set a time threshold for dropping exit spans. ({pull}2843[#2843])
 

docs/supported-technologies.asciidoc

@@ -145,6 +145,7 @@ so those should be supported as well.
 |https://www.npmjs.com/package/pg[pg] |>=4.0.0 <9.0.0 |Will instrument all queries
 |https://www.npmjs.com/package/redis[redis] |>=2.0.0 <4.0.0 |Will instrument all queries
 |https://www.npmjs.com/package/tedious[tedious] |>=1.9 <15.0.0 | (Excluding v4.0.0.) Will instrument all queries
+|https://www.npmjs.com/package/undici[undici] | >=4.7.1 <6 | Will instrument undici HTTP requests, except HTTP CONNECT. Requires node v14.17.0 or later, or the user to have installed the https://www.npmjs.com/package/diagnostics_channel['diagnostics_channel' polyfill].
 |https://www.npmjs.com/package/ws[ws] |>=1.0.0 <8.0.0 |Will instrument outgoing WebSocket messages
 |=======================================================================
 

examples/trace-elasticsearch8.js

@@ -18,15 +18,15 @@ const apm = require('../').start({ // elastic-apm-node
   logUncaughtExceptions: true
 })
 
-// Currently, pre-releases of v8 are published as the "...-canary" package name.
 // eslint-disable-next-line no-unused-vars
-const { Client, HttpConnection } = require('@elastic/elasticsearch-canary')
+const { Client, HttpConnection } = require('@elastic/elasticsearch')
 
 const client = new Client({
-  // With version 8 of the client, you can use `HttpConnection` to use the old
-  // HTTP client:
+  // By default version 8 uses the new undici HTTP client lib. You can specify
+  // `HttpConnection` to use the older HTTP client.
   // Connection: HttpConnection,
-  node: `http://${process.env.ES_HOST || 'localhost'}:9200`
+  node: `http://${process.env.ES_HOST || 'localhost'}:9200`,
+  maxRetries: 1
 })
 
 async function run () {

examples/trace-fetch.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node --no-warnings
+
+/*
+ * Copyright Elasticsearch B.V. and other contributors where applicable.
+ * Licensed under the BSD 2-Clause License; you may not use this file except in
+ * compliance with the BSD 2-Clause License.
+ */
+
+// This example shows use of Node v18's core `fetch()`. The Node.js APM agent
+// will automatically instrument it.
+
+/* global fetch */ // for eslint
+
+const apm = require('../').start({
+  serviceName: 'example-trace-fetch'
+})
+
+const url = process.argv[2] || 'https://httpstat.us/200'
+
+async function main () {
+  // For tracing spans to be created, there must be an active transaction.
+  // Typically, a transaction is automatically started for incoming HTTP
+  // requests to a Node.js server. However, because this script is not running
+  // an HTTP server, we manually start a transaction. More details at:
+  // https://www.elastic.co/guide/en/apm/agent/nodejs/current/custom-transactions.html
+  const trans = apm.startTransaction('trans')
+  try {
+    const res = await fetch(url)
+    for (const [k, v] of res.headers) {
+      console.log(`${k}: ${v}`)
+    }
+    const body = await res.text()
+    console.log('\n' + body)
+  } catch (err) {
+    console.error('fetch error:', err)
+  } finally {
+    if (trans) trans.end()
+  }
+}
+
+main()

examples/trace-undici.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node --no-warnings
+
+/*
+ * Copyright Elasticsearch B.V. and other contributors where applicable.
+ * Licensed under the BSD 2-Clause License; you may not use this file except in
+ * compliance with the BSD 2-Clause License.
+ */
+
+// This example shows the Node.js APM agent's instrumentation of the 'undici'
+// HTTP client library.
+//
+// Set `ELASTIC_APM_SERVER_URL` and `ELASTIC_APM_SECRET_TOKEN` environment
+// variables to configure the APM agent, then run this script.
+
+const apm = require('../').start({
+  serviceName: 'example-trace-undici',
+  usePathAsTransactionName: true // for our simple HTTP server
+})
+
+const http = require('http')
+const undici = require('undici')
+
+// Start a simple HTTP server that we will call with undici.
+const server = http.createServer((req, res) => {
+  console.log('incoming request: %s %s %s', req.method, req.url, req.headers)
+  req.resume()
+  req.on('end', function () {
+    const resBody = JSON.stringify({ ping: 'pong' })
+    setTimeout(() => {
+      res.writeHead(200, {
+        'content-type': 'application/json',
+        'content-length': Buffer.byteLength(resBody)
+      })
+      res.end(resBody)
+    }, 100) // Take ~100ms to respond.
+  })
+})
+server.listen(3000, async () => {
+  // For tracing spans to be created, there must be an active transaction.
+  // Typically, a transaction is automatically started for incoming HTTP
+  // requests to a Node.js server. However, because the undici calls are not
+  // in the context of an incoming HTTP request we manually start a transaction.
+  // More details at:
+  // https://www.elastic.co/guide/en/apm/agent/nodejs/current/custom-transactions.html
+  const trans = apm.startTransaction('trans', 'manual')
+
+  // Make a handful of requests and use Undici's pipelining
+  // (https://undici.nodejs.org/#/?id=pipelining) to show concurrent requests.
+  const client = new undici.Client('http://localhost:3000', {
+    pipelining: 2
+  })
+  let lastReq
+  for (let i = 0; i < 4; i++) {
+    lastReq = client.request({ method: 'GET', path: '/ping-' + i })
+  }
+  const { statusCode, headers, body } = await lastReq
+  console.log('last ping statusCode:', statusCode)
+  console.log('last ping headers:', headers)
+  for await (const data of body) {
+    console.log('last ping data:', data.toString())
+  }
+
+  trans.end()
+  client.close()
+  server.close()
+})

lib/instrumentation/index.js

@@ -21,11 +21,13 @@ const {
   AsyncHooksRunContextManager,
   AsyncLocalStorageRunContextManager
 } = require('./run-context')
-const {
-  getLambdaHandlerInfo
-} = require('../lambda')
+const { getLambdaHandlerInfo } = require('../lambda')
+const undiciInstr = require('./modules/undici')
 
 const nodeSupportsAsyncLocalStorage = semver.satisfies(process.versions.node, '>=14.5 || ^12.19.0')
+// Node v16.5.0 added fetch support (behind `--experimental-fetch` until
+// v18.0.0) based on [email protected]. We can instrument undici >=v4.7.1.
+const nodeHasInstrumentableFetch = typeof (global.fetch) === 'function'
 
 var MODULES = [
   ['@elastic/elasticsearch', '@elastic/elasticsearch-canary'],
@@ -62,13 +64,15 @@ var MODULES = [
   'redis',
   'restify',
   'tedious',
+  'undici',
   'ws'
 ]
 
 module.exports = Instrumentation
 
 function Instrumentation (agent) {
   this._agent = agent
+  this._disableInstrumentationsSet = null
   this._hook = null // this._hook is only exposed for testing purposes
   this._started = false
   this._runCtxMgr = null
@@ -209,6 +213,11 @@ Instrumentation.prototype.start = function (runContextClass) {
 
   this._runCtxMgr.enable()
   this._startHook()
+
+  if (nodeHasInstrumentableFetch && this._isModuleEnabled('undici')) {
+    this._log.debug('instrumenting fetch')
+    undiciInstr.instrumentUndici(this._agent)
+  }
 }
 
 // Stop active instrumentation and reset global state *as much as possible*.
@@ -230,6 +239,10 @@ Instrumentation.prototype.stop = function () {
     this._hook.unhook()
     this._hook = null
   }
+
+  if (nodeHasInstrumentableFetch) {
+    undiciInstr.uninstrumentUndici()
+  }
 }
 
 // Reset internal state for (relatively) clean re-use of this Instrumentation.
@@ -243,6 +256,13 @@ Instrumentation.prototype.testReset = function () {
   }
 }
 
+Instrumentation.prototype._isModuleEnabled = function (modName) {
+  if (!this._disableInstrumentationsSet) {
+    this._disableInstrumentationsSet = new Set(this._agent._conf.disableInstrumentations)
+  }
+  return this._agent._conf.instrument && !this._disableInstrumentationsSet.has(modName)
+}
+
 Instrumentation.prototype._startHook = function () {
   if (!this._started) return
   if (this._hook) {
@@ -251,12 +271,11 @@ Instrumentation.prototype._startHook = function () {
   }
 
   var self = this
-  var disabled = new Set(this._agent._conf.disableInstrumentations)
 
   this._agent.logger.debug('adding hook to Node.js module loader')
 
   this._hook = hook(this._patches.keys, function (exports, name, basedir) {
-    var enabled = self._agent._conf.instrument && !disabled.has(name)
+    const enabled = self._isModuleEnabled(name)
     var pkg, version
 
     const isHandlingLambda = self._lambdaHandlerInfo && self._lambdaHandlerInfo.module === name