support bundling via esbuild (#2763)

Author: tlhunter

LICENSE-3rdparty.csv

@@ -36,6 +36,7 @@ dev,chalk,MIT,Copyright Sindre Sorhus
 dev,checksum,MIT,Copyright Daniel D. Shaw
 dev,cli-table3,MIT,Copyright 2014 James Talmage
 dev,dotenv,BSD-2-Clause,Copyright 2015 Scott Motte
+dev,esbuild,MIT,Copyright (c) 2020 Evan Wallace
 dev,eslint,MIT,Copyright JS Foundation and other contributors https://js.foundation
 dev,eslint-config-standard,MIT,Copyright Feross Aboukhadijeh
 dev,eslint-plugin-import,MIT,Copyright 2015 Ben Mosher

README.md

@@ -188,6 +188,42 @@ That said, even if your application runs on Lambda, any core instrumentation iss
 Regardless of where you open the issue, someone at Datadog will try to help.
 
 
+## Bundling
+
+Generally, `dd-trace` works by intercepting `require()` calls that a Node.js application makes when loading modules. This includes modules that are built-in to Node.js, like the `fs` module for accessing the filesystem, as well as modules installed from the npm registry, like the `pg` database module.
+
+Also generally, bundlers work by crawling all of the `require()` calls that an application makes to files on disk, replacing the `require()` calls with custom code, and then concatenating all of the resulting JavaScript into one "bundled" file. When a built-in module is loaded, like `require('fs')`, that call can then remain the same in the resulting bundle.
+
+Fundamentally APM tools like `dd-trace` stop working at this point. Perhaps they continue to intercept the calls for built-in modules but don't intercept calls to third party libraries. This means that by default when you bundle a `dd-trace` app with a bundler it is likely to capture information about disk access (via `fs`) and outbound HTTP requests (via `http`), but will otherwise omit calls to third party libraries (like extracting incoming request route information for the `express` framework or showing which query is run for the `mysql` database client).
+
+To get around this, one can treat all third party modules, or at least third party modules that the APM needs to instrument, as being "external" to the bundler. With this setting the instrumented modules remain on disk and continue to be loaded via `require()` while the non-instrumented modules are bundled. Sadly this results in a build with many extraneous files and starts to defeat the purpose of bundling. 
+
+For these reasons it's necessary to have custom-built bundler plugins. Such plugins are able to instruct the bundler on how to behave, injecting intermediary code and otherwise intercepting the "translated" `require()` calls. The result is that many more packages are then included in the bundled JavaScript file. Some applications can have 100% of modules bundled, however native modules still need to remain external to the bundle.
+
+### Esbuild Support
+
+This library provides experimental esbuild support in the form of an esbuild plugin, and requires at least Node.js v14.17. To use the plugin, make sure you have `dd-trace@3+` installed, and then require the `dd-trace/esbuild` module when building your bundle.
+
+Here's an example of how one might use `dd-trace` with esbuild:
+
+```javascript
+const ddPlugin = require('dd-trace/esbuild')
+const esbuild = require('esbuild')
+
+esbuild.build({
+  entryPoints: ['app.js'], 
+  bundle: true,
+  outfile: 'out.js',
+  plugins: [ddPlugin],
+  platform: 'node', // allows built-in modules to be required
+  target: ['node16']
+}).catch((err) => {
+  console.error(err)
+  process.exit(1)
+})
+```
+
+
 ## Security Vulnerabilities
 
 If you have found a security issue, please contact the security team directly at [security@datadoghq.com](mailto:security@datadoghq.com).

esbuild.js

@@ -0,0 +1,3 @@
+'use strict'
+
+module.exports = require('./packages/datadog-esbuild/index.js')

integration-tests/esbuild.spec.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+'use strict'
+
+const chproc = require('child_process')
+const path = require('path')
+
+const CWD = process.cwd()
+const TEST_DIR = path.join(__dirname, 'esbuild')
+
+// eslint-disable-next-line no-console
+console.log(`cd ${TEST_DIR}`)
+process.chdir(TEST_DIR)
+
+// eslint-disable-next-line no-console
+console.log('npm run build')
+chproc.execSync('npm run build')
+
+// eslint-disable-next-line no-console
+console.log('npm run built')
+try {
+  chproc.execSync('npm run built', {
+    timeout: 1000 * 30
+  })
+} catch (err) {
+  // eslint-disable-next-line no-console
+  console.error(err)
+  process.exit(1)
+} finally {
+  process.chdir(CWD)
+}

integration-tests/esbuild/.gitignore

@@ -0,0 +1 @@
+out.js

integration-tests/esbuild/basic-test.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+const tracer = require('../../').init() // dd-trace
+
+const assert = require('assert')
+const express = require('express')
+const http = require('http')
+
+const app = express()
+const PORT = 31415
+
+assert.equal(express.static.mime.types.ogg, 'audio/ogg')
+
+const server = app.listen(PORT, () => {
+  setImmediate(() => {
+    http.request(`http://localhost:${PORT}`).end() // query to self
+  })
+})
+
+app.get('/', async (_req, res) => {
+  assert.equal(
+    tracer.scope().active().context()._tags.component,
+    'express',
+    'the sample app bundled by esbuild is not properly instrumented'
+  ) // bad exit
+
+  res.json({ narwhal: 'bacons' })
+
+  setImmediate(() => {
+    server.close() // clean exit
+    setImmediate(() => {
+      process.exit(0)
+    })
+  })
+})

integration-tests/esbuild/build.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+const ddPlugin = require('../../esbuild') // dd-trace/esbuild
+const esbuild = require('esbuild')
+
+esbuild.build({
+  entryPoints: ['basic-test.js'],
+  bundle: true,
+  outfile: 'out.js',
+  plugins: [ddPlugin],
+  platform: 'node',
+  target: ['node16']
+}).catch((err) => {
+  console.error(err) // eslint-disable-line no-console
+  process.exit(1)
+})

integration-tests/esbuild/complex-app.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+require('../../').init() // dd-trace
+const assert = require('assert')
+const express = require('express')
+const redis = require('redis')
+const app = express()
+const PORT = 3000
+const pg = require('pg')
+const pgp = require('pg-promise')() // transient dep of 'pg'
+
+assert.equal(redis.Graph.name, 'Graph')
+assert.equal(pg.types.builtins.BOOL, 16)
+assert.equal(express.static.mime.types.ogg, 'audio/ogg')
+
+const conn = {
+  user: 'postgres',
+  host: 'localhost',
+  database: 'postgres',
+  password: 'hunter2',
+  port: 5433
+}
+
+console.log('pg connect') // eslint-disable-line no-console
+const client = new pg.Client(conn)
+client.connect()
+
+console.log('pg-promise connect') // eslint-disable-line no-console
+const client2 = pgp(conn)
+
+app.get('/', async (_req, res) => {
+  const query = await client.query('SELECT NOW() AS now')
+  const query2 = await client2.query('SELECT NOW() AS now')
+  res.json({
+    connection_pg: query.rows[0].now,
+    connection_pg_promise: query2[0].now
+  })
+})
+
+app.listen(PORT, () => {
+  console.log(`Example app listening on port ${PORT}`) // eslint-disable-line no-console
+})

integration-tests/esbuild/complex-app.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+import 'dd-trace/init.js'
+import assert from 'assert'
+import express from 'express'
+import redis from 'redis'
+const app = express()
+const PORT = 3000
+import pg from 'pg'
+import PGP from 'pg-promise' // transient dep of 'pg'
+const pgp = PGP()
+
+assert.equal(redis.Graph.name, 'Graph')
+assert.equal(pg.types.builtins.BOOL, 16)
+assert.equal(express.static.mime.types.ogg, 'audio/ogg')
+
+const conn = {
+  user: 'postgres',
+  host: 'localhost',
+  database: 'postgres',
+  password: 'hunter2',
+  port: 5433
+}
+
+console.log('pg connect') // eslint-disable-line no-console
+const client = new pg.Client(conn)
+client.connect()
+
+console.log('pg-promise connect') // eslint-disable-line no-console
+const client2 = pgp(conn)
+
+app.get('/', async (_req, res) => {
+  const query = await client.query('SELECT NOW() AS now')
+  const query2 = await client2.query('SELECT NOW() AS now')
+  res.json({
+    connection_pg: query.rows[0].now,
+    connection_pg_promise: query2[0].now
+  })
+})
+
+app.listen(PORT, () => {
+  console.log(`Example app listening on port ${PORT}`) // eslint-disable-line no-console
+})

integration-tests/esbuild/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "esbuild-dd-trace-demo",
+  "private": true,
+  "version": "1.0.0",
+  "description": "basic example app bundling dd-trace via esbuild",
+  "main": "app.js",
+  "scripts": {
+    "build": "DD_TRACE_DEBUG=true node ./build.js",
+    "built": "DD_TRACE_DEBUG=true node ./out.js",
+    "raw": "DD_TRACE_DEBUG=true node ./app.js",
+    "link": "pushd ../.. && yarn link && popd && yarn link dd-trace",
+    "request": "curl http://localhost:3000 | jq"
+  },
+  "keywords": [
+    "esbuild",
+    "apm"
+  ],
+  "author": "Thomas Hunter II <tlhunter@datadog.com>",
+  "license": "ISC",
+  "dependencies": {
+    "esbuild": "0.16.12",
+    "express": "^4.16.2"
+  }
+}

package.json

@@ -104,6 +104,7 @@
     "checksum": "^0.1.1",
     "cli-table3": "^0.5.1",
     "dotenv": "8.2.0",
+    "esbuild": "0.16.12",
     "eslint": "^8.23.0",
     "eslint-config-standard": "^11.0.0-beta.0",
     "eslint-plugin-import": "^2.8.0",

packages/datadog-esbuild/index.js

@@ -0,0 +1,104 @@
+'use strict'
+
+/* eslint-disable no-console */
+
+const NAMESPACE = 'datadog'
+
+const instrumented = Object.keys(require('../datadog-instrumentations/src/helpers/hooks.js'))
+const rawBuiltins = require('module').builtinModules
+
+warnIfUnsupported()
+
+const builtins = new Set()
+
+for (const builtin of rawBuiltins) {
+  builtins.add(builtin)
+  builtins.add(`node:${builtin}`)
+}
+
+const packagesOfInterest = new Set()
+
+const DEBUG = !!process.env.DD_TRACE_DEBUG
+
+// We don't want to handle any built-in packages via DCITM
+// Those packages will still be handled via RITM
+// Attempting to instrument them would fail as they have no package.json file
+for (const pkg of instrumented) {
+  if (builtins.has(pkg)) continue
+  if (pkg.startsWith('node:')) continue
+  packagesOfInterest.add(pkg)
+}
+
+const DC_CHANNEL = 'dd-trace:bundledModuleLoadStart'
+
+module.exports.name = 'datadog-esbuild'
+
+module.exports.setup = function (build) {
+  build.onResolve({ filter: /.*/ }, args => {
+    const packageName = args.path
+
+    if (args.namespace === 'file' && packagesOfInterest.has(packageName)) {
+      // The file namespace is used when requiring files from disk in userland
+      const pathToPackageJson = require.resolve(`${packageName}/package.json`, { paths: [ args.resolveDir ] })
+      const pkg = require(pathToPackageJson)
+
+      if (DEBUG) {
+        console.log(`resolve ${packageName}@${pkg.version}`)
+      }
+
+      // https://esbuild.github.io/plugins/#on-resolve-arguments
+      return {
+        path: packageName,
+        namespace: NAMESPACE,
+        pluginData: {
+          version: pkg.version
+        }
+      }
+    } else if (args.namespace === 'datadog') {
+      // The datadog namespace is used when requiring files that are injected during the onLoad stage
+      // see note in onLoad
+
+      if (builtins.has(packageName)) return
+
+      return {
+        path: require.resolve(packageName, { paths: [ args.resolveDir ] }),
+        namespace: 'file'
+      }
+    }
+  })
+
+  build.onLoad({ filter: /.*/, namespace: NAMESPACE }, args => {
+    if (DEBUG) {
+      console.log(`load ${args.path}@${args.pluginData.version}`)
+    }
+
+    // JSON.stringify adds double quotes. For perf gain could simply add in quotes when we know it's safe.
+    const contents = `
+      const dc = require('diagnostics_channel');
+      const ch = dc.channel(${JSON.stringify(DC_CHANNEL + ':' + args.path)});
+      const mod = require(${JSON.stringify(args.path)});
+      const payload = {
+        module: mod,
+        path: ${JSON.stringify(args.path)},
+        version: ${JSON.stringify(args.pluginData.version)}
+      };
+      ch.publish(payload);
+      module.exports = payload.module;
+    `
+    // https://esbuild.github.io/plugins/#on-load-results
+    return {
+      contents,
+      loader: 'js'
+    }
+  })
+}
+
+function warnIfUnsupported () {
+  const [major, minor] = process.versions.node.split('.').map(Number)
+  if (major < 14 || (major === 14 && minor < 17)) {
+    console.error('WARNING: Esbuild support isn\'t available for older versions of Node.js.')
+    console.error(`Expected: Node.js >= v14.17. Actual: Node.js = ${process.version}.`)
+    console.error('This application may build properly with this version of Node.js, but unless a')
+    console.error('more recent version is used at runtime, third party packages won\'t be instrumented.')
+  }
+}