From ed10a405f6571f38079f7ab615012eb44bfee156 Mon Sep 17 00:00:00 2001
From: Trent Mick <trent.mick@elastic.co>
Date: Mon, 3 Feb 2025 20:21:13 -0800
Subject: [PATCH 1/6] feat!: better ESM instrumentation; bump min-supported
 node to ^18.19.0 || >=20.6.0

This uses the IITM feature to only hook ES modules that will be patched by
instrumentations. This means instr-openai can possibly work with ESM usage of
openai -- before this it would crash from IITM hook changes.

This drops Node.js 14 and 16 support, in favour of the new base versions
that support module.register(). This is the same base version for coming
upstream OTel JS SDK 2.0. This allows us to simplify the ESM story: both
for docs and implementation.

Using --experimental-loader to somewhat support ESM for older node.js
versions is no longer supported. The main recommendation is to use
    node --import @elastic/opentelemetry-node ...
I.e. to use --import rather than --require. Only with --import will
EDOT Node.js register the loader hook for ESM instrumentation.
Using --require is still fine for CommonJS-only instr.
---
 .../hook.mjs => examples/openai/chat.mjs      |  21 +++-
 examples/openai/package.json                  |   3 +-
 packages/opentelemetry-node/CHANGELOG.md      |  27 +++++
 packages/opentelemetry-node/README.md         |   2 +-
 .../opentelemetry-node/docs/get-started.md    |   6 +-
 packages/opentelemetry-node/docs/metrics.md   |   4 +-
 .../docs/supported-technologies.md            |   4 +-
 packages/opentelemetry-node/import.mjs        |  58 +++------
 packages/opentelemetry-node/package-lock.json |  17 +--
 packages/opentelemetry-node/package.json      |   8 +-
 packages/opentelemetry-node/require.js        |  50 ++------
 .../opentelemetry-node/test/esm-usage.test.js | 112 ++----------------
 .../test/fixtures/use-fetch.mjs               |   2 +-
 .../test/fixtures/use-ioredis.mjs             |   2 +-
 .../test/fixtures/use-redis.mjs               |   2 +-
 .../test/instr-ioredis.test.js                |   7 +-
 .../test/instr-redis-4.test.js                |   4 +-
 .../test/instr-undici.test.js                 |   3 +
 18 files changed, 108 insertions(+), 224 deletions(-)
 rename packages/opentelemetry-node/hook.mjs => examples/openai/chat.mjs (68%)

diff --git a/packages/opentelemetry-node/hook.mjs b/examples/openai/chat.mjs
similarity index 68%
rename from packages/opentelemetry-node/hook.mjs
rename to examples/openai/chat.mjs
index d16b2de8..f2bf6ac6 100644
--- a/packages/opentelemetry-node/hook.mjs
+++ b/examples/openai/chat.mjs
@@ -17,9 +17,18 @@
  * under the License.
  */
 
-export {
-    load,
-    resolve,
-    getFormat,
-    getSource,
-} from '@opentelemetry/instrumentation/hook.mjs';
+import {OpenAI} from 'openai';
+
+let chatModel = process.env.CHAT_MODEL ?? 'gpt-4o-mini';
+
+const client = new OpenAI();
+const completion = await client.chat.completions.create({
+  model: chatModel,
+  messages: [
+    {
+      role: 'user',
+      content: 'Answer in up to 3 words: Which ocean contains Bouvet Island?',
+    },
+  ],
+});
+console.log(completion.choices[0].message.content);
diff --git a/examples/openai/package.json b/examples/openai/package.json
index 6b438820..cfdc09d0 100644
--- a/examples/openai/package.json
+++ b/examples/openai/package.json
@@ -8,7 +8,8 @@
   },
   "scripts": {
     "chat": "node --env-file .env --require @elastic/opentelemetry-node chat.js",
-    "embeddings": "node --env-file .env --require @elastic/opentelemetry-node embeddings.js"
+    "embeddings": "node --env-file .env --require @elastic/opentelemetry-node embeddings.js",
+    "chat:esm": "node --env-file .env --import @elastic/opentelemetry-node chat.mjs"
   },
   "dependencies": {
     "@elastic/opentelemetry-node": "*",
diff --git a/packages/opentelemetry-node/CHANGELOG.md b/packages/opentelemetry-node/CHANGELOG.md
index 6f704595..4a07ba47 100644
--- a/packages/opentelemetry-node/CHANGELOG.md
+++ b/packages/opentelemetry-node/CHANGELOG.md
@@ -2,12 +2,39 @@
 
 ## Unreleased
 
+- BREAKING CHANGE: Bump min-supported node to `^18.19.0 || >=20.6.0`.
+  This raises the minimum-supported Node.js to the same as coming releases of OpenTelemetry JS.
+  This base version range ensures that `module.register()` is available for improved ES module
+  (ESM) auto-instrumentation.
+  This drops support for Node.js 14 and 16.
+
+- feat: Improve ES module (ESM) instrumentation.
+
+  As part of this change, using `--require @elastic/opentelemetry-node` will
+  *no longer* setup a module hook for instrumenting ES modules; only using
+  `--import @elastic/opentelemetry-node` will do so. **The recommendation now
+  is to use `--import @elastic/opentelemetry-node` to start EDOT Node.js.**
+  Using `--require ...` is still fine when you know your application is only
+  using CommonJS modules.
+
+  Implementation details: The underlying module hook mechanism for ESM has been
+  changed to only hook modules that will potentially be patched by configured
+  instrumentations.  This allows some instrumentations to work that could not
+  before due to some ESM files not being hookable (at least via the imperfect
+  mechanism for hooking ES modules). One such example is
+  `@elastic/instrumentation-openai`.  See
+  <https://github.com/nodejs/import-in-the-middle/pull/146> for internal
+  details.
+
 - feat: Add `@opentelemetry/instrumentation-mysql` to the default set
   of instrumentations. See <https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/plugins/node/opentelemetry-instrumentation-mysql#readme>
+
 - feat: Add `@opentelemetry/instrumentation-mysql2` to the default set
   of instrumentations. See <https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/plugins/node/opentelemetry-instrumentation-mysql2#readme>
+
 - feat: Add `@opentelemetry/instrumentation-cassandra-driver` to the default set
   of instrumentations. See <https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/plugins/node/opentelemetry-instrumentation-cassandra#readme>
+
 - test: Test that the native instrumentation in `@elastic/elasticsearch@8.15.0` and later works.
 
 
diff --git a/packages/opentelemetry-node/README.md b/packages/opentelemetry-node/README.md
index fb49e710..8120a85c 100644
--- a/packages/opentelemetry-node/README.md
+++ b/packages/opentelemetry-node/README.md
@@ -31,7 +31,7 @@ npm install --save @elastic/opentelemetry-node
 ## Run
 
 ```sh
-node -r @elastic/opentelemetry-node my-service.js
+node --import @elastic/opentelemetry-node my-service.js
 ```
 
 ## Read the docs
diff --git a/packages/opentelemetry-node/docs/get-started.md b/packages/opentelemetry-node/docs/get-started.md
index 99450dc3..9deba7f0 100644
--- a/packages/opentelemetry-node/docs/get-started.md
+++ b/packages/opentelemetry-node/docs/get-started.md
@@ -92,11 +92,11 @@ for example, before `express` or `http` are loaded.
 
 <!-- ✅ Step-by-step instructions -->
 The recommended way to get the
-distro started is by using the `-r, --require` Node.js
-[CLI option](https://nodejs.org/api/cli.html#-r---require-module):
+distro started is by using the `--import` Node.js
+[CLI option](https://nodejs.org/api/cli.html#--importmodule):
 
 ```sh
-node --require @elastic/opentelemetry-node my-service.js
+node --import @elastic/opentelemetry-node my-service.js
 ```
 
 EDOT Node.js will automatically instrument popular modules (listed in [Supported technologies](./supported-technologies.md))
diff --git a/packages/opentelemetry-node/docs/metrics.md b/packages/opentelemetry-node/docs/metrics.md
index 245f71a7..09cc8bfa 100644
--- a/packages/opentelemetry-node/docs/metrics.md
+++ b/packages/opentelemetry-node/docs/metrics.md
@@ -21,7 +21,7 @@ variable `ELASTIC_OTEL_METRICS_DISABLED` to the string `true`.
 export OTEL_EXPORTER_OTLP_ENDPOINT="${ELASTIC_APM_SERVER_URL}"
 export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${ELASTIC_APM_SECRET_TOKEN}"
 export ELASTIC_OTEL_METRICS_DISABLED=true
-node -r @elastic/opentelemetry-node/start.js my-app.js
+node --import @elastic/opentelemetry-node/start.js my-app.js
 ```
 
 ## Advanced configuration
@@ -57,4 +57,4 @@ issues when doing an overview of the instrumented service. These are:
 
 
 If your service is instrumented by EDOT Node.js, or by custom instrumentation that includes the packages mentioned above, Kibana will
-display them as part of the [service metrics](https://www.elastic.co/guide/en/observability/current/apm-metrics.html) in its UI.
\ No newline at end of file
+display them as part of the [service metrics](https://www.elastic.co/guide/en/observability/current/apm-metrics.html) in its UI.
diff --git a/packages/opentelemetry-node/docs/supported-technologies.md b/packages/opentelemetry-node/docs/supported-technologies.md
index 129b6403..a894af69 100644
--- a/packages/opentelemetry-node/docs/supported-technologies.md
+++ b/packages/opentelemetry-node/docs/supported-technologies.md
@@ -83,7 +83,7 @@ node --import @elastic/opentelemetry-node my-app.js
 
 ## ECMAScript Modules (ESM)
 
-This Distro includes **limited and experimental** support for instrumenting [ECMAScript module imports](https://nodejs.org/api/esm.html#modules-ecmascript-modules), i.e. modules that are loaded via `import ...` statements and `import('...')` (dynamic import).
+This Distro includes **limited and experimental** support for instrumenting [ECMAScript module (ESM) imports](https://nodejs.org/api/esm.html#modules-ecmascript-modules), i.e. modules that are loaded via `import ...` statements and `import('...')` (dynamic import). To enable ESM instrumentation, use `node --import @elastic/opentelemetry-node ...` to start the SDK. (Using `node --require @elastic/opentelemetry-node ...` will not enable ESM instrumentation. It is intended to signal that only CommonJS module usage should be instrumented.)
 
 <!--
 TODO: add this to the above paragraph once we have an esm.md doc:
@@ -92,5 +92,5 @@ See the [ECMAScript module support](./esm.md) document for details.
 
 Limitations:
 
-* For Node.js `>=20.6.0 || >=18.19.0`, support for hooking `import`s is automatically enabled. For earlier versions of Node.js, you must manually enable the `import`-hook via the `--experimental-loader=@elastic/opentelemetry-node/hook.mjs` option, e.g.: `node --experimental-loader=@elastic/opentelemetry-node/hook.mjs --require=@elastic/opentelemetry-node app.js`.
+* ESM instrumentation is only support for Node.js versions `>=20.6.0 || >=18.19.0`. These are the versions that include `module.register()` support. Using the older `node --experimental-loader=...` option is not supported.
 * Currently only a subset of instrumentations support ESM: `express`, `ioredis`, `koa`, `pg`, `pino`. See [this OpenTelemetry JS tracking issue](https://github.com/open-telemetry/opentelemetry-js-contrib/issues/1942) for progress.
diff --git a/packages/opentelemetry-node/import.mjs b/packages/opentelemetry-node/import.mjs
index f3d014b2..5502bc16 100644
--- a/packages/opentelemetry-node/import.mjs
+++ b/packages/opentelemetry-node/import.mjs
@@ -20,52 +20,28 @@
 // Register ESM hook and start the SDK.
 // This is called for `--import @elastic/opentelemetry-node`.
 
-import * as module from 'node:module';
+import {register} from 'node:module';
 import {isMainThread} from 'node:worker_threads';
 
-import {log} from './lib/logging.js';
+// TODO: Update @opentelemetry/instrumentation exports to use it rather than IITM directly, if can.
+import {createAddHookMessageChannel} from 'import-in-the-middle';
 
-/**
- * Return true iff it looks like the `@elastic/opentelemetry-node/hook.mjs`
- * was loaded via node's `--experimental-loader` option.
- *
- * Dev Note: keep this in sync with "require.js".
- */
-function haveHookFromExperimentalLoader() {
-    const USED_LOADER_OPT =
-        /--(experimental-)?loader(\s+|=)@elastic\/opentelemetry-node\/hook.mjs/;
-    for (let i = 0; i < process.execArgv.length; i++) {
-        const arg = process.execArgv[i];
-        const nextArg = process.execArgv[i + 1];
-        if (
-            (arg === '--loader' || arg === '--experimental-loader') &&
-            nextArg === '@elastic/opentelemetry-node/hook.mjs'
-        ) {
-            log.trace('bootstrap-import: --loader hook args used');
-            return true;
-        } else if (USED_LOADER_OPT.test(arg)) {
-            log.trace('bootstrap-import: --loader hook arg used');
-            return true;
-        }
-    }
-    if (
-        process.env.NODE_OPTIONS &&
-        USED_LOADER_OPT.test(process.env.NODE_OPTIONS)
-    ) {
-        log.trace('bootstrap-import: --loader arg used in NODE_OPTIONS');
-        return true;
-    }
-    return false;
-}
+import {log} from './lib/logging.js';
 
 if (isMainThread) {
-    if (
-        typeof module.register === 'function' &&
-        !haveHookFromExperimentalLoader()
-    ) {
-        log.trace('bootstrap-import: registering module hook');
-        module.register('./hook.mjs', import.meta.url);
-    }
+    // Note: If there are *multiple* installations of import-in-the-middle, then
+    // only those instrumentations using this same one will be hooked.
+    const {registerOptions, waitForAllMessagesAcknowledged} =
+        createAddHookMessageChannel();
+
+    log.trace('import.mjs: registering module hook');
+    register('import-in-the-middle/hook.mjs', import.meta.url, registerOptions);
 
     await import('./lib/start.js');
+
+    // Ensure that the loader has acknowledged all the modules before we allow
+    // execution to continue.
+    await waitForAllMessagesAcknowledged();
+} else {
+    log.trace('import.mjs: skipping EDOT Node.js bootstrap on non-main thread');
 }
diff --git a/packages/opentelemetry-node/package-lock.json b/packages/opentelemetry-node/package-lock.json
index 645a1cd8..3e510eb7 100644
--- a/packages/opentelemetry-node/package-lock.json
+++ b/packages/opentelemetry-node/package-lock.json
@@ -19,7 +19,6 @@
         "@opentelemetry/exporter-metrics-otlp-http": "^0.57.1",
         "@opentelemetry/exporter-metrics-otlp-proto": "^0.57.1",
         "@opentelemetry/host-metrics": "^0.35.0",
-        "@opentelemetry/instrumentation": "^0.57.1",
         "@opentelemetry/instrumentation-aws-sdk": "^0.49.0",
         "@opentelemetry/instrumentation-bunyan": "^0.45.0",
         "@opentelemetry/instrumentation-cassandra-driver": "^0.45.0",
@@ -66,6 +65,7 @@
         "@opentelemetry/sdk-logs": "^0.57.1",
         "@opentelemetry/sdk-node": "^0.57.1",
         "@opentelemetry/winston-transport": "^0.10.0",
+        "import-in-the-middle": "^1.12.0",
         "safe-stable-stringify": "^2.4.3"
       },
       "devDependencies": {
@@ -103,7 +103,7 @@
         "winston": "^3.13.1"
       },
       "engines": {
-        "node": ">=14.18.0"
+        "node": "^18.19.0 || >=20.6.0"
       }
     },
     "../mockotlpserver": {
@@ -6570,9 +6570,10 @@
       ]
     },
     "node_modules/import-in-the-middle": {
-      "version": "1.9.0",
-      "resolved": "https://registry.npmjs.org/import-in-the-middle/-/import-in-the-middle-1.9.0.tgz",
-      "integrity": "sha512-Ng1SJINJDBzyUEkx9Mj32XD8G0TQCUb5TMoL9V91CTn6F3wYZLygLuhNFrv0cNMBZaeptnL1zecV6XrIdHJ+xQ==",
+      "version": "1.12.0",
+      "resolved": "https://registry.npmjs.org/import-in-the-middle/-/import-in-the-middle-1.12.0.tgz",
+      "integrity": "sha512-yAgSE7GmtRcu4ZUSFX/4v69UGXwugFFSdIQJ14LHPOPPQrWv8Y7O9PHsw8Ovk7bKCLe4sjXMbZFqGFcLHpZ89w==",
+      "license": "Apache-2.0",
       "dependencies": {
         "acorn": "^8.8.2",
         "acorn-import-attributes": "^1.9.5",
@@ -14492,9 +14493,9 @@
       "dev": true
     },
     "import-in-the-middle": {
-      "version": "1.9.0",
-      "resolved": "https://registry.npmjs.org/import-in-the-middle/-/import-in-the-middle-1.9.0.tgz",
-      "integrity": "sha512-Ng1SJINJDBzyUEkx9Mj32XD8G0TQCUb5TMoL9V91CTn6F3wYZLygLuhNFrv0cNMBZaeptnL1zecV6XrIdHJ+xQ==",
+      "version": "1.12.0",
+      "resolved": "https://registry.npmjs.org/import-in-the-middle/-/import-in-the-middle-1.12.0.tgz",
+      "integrity": "sha512-yAgSE7GmtRcu4ZUSFX/4v69UGXwugFFSdIQJ14LHPOPPQrWv8Y7O9PHsw8Ovk7bKCLe4sjXMbZFqGFcLHpZ89w==",
       "requires": {
         "acorn": "^8.8.2",
         "acorn-import-attributes": "^1.9.5",
diff --git a/packages/opentelemetry-node/package.json b/packages/opentelemetry-node/package.json
index 19a09b93..f80b2bd5 100644
--- a/packages/opentelemetry-node/package.json
+++ b/packages/opentelemetry-node/package.json
@@ -24,7 +24,7 @@
   ],
   "author": "Elastic Observability <https://www.elastic.co/observability>",
   "engines": {
-    "node": ">=14.18.0"
+    "node": "^18.19.0 || >=20.6.0"
   },
   "files": [
     "lib",
@@ -33,7 +33,6 @@
     "LICENSE",
     "NOTICE.md",
     "README.md",
-    "hook.mjs",
     "import.mjs",
     "package.json",
     "require.js"
@@ -45,7 +44,7 @@
     "lint:eslint": "eslint --ext=js,mjs,cjs . # requires node >=16.0.0",
     "lint:types": "rm -rf build/lint-types && tsc --outDir build/lint-types && diff -ur types build/lint-types",
     "lint:fix": "eslint --ext=js,mjs,cjs --fix . # requires node >=16.0.0",
-    "lint:deps": "dependency-check require.js import.mjs hook.mjs 'lib/**/*.js' 'test/**/*.js' '!test/fixtures/a-ts-proj' -e mjs:../../scripts/parse-mjs-source -i @types/tape -i dotenv -i @opentelemetry/winston-transport -i @opentelemetry/exporter-logs-* -i @opentelemetry/exporter-metrics-*",
+    "lint:deps": "dependency-check require.js import.mjs 'lib/**/*.js' 'test/**/*.js' '!test/fixtures/a-ts-proj' -e mjs:../../scripts/parse-mjs-source -i @types/tape -i dotenv -i @opentelemetry/winston-transport -i @opentelemetry/exporter-logs-* -i @opentelemetry/exporter-metrics-*",
     "lint:license-files": "../../scripts/gen-notice.sh --lint .  # requires node >=16",
     "lint:changelog": "../../scripts/extract-release-notes.sh .",
     "test": "NODE_OPTIONS='-r dotenv/config' DOTENV_CONFIG_PATH=./test/test-services.env tape test/**/*.test.js",
@@ -63,7 +62,6 @@
       "types": "./types/sdk.d.ts",
       "default": "./lib/sdk.js"
     },
-    "./hook.mjs": "./hook.mjs",
     "./package.json": "./package.json"
   },
   "dependencies": {
@@ -77,7 +75,6 @@
     "@opentelemetry/exporter-metrics-otlp-http": "^0.57.1",
     "@opentelemetry/exporter-metrics-otlp-proto": "^0.57.1",
     "@opentelemetry/host-metrics": "^0.35.0",
-    "@opentelemetry/instrumentation": "^0.57.1",
     "@opentelemetry/instrumentation-aws-sdk": "^0.49.0",
     "@opentelemetry/instrumentation-bunyan": "^0.45.0",
     "@opentelemetry/instrumentation-cassandra-driver": "^0.45.0",
@@ -124,6 +121,7 @@
     "@opentelemetry/sdk-logs": "^0.57.1",
     "@opentelemetry/sdk-node": "^0.57.1",
     "@opentelemetry/winston-transport": "^0.10.0",
+    "import-in-the-middle": "^1.12.0",
     "safe-stable-stringify": "^2.4.3"
   },
   "devDependencies": {
diff --git a/packages/opentelemetry-node/require.js b/packages/opentelemetry-node/require.js
index 1831fbc6..5e806d69 100644
--- a/packages/opentelemetry-node/require.js
+++ b/packages/opentelemetry-node/require.js
@@ -17,53 +17,17 @@
  * under the License.
  */
 
-// Register ESM hook and start the SDK.
+// Start the SDK for CommonJS usage.
 // This is called for `--require @elastic/opentelemetry-node`.
+//
+// Note: This does *not* register an import hook for ESM instrumentation. Use
+// `--import @elastic/opentelemetry-node` for that.
 
-const register = require('module').register;
-const {pathToFileURL} = require('url');
 const {isMainThread} = require('worker_threads');
 
-const {log} = require('./lib/logging');
-
-/**
- * Return true iff it looks like the `@elastic/opentelemetry-node/hook.mjs`
- * was loaded via node's `--experimental-loader` option.
- *
- * Dev Note: keep this in sync with "import.mjs".
- */
-function haveHookFromExperimentalLoader() {
-    const USED_LOADER_OPT =
-        /--(experimental-)?loader(\s+|=)@elastic\/opentelemetry-node\/hook.mjs/;
-    for (let i = 0; i < process.execArgv.length; i++) {
-        const arg = process.execArgv[i];
-        const nextArg = process.execArgv[i + 1];
-        if (
-            (arg === '--loader' || arg === '--experimental-loader') &&
-            nextArg === '@elastic/opentelemetry-node/hook.mjs'
-        ) {
-            log.trace('bootstrap-require: --loader hook args used');
-            return true;
-        } else if (USED_LOADER_OPT.test(arg)) {
-            log.trace('bootstrap-require: --loader hook arg used');
-            return true;
-        }
-    }
-    if (
-        process.env.NODE_OPTIONS &&
-        USED_LOADER_OPT.test(process.env.NODE_OPTIONS)
-    ) {
-        log.trace('bootstrap-require: --loader arg used in NODE_OPTIONS');
-        return true;
-    }
-    return false;
-}
-
 if (isMainThread) {
-    if (typeof register === 'function' && !haveHookFromExperimentalLoader()) {
-        log.trace('bootstrap-require: registering module hook');
-        register('./hook.mjs', pathToFileURL(__filename).toString());
-    }
-
     require('./lib/start.js');
+} else {
+    const {log} = require('./lib/logging');
+    log.trace('require.mjs: skipping EDOT Node.js bootstrap on non-main thread');
 }
diff --git a/packages/opentelemetry-node/test/esm-usage.test.js b/packages/opentelemetry-node/test/esm-usage.test.js
index 6082693a..3dc2003b 100644
--- a/packages/opentelemetry-node/test/esm-usage.test.js
+++ b/packages/opentelemetry-node/test/esm-usage.test.js
@@ -17,9 +17,7 @@
  * under the License.
  */
 
-// Sanity test the various ways that ESM support can be enabled via --require,
-// --import, and --experimental-loader (also --loader) in the various versions
-// of Node.js
+// Sanity test the various ways that ESM support can be enabled.
 
 const test = require('tape');
 const {filterOutDnsNetSpans, runTestFixtures} = require('./testutils');
@@ -35,23 +33,10 @@ if (skip) {
 
 /** @type {import('./testutils').TestFixture[]} */
 const testFixtures = [
-    {
-        name: 'ESM via --require',
-        versionRanges: {
-            // TODO: issue on node docs that https://nodejs.org/api/all.html#all_module_moduleregisterspecifier-parenturl-options history doesn't show backport to v18.19.0
-            node: '^18.19.0 || >=20.6.0', // when `module.register()` was added
-        },
-        args: ['./fixtures/use-ioredis.mjs'],
-        cwd: __dirname,
-        env: {
-            NODE_OPTIONS: '--require=@elastic/opentelemetry-node',
-        },
-        verbose: true,
-        checkTelemetry: assertUseIoredisMjsSpans,
-    },
     {
         name: 'ESM via --import',
         versionRanges: {
+            // TODO: issue on node docs that https://nodejs.org/api/all.html#all_module_moduleregisterspecifier-parenturl-options history doesn't show backport to v18.19.0
             node: '^18.19.0 || >=20.6.0', // when `module.register()` was added
         },
         args: ['./fixtures/use-ioredis.mjs'],
@@ -61,95 +46,16 @@ const testFixtures = [
             NODE_NO_WARNINGS: '1',
         },
         verbose: true,
-        checkTelemetry: assertUseIoredisMjsSpans,
-    },
-
-    // Test the cases where the Node.js version means `--experimental-loader`
-    // is needed to register the `import`-hook.
-    {
-        name: 'ESM via --require & --experimental-loader for older Node.js',
-        versionRanges: {
-            node: [
-                // The minimum versions where `--experimental-loader` works at all.
-                '^12.20.0 || ^14.13.1 || ^16.0.0 || ^18.1.0 || >=20.2.0',
-                // The Node.js versions before `module.register()` existed.
-                '<18.19.0 || >=20.0.0 <20.6.0',
-            ],
-        },
-        args: ['./fixtures/use-ioredis.mjs'],
-        cwd: __dirname,
-        env: {
-            NODE_OPTIONS:
-                '--require=@elastic/opentelemetry-node --experimental-loader=@elastic/opentelemetry-node/hook.mjs',
-            NODE_NO_WARNINGS: '1',
-        },
-        verbose: true,
-        checkTelemetry: assertUseIoredisMjsSpans,
-    },
-    {
-        name: 'ESM via --import & --experimental-loader for older Node.js',
-        versionRanges: {
-            node: [
-                // The minimum versions where `--experimental-loader` works at all.
-                '^12.20.0 || ^14.13.1 || ^16.0.0 || ^18.1.0 || >=20.2.0',
-                // The Node.js versions before `module.register()` existed,
-                // plus --import was added in v18.18.0.
-                '>=18.18.0 <18.19.0 || >=20.0.0 <20.6.0',
-            ],
-        },
-        args: ['./fixtures/use-ioredis.mjs'],
-        cwd: __dirname,
-        env: {
-            NODE_OPTIONS:
-                '--import=@elastic/opentelemetry-node --experimental-loader=@elastic/opentelemetry-node/hook.mjs',
-            NODE_NO_WARNINGS: '1',
-        },
-        verbose: true,
-        checkTelemetry: assertUseIoredisMjsSpans,
-    },
-
-    // Test a couple cases where, with newer Node.js versions that support
-    // `module.register()`, we could possibly *double-register* the hook if
-    // the user also registered the hook via `--experimental-loader=...`.
-    {
-        name: 'ESM via --import with possible double-hooking',
-        versionRanges: {
-            node: '^18.19.0 || >=20.6.0', // when `module.register()` was added
-        },
-        args: ['./fixtures/use-ioredis.mjs'],
-        cwd: __dirname,
-        env: {
-            NODE_OPTIONS:
-                '--import=@elastic/opentelemetry-node --experimental-loader=@elastic/opentelemetry-node/hook.mjs',
-            NODE_NO_WARNINGS: '1',
-        },
-        verbose: true,
-        checkTelemetry: assertUseIoredisMjsSpans,
-    },
-    {
-        name: 'ESM via --require with possible double-hooking',
-        versionRanges: {
-            node: '^18.19.0 || >=20.6.0', // when `module.register()` was added
-        },
-        args: ['./fixtures/use-ioredis.mjs'],
-        cwd: __dirname,
-        env: {
-            NODE_OPTIONS:
-                '--require=@elastic/opentelemetry-node --experimental-loader=@elastic/opentelemetry-node/hook.mjs',
-            NODE_NO_WARNINGS: '1',
-        },
-        verbose: true,
-        checkTelemetry: assertUseIoredisMjsSpans,
+        checkTelemetry: function assertUseIoredisMjsSpans(t, col) {
+            // Assert that we got the two redis spans expected from 'use-ioredis.mjs'.
+            const spans = filterOutDnsNetSpans(col.sortedSpans);
+            t.equal(spans[1].name, 'set');
+            t.equal(spans[1].attributes['db.system'], 'redis');
+            t.equal(spans[2].name, 'get');
+        }
     },
 ];
 
-function assertUseIoredisMjsSpans(t, col) {
-    // Assert that we got the two redis spans expected from 'use-ioredis.mjs'.
-    const spans = filterOutDnsNetSpans(col.sortedSpans);
-    t.equal(spans[1].name, 'set');
-    t.equal(spans[1].attributes['db.system'], 'redis');
-    t.equal(spans[2].name, 'get');
-}
 
 test('ESM usage', {skip}, (suite) => {
     runTestFixtures(suite, testFixtures);
diff --git a/packages/opentelemetry-node/test/fixtures/use-fetch.mjs b/packages/opentelemetry-node/test/fixtures/use-fetch.mjs
index 6621b00c..30d74729 100644
--- a/packages/opentelemetry-node/test/fixtures/use-fetch.mjs
+++ b/packages/opentelemetry-node/test/fixtures/use-fetch.mjs
@@ -17,7 +17,7 @@
  * under the License.
  */
 
-// Usage: node -r @elastic/opentelemetry-node use-fetch.mjs
+// Usage: node --import @elastic/opentelemetry-node use-fetch.mjs
 
 const res = await fetch('http://www.google.com/');
 console.log(
diff --git a/packages/opentelemetry-node/test/fixtures/use-ioredis.mjs b/packages/opentelemetry-node/test/fixtures/use-ioredis.mjs
index f81106af..9dce1e9b 100644
--- a/packages/opentelemetry-node/test/fixtures/use-ioredis.mjs
+++ b/packages/opentelemetry-node/test/fixtures/use-ioredis.mjs
@@ -17,7 +17,7 @@
  * under the License.
  */
 
-// Usage: node -r @elastic/opentelemetry-node use-ioredis.mjs
+// Usage: node --import @elastic/opentelemetry-node use-ioredis.mjs
 
 import {trace} from '@opentelemetry/api';
 
diff --git a/packages/opentelemetry-node/test/fixtures/use-redis.mjs b/packages/opentelemetry-node/test/fixtures/use-redis.mjs
index 4cd6e2ab..e19ee052 100644
--- a/packages/opentelemetry-node/test/fixtures/use-redis.mjs
+++ b/packages/opentelemetry-node/test/fixtures/use-redis.mjs
@@ -17,7 +17,7 @@
  * under the License.
  */
 
-// Usage: node -r @elastic/opentelemetry-node use-redis.mjs
+// Usage: node --import @elastic/opentelemetry-node use-redis.mjs
 
 import {trace} from '@opentelemetry/api';
 
diff --git a/packages/opentelemetry-node/test/instr-ioredis.test.js b/packages/opentelemetry-node/test/instr-ioredis.test.js
index 01fc8f4b..10195ab0 100644
--- a/packages/opentelemetry-node/test/instr-ioredis.test.js
+++ b/packages/opentelemetry-node/test/instr-ioredis.test.js
@@ -64,19 +64,18 @@ const testFixtures = [
         },
     },
 
-    // This duplicates the "ESM via --require" test case in esm-usage.test.js,
+    // This duplicates the test case in esm-usage.test.js,
     // but it is useful to have the ESM ioredis sanity test here as well when
     // working on instr-ioredis.
     {
-        name: 'use-ioredis.mjs (ESM via --require)',
+        name: 'use-ioredis.mjs (ESM)',
         versionRanges: {
-            // TODO: issue on node docs that https://nodejs.org/api/all.html#all_module_moduleregisterspecifier-parenturl-options history doesn't show backport to v18.19.0
             node: '^18.19.0 || >=20.6.0', // when `module.register()` was added
         },
         args: ['./fixtures/use-ioredis.mjs'],
         cwd: __dirname,
         env: {
-            NODE_OPTIONS: '--require=@elastic/opentelemetry-node',
+            NODE_OPTIONS: '--import=@elastic/opentelemetry-node',
         },
         verbose: true,
         checkTelemetry: assertUseIoredisMjsSpans,
diff --git a/packages/opentelemetry-node/test/instr-redis-4.test.js b/packages/opentelemetry-node/test/instr-redis-4.test.js
index 0271cd04..5848c01e 100644
--- a/packages/opentelemetry-node/test/instr-redis-4.test.js
+++ b/packages/opentelemetry-node/test/instr-redis-4.test.js
@@ -65,14 +65,14 @@ const testFixtures = [
     },
     // ESM redis sanity test
     {
-        name: 'use-redis.mjs (ESM via --require)',
+        name: 'use-redis.mjs (ESM)',
         versionRanges: {
             node: '^18.19.0 || >=20.6.0', // when `module.register()` was added
         },
         args: ['./fixtures/use-redis.mjs'],
         cwd: __dirname,
         env: {
-            NODE_OPTIONS: '--require=@elastic/opentelemetry-node',
+            NODE_OPTIONS: '--import=@elastic/opentelemetry-node',
         },
         verbose: true,
         checkTelemetry: (t, col) => {
diff --git a/packages/opentelemetry-node/test/instr-undici.test.js b/packages/opentelemetry-node/test/instr-undici.test.js
index d4ce97d3..584f9e7e 100644
--- a/packages/opentelemetry-node/test/instr-undici.test.js
+++ b/packages/opentelemetry-node/test/instr-undici.test.js
@@ -91,6 +91,9 @@ const testFixtures = [
         args: ['./fixtures/use-fetch.mjs'],
         cwd: __dirname,
         env: {
+            // Typically '--import' usage is required for ESM instrumention.
+            // However undici instrumentation uses diagnostics_channel, so it
+            // an exception.
             NODE_OPTIONS: '--require=@elastic/opentelemetry-node',
         },
         // verbose: true,

From 4cb5ca142b65b5a328abc384f36b0bc0ac9b9c40 Mon Sep 17 00:00:00 2001
From: Trent Mick <trent.mick@elastic.co>
Date: Mon, 3 Feb 2025 20:25:40 -0800
Subject: [PATCH 2/6] lint fix

---
 packages/opentelemetry-node/require.js             | 4 +++-
 packages/opentelemetry-node/test/esm-usage.test.js | 3 +--
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/packages/opentelemetry-node/require.js b/packages/opentelemetry-node/require.js
index 5e806d69..98b7170e 100644
--- a/packages/opentelemetry-node/require.js
+++ b/packages/opentelemetry-node/require.js
@@ -29,5 +29,7 @@ if (isMainThread) {
     require('./lib/start.js');
 } else {
     const {log} = require('./lib/logging');
-    log.trace('require.mjs: skipping EDOT Node.js bootstrap on non-main thread');
+    log.trace(
+        'require.mjs: skipping EDOT Node.js bootstrap on non-main thread'
+    );
 }
diff --git a/packages/opentelemetry-node/test/esm-usage.test.js b/packages/opentelemetry-node/test/esm-usage.test.js
index 3dc2003b..75513fa9 100644
--- a/packages/opentelemetry-node/test/esm-usage.test.js
+++ b/packages/opentelemetry-node/test/esm-usage.test.js
@@ -52,11 +52,10 @@ const testFixtures = [
             t.equal(spans[1].name, 'set');
             t.equal(spans[1].attributes['db.system'], 'redis');
             t.equal(spans[2].name, 'get');
-        }
+        },
     },
 ];
 
-
 test('ESM usage', {skip}, (suite) => {
     runTestFixtures(suite, testFixtures);
     suite.end();

From aed01d6852ec8580159da72af1571b925b0ae4b1 Mon Sep 17 00:00:00 2001
From: Trent Mick <trent.mick@elastic.co>
Date: Mon, 3 Feb 2025 20:28:41 -0800
Subject: [PATCH 3/6] drop testing of node 14 and 16; add testing of min-minors
 of 18 and 20 that are supported

---
 .github/workflows/test-edot.yml                         | 8 ++------
 packages/opentelemetry-node/test/instr-mongoose.test.js | 2 +-
 2 files changed, 3 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/test-edot.yml b/.github/workflows/test-edot.yml
index bf763f10..b17376da 100644
--- a/.github/workflows/test-edot.yml
+++ b/.github/workflows/test-edot.yml
@@ -33,13 +33,9 @@ jobs:
           - '22'
           - '22.0'
           - '20'
-          - '20.0'
+          - '20.6.0'
           - '18'
-          - '18.0'
-          - '16'
-          - '16.0'
-          - '14'
-          - '14.18.0'
+          - '18.19.0'
 
     runs-on: ubuntu-24.04
 
diff --git a/packages/opentelemetry-node/test/instr-mongoose.test.js b/packages/opentelemetry-node/test/instr-mongoose.test.js
index c4ae061f..6c31d997 100644
--- a/packages/opentelemetry-node/test/instr-mongoose.test.js
+++ b/packages/opentelemetry-node/test/instr-mongoose.test.js
@@ -43,7 +43,7 @@ const testFixtures = [
             // Ref: https://github.com/mongodb/node-mongodb-native/blob/a8370367f7470962a834ddf36f9a6c62621d6345/package.json#L118
             node: '>=16.20.1',
         },
-        // verbose: true,
+        verbose: true,
         checkTelemetry: (t, col) => {
             // We expect spans like this
             // ------ trace 5527d1 (13 spans) ------

From b77c16e4935e8c4d205c3c88484c2c8e80941257 Mon Sep 17 00:00:00 2001
From: Trent Mick <trent.mick@elastic.co>
Date: Mon, 3 Feb 2025 20:31:13 -0800
Subject: [PATCH 4/6] typo

---
 packages/opentelemetry-node/test/instr-undici.test.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/opentelemetry-node/test/instr-undici.test.js b/packages/opentelemetry-node/test/instr-undici.test.js
index 584f9e7e..fadf064b 100644
--- a/packages/opentelemetry-node/test/instr-undici.test.js
+++ b/packages/opentelemetry-node/test/instr-undici.test.js
@@ -93,7 +93,7 @@ const testFixtures = [
         env: {
             // Typically '--import' usage is required for ESM instrumention.
             // However undici instrumentation uses diagnostics_channel, so it
-            // an exception.
+            // is an exception.
             NODE_OPTIONS: '--require=@elastic/opentelemetry-node',
         },
         // verbose: true,

From 049103a9109373e1c8f9fbd77237555bbbaeab6d Mon Sep 17 00:00:00 2001
From: Trent Mick <trent.mick@elastic.co>
Date: Mon, 3 Feb 2025 20:33:30 -0800
Subject: [PATCH 5/6] update min-node in supported-tech doc

---
 packages/opentelemetry-node/docs/supported-technologies.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/opentelemetry-node/docs/supported-technologies.md b/packages/opentelemetry-node/docs/supported-technologies.md
index a894af69..2a1d9b4b 100644
--- a/packages/opentelemetry-node/docs/supported-technologies.md
+++ b/packages/opentelemetry-node/docs/supported-technologies.md
@@ -13,13 +13,13 @@ Elastic Stack, so it is strongly recommended to be using a recent 8.x version.
 
 ## Node.js versions
 
-EDOT Node.js supports Node.js v14.18.0 and later.
+EDOT Node.js supports Node.js 18.19.0, 20.6.0, or later.
 This follows from the [OpenTelemetry JS supported runtimes](https://github.com/open-telemetry/opentelemetry-js#supported-runtimes).
 
 <!--
 Dev Notes on supported Node.js versions:
-- v14.18.0 or later is required for `node:`-prefixed core module loading, as
-  used by gaxios@6.7.0, a transitive dep of `@opentelemetry/resource-detector-gcp`.
+- `^18.19.0 || >=20.6.0` is required for `module.register()` support for ESM
+  instrumentation.
 -->
 
 ## TypeScript versions

From f5e8f6cfc4c76ef382570b053df650c433e61343 Mon Sep 17 00:00:00 2001
From: Trent Mick <trent.mick@elastic.co>
Date: Tue, 4 Feb 2025 08:32:37 -0800
Subject: [PATCH 6/6] correct the version range here

---
 packages/opentelemetry-node/docs/supported-technologies.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/opentelemetry-node/docs/supported-technologies.md b/packages/opentelemetry-node/docs/supported-technologies.md
index 2a1d9b4b..d3984f5e 100644
--- a/packages/opentelemetry-node/docs/supported-technologies.md
+++ b/packages/opentelemetry-node/docs/supported-technologies.md
@@ -92,5 +92,5 @@ See the [ECMAScript module support](./esm.md) document for details.
 
 Limitations:
 
-* ESM instrumentation is only support for Node.js versions `>=20.6.0 || >=18.19.0`. These are the versions that include `module.register()` support. Using the older `node --experimental-loader=...` option is not supported.
+* ESM instrumentation is only support for Node.js versions `^18.19.0 || >=20.6.0`. These are the versions that include `module.register()` support. Using the older `node --experimental-loader=...` option is not supported.
 * Currently only a subset of instrumentations support ESM: `express`, `ioredis`, `koa`, `pg`, `pino`. See [this OpenTelemetry JS tracking issue](https://github.com/open-telemetry/opentelemetry-js-contrib/issues/1942) for progress.