Activate ESM loader hook of the "import-in-the-middle" library for ES (EcmaScript) based user handlers (#1574)

* Activate ESM loader hook of the "import-in-the-middle" library for ES (EcmaScript) based user handlers

* Add tests

Author: serkan-ozal

nodejs/package-lock.json

@@ -9,9 +9,13 @@
     "lint": "ESLINT_USE_FLAT_CONFIG=false eslint . --ext .ts",
     "lint:fix": "ESLINT_USE_FLAT_CONFIG=false eslint . --ext .ts --fix",
     "build": "npm run clean && npm run compile && npm run postcompile",
+    "copy-esm-files": "copyfiles 'src/**/*.mjs' build && copyfiles 'test/**/*.mjs' build",
     "compile": "tsc -p .",
-    "postcompile": "copyfiles 'package*.json' build/workspace/nodejs && npm install --production --ignore-scripts --prefix build/workspace/nodejs && rm build/workspace/nodejs/package.json build/workspace/nodejs/package-lock.json && copyfiles -f 'scripts/*' build/workspace && copyfiles -f 'build/src/*' build/workspace && cd build/workspace && bestzip ../layer.zip *",
-    "test": "mocha"
+    "postcompile": "npm run copy-esm-files && copyfiles 'package*.json' build/workspace/nodejs && npm install --production --ignore-scripts --prefix build/workspace/nodejs && rm build/workspace/nodejs/package.json build/workspace/nodejs/package-lock.json && copyfiles -f 'scripts/*' build/workspace && copyfiles -f 'build/src/*' build/workspace && cd build/workspace && bestzip ../layer.zip *",
+    "pretest": "npm run compile",
+    "test:cjs": "mocha 'test/**/*.spec.ts' --exclude 'test/**/*.spec.mjs' --timeout 10000",
+    "test:esm": "mocha 'test/**/*.spec.mjs' --exclude 'test/**/*.spec.ts' --timeout 10000",
+    "test": "npm run test:cjs && npm run test:esm"
   },
   "keywords": [
     "opentelemetry",
@@ -28,21 +32,21 @@
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/api-logs": "^0.54.0",
-    "@opentelemetry/exporter-logs-otlp-proto": "^0.54.0",
+    "@opentelemetry/api-logs": "^0.54.2",
+    "@opentelemetry/exporter-logs-otlp-proto": "^0.54.2",
     "@opentelemetry/auto-configuration-propagators": "^0.3.1",
     "@opentelemetry/core": "^1.27.0",
-    "@opentelemetry/exporter-metrics-otlp-proto": "^0.54.0",
-    "@opentelemetry/exporter-trace-otlp-proto": "^0.54.0",
-    "@opentelemetry/instrumentation": "^0.54.0",
-    "@opentelemetry/instrumentation-aws-lambda": "^0.46.0",
-    "@opentelemetry/instrumentation-aws-sdk": "^0.45.0",
+    "@opentelemetry/exporter-metrics-otlp-proto": "^0.54.2",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.54.2",
+    "@opentelemetry/instrumentation": "^0.54.2",
+    "@opentelemetry/instrumentation-aws-lambda": "^0.47.0",
+    "@opentelemetry/instrumentation-aws-sdk": "^0.46.0",
     "@opentelemetry/instrumentation-dns": "^0.40.0",
     "@opentelemetry/instrumentation-express": "^0.44.0",
     "@opentelemetry/instrumentation-graphql": "^0.44.0",
-    "@opentelemetry/instrumentation-grpc": "^0.54.0",
+    "@opentelemetry/instrumentation-grpc": "^0.54.2",
     "@opentelemetry/instrumentation-hapi": "^0.42.0",
-    "@opentelemetry/instrumentation-http": "^0.54.0",
+    "@opentelemetry/instrumentation-http": "^0.54.2",
     "@opentelemetry/instrumentation-ioredis": "^0.44.0",
     "@opentelemetry/instrumentation-koa": "^0.44.0",
     "@opentelemetry/instrumentation-mongodb": "^0.48.0",
@@ -53,7 +57,7 @@
     "@opentelemetry/propagator-aws-xray": "^1.26.0",
     "@opentelemetry/resource-detector-aws": "^1.7.0",
     "@opentelemetry/resources": "^1.27.0",
-    "@opentelemetry/sdk-logs": "^0.54.0",
+    "@opentelemetry/sdk-logs": "^0.54.2",
     "@opentelemetry/sdk-metrics": "^1.27.0",
     "@opentelemetry/sdk-trace-base": "^1.27.0",
     "@opentelemetry/sdk-trace-node": "^1.27.0"

nodejs/packages/layer/package-lock.json

@@ -2,7 +2,7 @@
 
 set -ef -o pipefail
 
-export NODE_OPTIONS="${NODE_OPTIONS} --require /opt/wrapper.js"
+export NODE_OPTIONS="${NODE_OPTIONS} --import /opt/loader.mjs --require /opt/wrapper.js"
 
 if [[ $OTEL_RESOURCE_ATTRIBUTES != *"service.name="* ]]; then
   export OTEL_RESOURCE_ATTRIBUTES="service.name=${AWS_LAMBDA_FUNCTION_NAME},${OTEL_RESOURCE_ATTRIBUTES}"

nodejs/packages/layer/package.json

@@ -0,0 +1,91 @@
+import { register } from 'module';
+import * as path from 'path';
+import * as fs from 'fs';
+
+function _hasFolderPackageJsonTypeModule(folder) {
+  if (folder.endsWith('/node_modules')) {
+    return false;
+  }
+  let pj = path.join(folder, '/package.json');
+  if (fs.existsSync(pj)) {
+    try {
+      let pkg = JSON.parse(fs.readFileSync(pj).toString());
+      if (pkg) {
+        if (pkg.type === 'module') {
+          return true;
+        } else {
+          return false;
+        }
+      }
+    } catch (e) {
+      console.warn(`${pj} cannot be read, it will be ignored for ES module detection purposes.`, e);
+      return false;
+    }
+  }
+  if (folder === '/') {
+    return false;
+  }
+  return _hasFolderPackageJsonTypeModule(path.resolve(folder, '..'));
+}
+
+function _hasPackageJsonTypeModule(file) {
+  let jsPath = file + '.js';
+  if (fs.existsSync(jsPath)) {
+    return _hasFolderPackageJsonTypeModule(path.resolve(path.dirname(jsPath)));
+  }
+  return false;
+}
+
+function _resolveHandlerFileName() {
+  const taskRoot = process.env.LAMBDA_TASK_ROOT;
+  const handlerDef = process.env._HANDLER;
+  if (!taskRoot || !handlerDef) {
+    return null;
+  }
+  const handler = path.basename(handlerDef);
+  const moduleRoot = handlerDef.substr(0, handlerDef.length - handler.length);
+  const [module, _] = handler.split('.', 2);
+  return path.resolve(taskRoot, moduleRoot, module);
+}
+
+function _isHandlerAnESModule() {
+  try {
+    const handlerFileName = _resolveHandlerFileName();
+    if (!handlerFileName) {
+      return false;
+    }
+    if (fs.existsSync(handlerFileName + '.mjs')) {
+      return true;
+    } else if (fs.existsSync(handlerFileName + '.cjs')) {
+      return false;
+    } else {
+      return _hasPackageJsonTypeModule(handlerFileName);
+    }
+  } catch (e) {
+    console.error('Unknown error occurred while checking whether handler is an ES module', e);
+    return false;
+  }
+}
+
+let registered = false;
+
+export function registerLoader() {
+  if (!registered) {
+    register('import-in-the-middle/hook.mjs', import.meta.url);
+    registered = true;
+  }
+}
+
+if (_isHandlerAnESModule()) {
+  /*
+  We could activate ESM loader hook of the "import-in-the-middle" library,
+  - by "--loader=import-in-the-middle/hook.mjs" Node CLI option, but "--loader" option has been deprecated
+  - or by "--import=import-in-the-middle/hook.mjs" Node CLI option, but in this case,
+    there will always be "import-in-the-middle" hook initialization overhead even for non-ESM (CommonJS) modules
+
+  Hence, instead, we initialize "import-in-the-middle" hook only for ES (EcmaScript) based user handlers
+  to prevent redundant "import-in-the-middle" hook initialization overhead during coldstart
+  of the CommonJS based user handlers.
+   */
+  registerLoader();
+}

nodejs/packages/layer/scripts/otel-handler

@@ -27,10 +27,13 @@ import {
   AwsLambdaInstrumentationConfig,
 } from '@opentelemetry/instrumentation-aws-lambda';
 import {
+  context,
   diag,
   DiagConsoleLogger,
   DiagLogLevel,
   metrics,
+  propagation,
+  trace,
 } from '@opentelemetry/api';
 import { getEnv } from '@opentelemetry/core';
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
@@ -51,8 +54,8 @@ import {
 import { logs } from '@opentelemetry/api-logs';
 
 function defaultConfigureInstrumentations() {
-  // Use require statements for instrumentation to avoid having to have transitive dependencies on all the typescript
-  // definitions.
+  // Use require statements for instrumentation
+  // to avoid having to have transitive dependencies on all the typescript definitions.
   const { DnsInstrumentation } = require('@opentelemetry/instrumentation-dns');
   const {
     ExpressInstrumentation,
@@ -102,7 +105,7 @@ function defaultConfigureInstrumentations() {
 }
 
 declare global {
-  // in case of downstream configuring span processors etc
+  // In case of downstream configuring span processors etc
   function configureAwsInstrumentation(
     defaultConfig: AwsSdkInstrumentationConfig,
   ): AwsSdkInstrumentationConfig;
@@ -123,34 +126,25 @@ declare global {
   function configureInstrumentations(): Instrumentation[];
 }
 
-console.log('Registering OpenTelemetry');
-
-const instrumentations = [
-  new AwsInstrumentation(
-    typeof configureAwsInstrumentation === 'function'
-      ? configureAwsInstrumentation({ suppressInternalInstrumentation: true })
-      : { suppressInternalInstrumentation: true },
-  ),
-  new AwsLambdaInstrumentation(
-    typeof configureLambdaInstrumentation === 'function'
-      ? configureLambdaInstrumentation({})
-      : {},
-  ),
-  ...(typeof configureInstrumentations === 'function'
-    ? configureInstrumentations
-    : defaultConfigureInstrumentations)(),
-];
-
-// configure lambda logging
-const logLevel = getEnv().OTEL_LOG_LEVEL;
-diag.setLogger(new DiagConsoleLogger(), logLevel);
-
-// Register instrumentations synchronously to ensure code is patched even before provider is ready.
-registerInstrumentations({
-  instrumentations,
-});
+function createInstrumentations() {
+  return [
+    new AwsInstrumentation(
+      typeof configureAwsInstrumentation === 'function'
+        ? configureAwsInstrumentation({ suppressInternalInstrumentation: true })
+        : { suppressInternalInstrumentation: true },
+    ),
+    new AwsLambdaInstrumentation(
+      typeof configureLambdaInstrumentation === 'function'
+        ? configureLambdaInstrumentation({})
+        : {},
+    ),
+    ...(typeof configureInstrumentations === 'function'
+      ? configureInstrumentations
+      : defaultConfigureInstrumentations)(),
+  ];
+}
 
-async function initializeProvider() {
+function initializeProvider() {
   const resource = detectResourcesSync({
     detectors: [awsLambdaDetector, envDetector, processDetector],
   });
@@ -166,12 +160,12 @@ async function initializeProvider() {
   if (typeof configureTracerProvider === 'function') {
     configureTracerProvider(tracerProvider);
   } else {
-    // defaults
+    // Defaults
     tracerProvider.addSpanProcessor(
       new BatchSpanProcessor(new OTLPTraceExporter()),
     );
   }
-  // logging for debug
+  // Logging for debug
   if (logLevel === DiagLogLevel.DEBUG) {
     tracerProvider.addSpanProcessor(
       new SimpleSpanProcessor(new ConsoleSpanExporter()),
@@ -182,7 +176,7 @@ async function initializeProvider() {
   if (typeof configureSdkRegistration === 'function') {
     sdkRegistrationConfig = configureSdkRegistration(sdkRegistrationConfig);
   }
-  // auto-configure propagator if not provided
+  // Auto-configure propagator if not provided
   if (!sdkRegistrationConfig.propagator) {
     sdkRegistrationConfig.propagator = getPropagator();
   }
@@ -223,20 +217,58 @@ async function initializeProvider() {
     logs.setGlobalLoggerProvider(loggerProvider);
   }
 
-  // logging for debug
+  // Logging for debug
   if (logLevel === DiagLogLevel.DEBUG) {
     loggerProvider.addLogRecordProcessor(
       new SimpleLogRecordProcessor(new ConsoleLogRecordExporter()),
     );
   }
 
+  // Create instrumentations if they have not been created before
+  // to prevent additional coldstart overhead
+  // caused by creations and initializations of instrumentations.
+  if (!instrumentations || !instrumentations.length) {
+    instrumentations = createInstrumentations();
+  }
+
   // Re-register instrumentation with initialized provider. Patched code will see the update.
-  registerInstrumentations({
+  disableInstrumentations = registerInstrumentations({
     instrumentations,
     tracerProvider,
     meterProvider,
     loggerProvider,
   });
 }
-// eslint-disable-next-line @typescript-eslint/no-floating-promises
-initializeProvider();
+
+export function wrap() {
+  initializeProvider();
+}
+
+export function unwrap() {
+  if (disableInstrumentations) {
+    disableInstrumentations();
+    disableInstrumentations = () => {};
+  }
+  instrumentations = [];
+  context.disable();
+  propagation.disable();
+  trace.disable();
+  metrics.disable();
+  logs.disable();
+}
+
+console.log('Registering OpenTelemetry');
+
+// Configure lambda logging
+const logLevel = getEnv().OTEL_LOG_LEVEL;
+diag.setLogger(new DiagConsoleLogger(), logLevel);
+
+let instrumentations = createInstrumentations();
+let disableInstrumentations: () => void;
+
+// Register instrumentations synchronously to ensure code is patched even before provider is ready.
+disableInstrumentations = registerInstrumentations({
+  instrumentations,
+});
+
+wrap();