fix: removed support for experimental loader flag (#2153)

BREAKING CHANGE: 

- Removed support for --experimental-loader
- Removed support for esm-loader.mjs

Migration Recommendations: 

- Replace --experimental-loader with --import
- Use esm-register.mjs instead of esm-loader.mjs

e.g. --import /path/to/instana/node_modules/@instana/collector/esm-register.mjs

Author: aryamohanan

CONTRIBUTING.md

@@ -374,18 +374,11 @@ REGIONS=<region> SKIP_DOCKER_IMAGE=true BUILD_LAYER_WITH=local LAYER_NAME=experi
 
 We have added the ESM support for all Node.js versions, Since version 20.6, [ESM loaders are off-thread](https://github.com/nodejs/node/pull/44710), loaded separately, a shift from previous setups where the Instana collector was loaded within the loader, leading to a disruption in existing implementation. To resolve this, we've replaced the deprecated `--experimental-loader` with `--import`, facilitating the loading of the collector in the main thread. However, note that `--import` is only compatible with Node.js v18.19 and later, necessitating the maintenance of both styles for different Node.js versions.
 
-Use the following command to enable experimental ESM support:
-
-- For Node.js versions greater than or equal to 18.19:
+Use the following command to enable ESM support:
 
 ```sh
 node --import  /path/to/instana/node_modules/@instana/collector/esm-register.mjs entry-point
 ```
-- For Node.js versions less than 18.19:
-
-```sh
-node --experimental-loader /path/to/instana/node_modules/@instana/collector/esm-loader.mjs entry-point
-```
 
 ## Node.js prerelease
 

packages/aws-fargate/esm-loader.mjs

@@ -5,6 +5,8 @@
 'use strict';
 
 /**
+ * IMPORTANT: This file is deprecated, no longer supported, and will be removed in the next major release (v6).
+ * 
  * IMPORTANT NOTE: From Node.js version 18.19 and above, the ESM loaders operate off-thread.
  * Consequently, ESM instrumentation using '--experimental-loader' becomes deprecated.
  * Instead, we are using '--import' for loading instrumentation and relocated the Instana collector

packages/aws-fargate/src/preactivate.js

@@ -5,18 +5,45 @@
 
 'use strict';
 
-const { isNodeJsTooOld, minimumNodeJsVersion } = require('@instana/core/src/util/nodeJsVersionCheck');
+const { esm, nodeJsVersionCheck } = require('@instana/core/src/util');
 
-if (isNodeJsTooOld()) {
+if (nodeJsVersionCheck.isNodeJsTooOld()) {
   // eslint-disable-next-line no-console
   console.error(
-    `The package @instana/aws-fargate requires at least Node.js ${minimumNodeJsVersion} but this process is ` +
+    // eslint-disable-next-line max-len
+    `The package @instana/aws-fargate requires at least Node.js ${nodeJsVersionCheck.minimumNodeJsVersion} but this process is ` +
       `running on Node.js ${process.version}. This Fargate container will not be monitored by Instana.` +
       'See https://www.ibm.com/docs/en/instana-observability/current?topic=agents-aws-fargate#versioning.'
   );
   return;
 }
 
+// Check for unsupported ESM loader configurations and exit early
+if (esm.hasExperimentalLoaderFlag()) {
+  // eslint-disable-next-line no-console
+  console.error(
+    "Node.js 18.19.0 and later no longer support the '--experimental-loader' flag for ESM. " +
+      `Your current version is ${process.version}. To ensure tracing by Instana, ` +
+      "please use the '--import' flag instead. For more information, refer to the Instana documentation: " +
+      'https://www.ibm.com/docs/en/instana-observability/current?topic=nodejs-collector-installation.'
+  );
+  return;
+}
+
+// This loader worked with '--experimental-loader' in Node.js versions below 18.19.
+// TODO: Remove 'esm-loader.mjs' file and this log in the next major release (v6).
+if (esm.hasEsmLoaderFile()) {
+  // eslint-disable-next-line no-console
+  console.error(
+    "Importing 'esm-loader.mjs' is not a valid command. " +
+      'This process will not be monitored by Instana. ' +
+      "Use 'esm-register.mjs' with '--import' to enable tracing.  For more information, " +
+      'refer to the Instana documentation: ' +
+      'https://www.ibm.com/docs/en/instana-observability/current?topic=nodejs-collector-installation.'
+  );
+  return;
+}
+
 const { util: coreUtil } = require('@instana/core');
 const { environment: environmentUtil, consoleLogger: serverlessLogger } = require('@instana/serverless');
 

packages/aws-fargate/test/Control.js

@@ -13,7 +13,6 @@ const config = require('@instana/core/test/config');
 const AbstractServerlessControl = require('../../serverless/test/util/AbstractServerlessControl');
 const portfinder = require('../../collector/test/test_util/portfinder');
 const PATH_TO_INSTANA_FARGATE_PACKAGE = path.join(__dirname, '..');
-const isLatestEsmSupportedVersion = require('@instana/core').util.esm.isLatestEsmSupportedVersion;
 let execArg;
 
 function Control(opts) {
@@ -99,9 +98,7 @@ Control.prototype.startMonitoredProcess = function startMonitoredProcess() {
     env.INSTANA_AGENT_KEY = this.instanaAgentKey;
   }
 
-  const loaderPath = isLatestEsmSupportedVersion(process.versions.node)
-    ? ['--import', `${path.join(__dirname, '..', 'esm-register.mjs')}`]
-    : [`--experimental-loader=${path.join(__dirname, '..', 'esm-loader.mjs')}`];
+  const loaderPath = ['--import', `${path.join(__dirname, '..', 'esm-register.mjs')}`];
 
   if (this.opts.containerAppPath && this.opts.env && this.opts.env.ESM_TEST) {
     if (this.opts.containerAppPath.endsWith('.mjs')) {

packages/azure-container-services/esm-loader.mjs

@@ -5,6 +5,8 @@
 'use strict';
 
 /**
+ * IMPORTANT: This file is deprecated, no longer supported, and will be removed in the next major release (v6).
+ *
  * IMPORTANT NOTE: From Node.js version 18.19 and above, the ESM loaders operate off-thread.
  * Consequently, ESM instrumentation using '--experimental-loader' becomes deprecated.
  * Instead, we are using '--import' for loading instrumentation and relocated the Instana collector

packages/azure-container-services/src/index.js

@@ -4,21 +4,47 @@
 
 'use strict';
 
-const { isNodeJsTooOld, minimumNodeJsVersion } = require('@instana/core/src/util/nodeJsVersionCheck');
+const { esm, nodeJsVersionCheck } = require('@instana/core/src/util');
 
 // As of now, Azure App Service supports Node.js versions 16-lts,18-lts and 20-lts. However, for existing services,
 // older Node.js versions might still be supported. You can find more information about configuring Node.js on Azure
 // App Service at: https://learn.microsoft.com/en-us/azure/app-service/configure-language-nodejs?pivots=platform-linux
 
-if (isNodeJsTooOld()) {
+if (nodeJsVersionCheck.isNodeJsTooOld()) {
   // eslint-disable-next-line no-console
   console.error(
-    `The package @instana/azure-container-services requires at least Node.js ${minimumNodeJsVersion} but this` +
+    // eslint-disable-next-line max-len
+    `The package @instana/azure-container-services requires at least Node.js ${nodeJsVersionCheck.minimumNodeJsVersion} but this` +
       `process is running on Node.js ${process.version}. This azure container service will not be monitored by Instana.`
   );
   return;
 }
 
+if (esm.hasExperimentalLoaderFlag()) {
+  // eslint-disable-next-line no-console
+  console.error(
+    "Node.js 18.19.0 and later no longer support the '--experimental-loader' flag for ESM. " +
+      `Your current version is ${process.version}. To ensure tracing by Instana, ` +
+      "please use the '--import' flag instead. For more information, refer to the Instana documentation: " +
+      'https://www.ibm.com/docs/en/instana-observability/current?topic=nodejs-collector-installation.'
+  );
+  return;
+}
+
+// This loader worked with '--experimental-loader' in Node.js versions below 18.19.
+// TODO: Remove 'esm-loader.mjs' file and this log in the next major release (v6).
+if (esm.hasEsmLoaderFile()) {
+  // eslint-disable-next-line no-console
+  console.error(
+    "Importing 'esm-loader.mjs' is not supported and will be removed in next major release. " +
+      'This process will not be monitored by Instana. ' +
+      "Use 'esm-register.mjs' with '--import' to enable tracing.  For more information, " +
+      'refer to the Instana documentation: ' +
+      'https://www.ibm.com/docs/en/instana-observability/current?topic=nodejs-collector-installation.'
+  );
+  return;
+}
+
 const { util: coreUtil } = require('@instana/core');
 const { environment: environmentUtil, consoleLogger: log } = require('@instana/serverless');
 

packages/azure-container-services/test/Control.js

@@ -10,7 +10,6 @@ const fetch = require('node-fetch-v2');
 const portfinder = require('@instana/collector/test/test_util/portfinder');
 const config = require('@instana/core/test/config');
 const AbstractServerlessControl = require('../../serverless/test/util/AbstractServerlessControl');
-const isLatestEsmSupportedVersion = require('@instana/core').util.esm.isLatestEsmSupportedVersion;
 
 const PATH_TO_INSTANA_AZURE_PACKAGE = path.join(__dirname, '..');
 let execArg;
@@ -59,9 +58,7 @@ class Control extends AbstractServerlessControl {
       env.INSTANA_AGENT_KEY = this.instanaAgentKey;
     }
 
-    const loaderPath = isLatestEsmSupportedVersion(process.versions.node)
-      ? ['--import', `${path.join(__dirname, '..', 'esm-register.mjs')}`]
-      : [`--experimental-loader=${path.join(__dirname, '..', 'esm-loader.mjs')}`];
+    const loaderPath = ['--import', `${path.join(__dirname, '..', 'esm-register.mjs')}`];
 
     if (this.opts.containerAppPath && this.opts.env && this.opts.env.ESM_TEST) {
       execArg = this.opts.containerAppPath.endsWith('.mjs') ? loaderPath : ['--require', PATH_TO_INSTANA_AZURE_PACKAGE];

packages/collector/esm-loader.mjs

@@ -5,6 +5,8 @@
 'use strict';
 
 /**
+ * IMPORTANT: This file is deprecated, no longer supported, and will be removed in the next major release (v6).
+ *
  * IMPORTANT NOTE: From Node.js version 18.19 and above, the ESM loaders operate off-thread.
  * Consequently, ESM instrumentation using '--experimental-loader' becomes deprecated.
  * Instead, we are using '--import' for loading instrumentation and relocated the Instana collector

packages/collector/src/index.js

@@ -5,7 +5,7 @@
 
 'use strict';
 
-const { isNodeJsTooOld, minimumNodeJsVersion } = require('@instana/core/src/util/nodeJsVersionCheck');
+const { esm, nodeJsVersionCheck } = require('@instana/core/src/util');
 const { isProcessAvailable } = require('@instana/core/src/util/moduleAvailable');
 
 if (!isProcessAvailable()) {
@@ -20,10 +20,11 @@ if (!isProcessAvailable()) {
   return;
 }
 
-if (isNodeJsTooOld()) {
+if (nodeJsVersionCheck.isNodeJsTooOld()) {
   // eslint-disable-next-line no-console
   console.error(
-    `The package @instana/collector requires at least Node.js ${minimumNodeJsVersion} but this process is ` +
+    // eslint-disable-next-line max-len
+    `The package @instana/collector requires at least Node.js ${nodeJsVersionCheck.minimumNodeJsVersion} but this process is ` +
       `running on Node.js ${process.version}. This process will not be monitored by Instana.`
   );
 
@@ -34,6 +35,36 @@ if (isNodeJsTooOld()) {
   return;
 }
 
+// v18.19 and above usage of --experimental-loader flag no longer supported
+// TODO: Remove error log in the next major release(v6)
+if (esm.hasExperimentalLoaderFlag()) {
+  // eslint-disable-next-line no-console
+  console.error(
+    "Node.js 18.19.0 and later no longer support the '--experimental-loader' flag for ESM. " +
+      `Your current version is ${process.version}. To ensure tracing by Instana, ` +
+      "please use the '--import' flag instead. For more information, refer to the Instana documentation: " +
+      'https://www.ibm.com/docs/en/instana-observability/current?topic=nodejs-collector-installation.'
+  );
+  module.exports.default = function noOp() {};
+  // @ts-ignore TS1108
+  return;
+}
+
+//  This loader worked with '--experimental-loader' in Node.js versions below 18.19.
+//  TODO: Remove 'esm-loader.mjs' file and this log in the next major release (v6).
+if (esm.hasEsmLoaderFile()) {
+  // eslint-disable-next-line no-console
+  console.error(
+    "Importing 'esm-loader.mjs' is not supported and will be removed in next major release. " +
+      'This process will not be monitored by Instana. ' +
+      "Use 'esm-register.mjs' with '--import' to enable tracing.  For more information, " +
+      'refer to the Instana documentation: ' +
+      'https://www.ibm.com/docs/en/instana-observability/current?topic=nodejs-collector-installation.'
+  );
+  module.exports.default = function noOp() {};
+  // @ts-ignore TS1108
+  return;
+}
 let isMainThread = true;
 try {
   isMainThread = require('worker_threads').isMainThread;

packages/collector/test/test_util/ProcessControls.js

@@ -20,7 +20,6 @@ const globalAgent = require('../globalAgent');
 const portFinder = require('./portfinder');
 const sslDir = path.join(__dirname, '..', 'apps', 'ssl');
 const cert = fs.readFileSync(path.join(sslDir, 'cert'));
-const isLatestEsmSupportedVersion = require('@instana/core').util.esm.isLatestEsmSupportedVersion;
 
 class ProcessControls {
   /**
@@ -57,10 +56,7 @@ class ProcessControls {
     }
 
     if (process.env.RUN_ESM && !opts.execArgv) {
-      const resolveEsmLoader = () =>
-        isLatestEsmSupportedVersion(process.versions.node)
-          ? [`--import=${path.join(__dirname, '..', '..', 'esm-register.mjs')}`]
-          : [`--experimental-loader=${path.join(__dirname, '..', '..', 'esm-loader.mjs')}`];
+      const esmLoader = [`--import=${path.join(__dirname, '..', '..', 'esm-register.mjs')}`];
 
       try {
         // Custom appPath is provided, use that. here we check the exact file name for esm app
@@ -72,13 +68,13 @@ class ProcessControls {
           const esmApp = testUtils.checkESMApp({ appPath: updatedPath });
 
           if (esmApp) {
-            opts.execArgv = resolveEsmLoader();
+            opts.execArgv = esmLoader;
             opts.appPath = updatedPath;
           }
         } else if (opts?.dirname) {
           const esmApp = testUtils.checkESMApp({ appPath: path.join(opts.dirname, 'app.mjs') });
           if (esmApp) {
-            opts.execArgv = resolveEsmLoader();
+            opts.execArgv = esmLoader;
             opts.appPath = path.join(opts.dirname, 'app.mjs');
           }
         }