feat(instrumentation-aws-lambda): add runtime-aware handler support with backward compatibility

Added runtime-aware handler support that automatically detects Node.js version from AWS_EXECUTION_ENV and adapts handler signatures accordingly. Node.js 24+ only supports Promise-based handlers, while Node.js 22 and lower support both callback and Promise-based handlers for backward compatibility.

Author: RaphaelManke

packages/instrumentation-aws-lambda/CHANGELOG.md

@@ -3,9 +3,12 @@
 
 ## [Unreleased]
 
-### Breaking Changes
+### Features
 
-* **instrumentation-aws-lambda:** Removed support for callback-based Lambda handlers. Only Promise-based handlers (async/await or functions returning Promises) are now supported. This aligns with AWS Lambda's deprecation of callbacks in Node.js 24 runtime. Users must migrate their handlers to Promise-based format before upgrading.
+* **instrumentation-aws-lambda:** Added runtime-aware handler support. The instrumentation automatically detects the Node.js runtime version from `AWS_EXECUTION_ENV` and adapts handler signatures accordingly:
+  - **Node.js 24+**: Only Promise-based handlers are supported (callbacks deprecated by AWS Lambda)
+  - **Node.js 22 and lower**: Both callback-based and Promise-based handlers are supported for backward compatibility
+  This ensures seamless operation across different Node.js runtime versions while respecting AWS Lambda's deprecation of callbacks in Node.js 24+.
 
 ## [0.60.1](https://github.com/open-telemetry/opentelemetry-js-contrib/compare/instrumentation-aws-lambda-v0.60.0...instrumentation-aws-lambda-v0.60.1) (2025-11-24)
 

packages/instrumentation-aws-lambda/README.md

@@ -25,23 +25,30 @@ npm install --save @opentelemetry/instrumentation-aws-lambda
 
 ## Important Notes
 
-### Callback-Based Handlers Deprecated
+### Handler Types Supported
 
-As of AWS Lambda Node.js 24 runtime, callback-based handlers are deprecated. This instrumentation now only supports Promise-based handlers (async/await or functions returning Promises). If you're using callback-based handlers, you must migrate to Promise-based handlers before upgrading to Node.js 24 runtime.
+This instrumentation automatically detects the Node.js runtime version and supports handlers accordingly:
 
-Example migration:
+- **Node.js 24+**: Only Promise-based handlers are supported (callbacks are deprecated by AWS Lambda)
+- **Node.js 22 and lower**: Both callback-based and Promise-based handlers are supported for backward compatibility
+
+The instrumentation detects the runtime version from the `AWS_EXECUTION_ENV` environment variable and adapts the handler signature accordingly. For Node.js 24+, the handler signature is `(event, context)`, while for Node.js 22 and lower, it supports both `(event, context, callback)` and `(event, context)`.
+
+Example handlers:
 ```js
-// ❌ Deprecated callback-based handler
+// Callback-based handler (Node.js 22 and lower only)
 exports.handler = function(event, context, callback) {
   callback(null, 'ok');
 };
 
-// ✅ Promise-based handler
+// Promise-based handler (all Node.js versions)
 exports.handler = async function(event, context) {
   return 'ok';
 };
 ```
 
+**Note**: AWS Lambda has deprecated callback-based handlers in Node.js 24 runtime. It's recommended to migrate to Promise-based handlers when upgrading to Node.js 24+.
+
 ## Usage
 
 Create a file to initialize the instrumentation, such as `lambda-wrapper.js`.

packages/instrumentation-aws-lambda/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentelemetry/instrumentation-aws-lambda",
-  "version": "0.60.1",
+  "version": "0.61.0",
   "description": "OpenTelemetry instrumentation for AWS Lambda function invocations",
   "main": "build/src/index.js",
   "types": "build/src/index.d.ts",

packages/instrumentation-aws-lambda/src/instrumentation.ts

@@ -45,6 +45,7 @@ import { ATTR_FAAS_EXECUTION, ATTR_FAAS_ID } from './semconv-obsolete';
 
 import {
   APIGatewayProxyEventHeaders,
+  Callback,
   Context,
   Handler,
   StreamifyHandler,
@@ -70,6 +71,25 @@ export const AWS_HANDLER_STREAMING_SYMBOL = Symbol.for(
 );
 export const AWS_HANDLER_STREAMING_RESPONSE = 'response';
 
+/**
+ * Detects the Node.js runtime version from AWS_EXECUTION_ENV environment variable.
+ * Returns the major version number (e.g., 24, 22, 20) or null if not detected.
+ */
+function getNodeRuntimeVersion(): number | null {
+  const executionEnv = process.env.AWS_EXECUTION_ENV;
+  if (!executionEnv) {
+    return null;
+  }
+
+  // AWS_EXECUTION_ENV format: AWS_Lambda_nodejs24.x, AWS_Lambda_nodejs22.x, etc.
+  const match = executionEnv.match(/AWS_Lambda_nodejs(\d+)\./);
+  if (match && match[1]) {
+    return parseInt(match[1], 10);
+  }
+
+  return null;
+}
+
 export class AwsLambdaInstrumentation extends InstrumentationBase<AwsLambdaInstrumentationConfig> {
   private declare _traceForceFlusher?: () => Promise<void>;
   private declare _metricForceFlusher?: () => Promise<void>;
@@ -271,43 +291,105 @@ export class AwsLambdaInstrumentation extends InstrumentationBase<AwsLambdaInstr
       };
     }
 
-    return function patchedHandler(
-      this: never,
-      // The event can be a user type, it truly is any.
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      event: any,
-      context: Context
-    ) {
-      _onRequest();
+    // Determine runtime version to decide whether to support callbacks
+    const nodeVersion = getNodeRuntimeVersion();
+    const supportsCallbacks = nodeVersion === null || nodeVersion < 24;
 
-      const parent = plugin._determineParent(event, context);
+    if (supportsCallbacks) {
+      // Node.js 22 and lower: Support callback-based handlers for backward compatibility
+      return function patchedHandlerWithCallback(
+        this: never,
+        // The event can be a user type, it truly is any.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        event: any,
+        context: Context,
+        callback?: Callback
+      ) {
+        _onRequest();
 
-      const span = plugin._createSpanForRequest(
-        event,
-        context,
-        requestIsColdStart,
-        parent
-      );
+        const parent = plugin._determineParent(event, context);
 
-      plugin._applyRequestHook(span, event, context);
-
-      return otelContext.with(trace.setSpan(parent, span), () => {
-        // Type assertion: Handler type from aws-lambda still includes callback parameter,
-        // but we only support Promise-based handlers now (Node.js 24+)
-        const maybePromise = safeExecuteInTheMiddle(
-          () => (original as (event: any, context: Context) => Promise<any> | any).apply(this, [event, context]),
-          error => {
-            if (error != null) {
-              // Exception thrown synchronously before resolving promise.
-              plugin._applyResponseHook(span, error);
-              plugin._endSpan(span, error, () => {});
-            }
+        const span = plugin._createSpanForRequest(
+          event,
+          context,
+          requestIsColdStart,
+          parent
+        );
+
+        plugin._applyRequestHook(span, event, context);
+
+        return otelContext.with(trace.setSpan(parent, span), () => {
+          // Support both callback-based and Promise-based handlers for backward compatibility
+          if (callback) {
+            const wrappedCallback = plugin._wrapCallback(callback, span);
+            const maybePromise = safeExecuteInTheMiddle(
+              () => original.apply(this, [event, context, wrappedCallback]),
+              error => {
+                if (error != null) {
+                  // Exception thrown synchronously before resolving callback / promise.
+                  plugin._applyResponseHook(span, error);
+                  plugin._endSpan(span, error, () => {});
+                }
+              }
+            ) as Promise<{}> | undefined;
+
+            return plugin._handlePromiseResult(span, maybePromise);
+          } else {
+            // Promise-based handler
+            const maybePromise = safeExecuteInTheMiddle(
+              () => (original as (event: any, context: Context) => Promise<any> | any).apply(this, [event, context]),
+              error => {
+                if (error != null) {
+                  // Exception thrown synchronously before resolving promise.
+                  plugin._applyResponseHook(span, error);
+                  plugin._endSpan(span, error, () => {});
+                }
+              }
+            ) as Promise<{}> | undefined;
+
+            return plugin._handlePromiseResult(span, maybePromise);
           }
-        ) as Promise<{}> | undefined;
+        });
+      };
+    } else {
+      // Node.js 24+: Only Promise-based handlers (callbacks deprecated)
+      return function patchedHandler(
+        this: never,
+        // The event can be a user type, it truly is any.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        event: any,
+        context: Context
+      ) {
+        _onRequest();
 
-        return plugin._handlePromiseResult(span, maybePromise);
-      });
-    };
+        const parent = plugin._determineParent(event, context);
+
+        const span = plugin._createSpanForRequest(
+          event,
+          context,
+          requestIsColdStart,
+          parent
+        );
+
+        plugin._applyRequestHook(span, event, context);
+
+        return otelContext.with(trace.setSpan(parent, span), () => {
+          // Promise-based handler only (Node.js 24+)
+          const maybePromise = safeExecuteInTheMiddle(
+            () => (original as (event: any, context: Context) => Promise<any> | any).apply(this, [event, context]),
+            error => {
+              if (error != null) {
+                // Exception thrown synchronously before resolving promise.
+                plugin._applyResponseHook(span, error);
+                plugin._endSpan(span, error, () => {});
+              }
+            }
+          ) as Promise<{}> | undefined;
+
+          return plugin._handlePromiseResult(span, maybePromise);
+        });
+      };
+    }
   }
 
   private _createSpanForRequest(
@@ -435,6 +517,19 @@ export class AwsLambdaInstrumentation extends InstrumentationBase<AwsLambdaInstr
     return undefined;
   }
 
+  private _wrapCallback(original: Callback, span: Span): Callback {
+    const plugin = this;
+    return function wrappedCallback(this: never, err, res) {
+      diag.debug('AWS Lambda instrumentation: Executing wrapped callback function');
+      plugin._applyResponseHook(span, err, res);
+
+      plugin._endSpan(span, err, () => {
+        diag.debug('AWS Lambda instrumentation: Executing original callback function');
+        return original.apply(this, [err, res]);
+      });
+    };
+  }
+
   private _endSpan(
     span: Span,
     err: string | Error | null | undefined,

packages/instrumentation-aws-lambda/test/integrations/lambda-handler.test.ts

@@ -392,6 +392,91 @@ describe('lambda handler', () => {
     assert.strictEqual(span.parentSpanContext?.spanId, undefined);
   });
 
+  describe('callback-based handler (Node.js 22 and lower)', () => {
+    beforeEach(() => {
+      // Simulate Node.js 22 runtime for backward compatibility testing
+      process.env.AWS_EXECUTION_ENV = 'AWS_Lambda_nodejs22.x';
+    });
+
+    afterEach(() => {
+      delete process.env.AWS_EXECUTION_ENV;
+    });
+
+    it('should export a valid span with callback handler', async () => {
+      initializeHandler('lambda-test/sync.callbackHandler');
+
+      const result = await new Promise((resolve, reject) => {
+        lambdaRequire('lambda-test/sync').callbackHandler(
+          'arg',
+          ctx,
+          (err: Error, res: any) => {
+            if (err) {
+              reject(err);
+            } else {
+              resolve(res);
+            }
+          }
+        );
+      });
+      assert.strictEqual(result, 'ok');
+      const spans = memoryExporter.getFinishedSpans();
+      const [span] = spans;
+      assert.strictEqual(spans.length, 1);
+      assertSpanSuccess(span);
+      assert.strictEqual(span.parentSpanContext?.spanId, undefined);
+    });
+
+    it('should record error with callback handler', async () => {
+      initializeHandler('lambda-test/sync.callbackError');
+
+      let err: Error;
+      try {
+        await new Promise((resolve, reject) => {
+          lambdaRequire('lambda-test/sync').callbackError(
+            'arg',
+            ctx,
+            (error: Error, _res: any) => {
+              if (error) {
+                reject(error);
+              } else {
+                resolve({});
+              }
+            }
+          );
+        });
+      } catch (e: any) {
+        err = e;
+      }
+      assert.strictEqual(err!.message, 'handler error');
+      const spans = memoryExporter.getFinishedSpans();
+      const [span] = spans;
+      assert.strictEqual(spans.length, 1);
+      assertSpanFailure(span);
+      assert.strictEqual(span.parentSpanContext?.spanId, undefined);
+    });
+
+    it('context should have parent trace with callback handler', async () => {
+      initializeHandler('lambda-test/sync.callbackContext');
+
+      const result = await new Promise((resolve, reject) => {
+        lambdaRequire('lambda-test/sync').callbackContext(
+          'arg',
+          ctx,
+          (err: Error, res: any) => {
+            if (err) {
+              reject(err);
+            } else {
+              resolve(res);
+            }
+          }
+        );
+      });
+      const spans = memoryExporter.getFinishedSpans();
+      const [span] = spans;
+      assert.strictEqual(span.spanContext().traceId, result);
+    });
+  });
+
   describe('with remote parent', () => {
     beforeEach(() => {
       propagation.disable();

packages/instrumentation-aws-lambda/test/lambda-test/sync.js

@@ -15,6 +15,7 @@
  */
 const api = require('@opentelemetry/api');
 
+// Promise-based handlers (all Node.js versions)
 exports.handler = async function (event, context) {
   return 'ok';
 };
@@ -38,3 +39,16 @@ exports.callbackstringerror = async function (event, context) {
 exports.context = async function (event, context) {
   return api.trace.getSpan(api.context.active()).spanContext().traceId;
 };
+
+// Callback-based handlers (Node.js 22 and lower only - for backward compatibility testing)
+exports.callbackHandler = function (event, context, callback) {
+  callback(null, 'ok');
+};
+
+exports.callbackError = function (event, context, callback) {
+  callback(new Error('handler error'));
+};
+
+exports.callbackContext = function (event, context, callback) {
+  callback(null, api.trace.getSpan(api.context.active()).spanContext().traceId);
+};