feat(instrumentation-aws-lambda): remove callback-based handler support

BREAKING CHANGE: 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.

Changes:
- Removed Callback import and _wrapCallback method from instrumentation
- Updated patchedHandler to only accept (event, context) parameters
- Converted all test handlers from callback-based to Promise-based
- Updated all tests to use Promise-based handlers directly
- Added migration guide in README.md
- Documented breaking change in CHANGELOG.md

All 50 tests passing.

Author: RaphaelManke

packages/instrumentation-aws-lambda/CHANGELOG.md

@@ -1,6 +1,12 @@
 <!-- markdownlint-disable MD007 MD034 -->
 # Changelog
 
+## [Unreleased]
+
+### Breaking Changes
+
+* **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.
+
 ## [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

@@ -23,6 +23,25 @@ npm install --save @opentelemetry/instrumentation-aws-lambda
 
 - This package will instrument the lambda execution regardless of versions.
 
+## Important Notes
+
+### Callback-Based Handlers Deprecated
+
+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.
+
+Example migration:
+```js
+// ❌ Deprecated callback-based handler
+exports.handler = function(event, context, callback) {
+  callback(null, 'ok');
+};
+
+// ✅ Promise-based handler
+exports.handler = async function(event, context) {
+  return 'ok';
+};
+```
+
 ## Usage
 
 Create a file to initialize the instrumentation, such as `lambda-wrapper.js`.

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

@@ -45,7 +45,6 @@ import { ATTR_FAAS_EXECUTION, ATTR_FAAS_ID } from './semconv-obsolete';
 
 import {
   APIGatewayProxyEventHeaders,
-  Callback,
   Context,
   Handler,
   StreamifyHandler,
@@ -277,8 +276,7 @@ export class AwsLambdaInstrumentation extends InstrumentationBase<AwsLambdaInstr
       // 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
+      context: Context
     ) {
       _onRequest();
 
@@ -294,16 +292,13 @@ export class AwsLambdaInstrumentation extends InstrumentationBase<AwsLambdaInstr
       plugin._applyRequestHook(span, event, context);
 
       return otelContext.with(trace.setSpan(parent, span), () => {
-        // Lambda seems to pass a callback even if handler is of Promise form, so we wrap all the time before calling
-        // the handler and see if the result is a Promise or not. In such a case, the callback is usually ignored. If
-        // the handler happened to both call the callback and complete a returned Promise, whichever happens first will
-        // win and the latter will be ignored.
-        const wrappedCallback = plugin._wrapCallback(callback, 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.apply(this, [event, context, wrappedCallback]),
+          () => (original as (event: any, context: Context) => Promise<any> | any).apply(this, [event, context]),
           error => {
             if (error != null) {
-              // Exception thrown synchronously before resolving callback / promise.
+              // Exception thrown synchronously before resolving promise.
               plugin._applyResponseHook(span, error);
               plugin._endSpan(span, error, () => {});
             }
@@ -440,19 +435,6 @@ 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('executing wrapped lookup callback function');
-      plugin._applyResponseHook(span, err, res);
-
-      plugin._endSpan(span, err, () => {
-        diag.debug('executing original lookup callback function');
-        return original.apply(this, [err, res]);
-      });
-    };
-  }
-
   private _endSpan(
     span: Span,
     err: string | Error | null | undefined,
@@ -482,14 +464,14 @@ export class AwsLambdaInstrumentation extends InstrumentationBase<AwsLambdaInstr
       flushers.push(this._traceForceFlusher());
     } else {
       diag.debug(
-        'Spans may not be exported for the lambda function because we are not force flushing before callback.'
+        'Spans may not be exported for the lambda function because we are not force flushing before handler completion.'
       );
     }
     if (this._metricForceFlusher) {
       flushers.push(this._metricForceFlusher());
     } else {
       diag.debug(
-        'Metrics may not be exported for the lambda function because we are not force flushing before callback.'
+        'Metrics may not be exported for the lambda function because we are not force flushing before handler completion.'
       );
     }
 

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

@@ -100,19 +100,7 @@ describe('force flush', () => {
     provider.forceFlush = forceFlush;
     initializeHandlerTracing('lambda-test/sync.handler', provider);
 
-    await new Promise((resolve, reject) => {
-      lambdaRequire('lambda-test/sync').handler(
-        'arg',
-        ctx,
-        (err: Error, res: any) => {
-          if (err) {
-            reject(err);
-          } else {
-            resolve(res);
-          }
-        }
-      );
-    });
+    await lambdaRequire('lambda-test/sync').handler('arg', ctx);
 
     assert.strictEqual(forceFlushed, true);
   });
@@ -133,19 +121,7 @@ describe('force flush', () => {
     nodeTracerProvider.forceFlush = forceFlush;
     initializeHandlerTracing('lambda-test/sync.handler', provider);
 
-    await new Promise((resolve, reject) => {
-      lambdaRequire('lambda-test/sync').handler(
-        'arg',
-        ctx,
-        (err: Error, res: any) => {
-          if (err) {
-            reject(err);
-          } else {
-            resolve(res);
-          }
-        }
-      );
-    });
+    await lambdaRequire('lambda-test/sync').handler('arg', ctx);
 
     assert.strictEqual(forceFlushed, true);
   });
@@ -165,24 +141,12 @@ describe('force flush', () => {
     provider.forceFlush = forceFlush;
     initializeHandlerMetrics('lambda-test/sync.handler', provider);
 
-    await new Promise((resolve, reject) => {
-      lambdaRequire('lambda-test/sync').handler(
-        'arg',
-        ctx,
-        (err: Error, res: any) => {
-          if (err) {
-            reject(err);
-          } else {
-            resolve(res);
-          }
-        }
-      );
-    });
+    await lambdaRequire('lambda-test/sync').handler('arg', ctx);
 
     assert.strictEqual(forceFlushed, true);
   });
 
-  it('should callback once after force flush providers', async () => {
+  it('should complete handler after force flush providers', async () => {
     const nodeTracerProvider = new NodeTracerProvider({
       spanProcessors: [new BatchSpanProcessor(traceMemoryExporter)],
     });
@@ -216,24 +180,9 @@ describe('force flush', () => {
     instrumentation.setTracerProvider(tracerProvider);
     instrumentation.setMeterProvider(meterProvider);
 
-    let callbackCount = 0;
-    await new Promise((resolve, reject) => {
-      lambdaRequire('lambda-test/sync').handler(
-        'arg',
-        ctx,
-        (err: Error, res: any) => {
-          callbackCount++;
-          if (err) {
-            reject(err);
-          } else {
-            resolve(res);
-          }
-        }
-      );
-    });
+    await lambdaRequire('lambda-test/sync').handler('arg', ctx);
 
     assert.strictEqual(tracerForceFlushed, true);
     assert.strictEqual(meterForceFlushed, true);
-    assert.strictEqual(callbackCount, 1);
   });
 });