feat(aws): Add SENTRY_LAYER_EXTENSION to configure using the lambda layer

extension via env variables

Author: andreiborza

packages/aws-serverless/package.json

@@ -71,6 +71,7 @@
     "@opentelemetry/semantic-conventions": "^1.37.0",
     "@sentry/core": "10.22.0",
     "@sentry/node": "10.22.0",
+    "@sentry/node-core": "10.22.0",
     "@types/aws-lambda": "^8.10.62"
   },
   "devDependencies": {

packages/aws-serverless/src/init.ts

@@ -2,6 +2,7 @@ import type { Integration, Options } from '@sentry/core';
 import { applySdkMetadata, debug, getSDKSource } from '@sentry/core';
 import type { NodeClient, NodeOptions } from '@sentry/node';
 import { getDefaultIntegrationsWithoutPerformance, initWithoutDefaultIntegrations } from '@sentry/node';
+import { envToBool } from '@sentry/node-core';
 import { DEBUG_BUILD } from './debug-build';
 import { awsIntegration } from './integration/aws';
 import { awsLambdaIntegration } from './integration/awslambda';
@@ -54,7 +55,10 @@ export function getDefaultIntegrations(_options: Options): Integration[] {
 
 export interface AwsServerlessOptions extends NodeOptions {
   /**
-   * If Sentry events should be proxied through the Lambda extension when using the Lambda layer. Defaults to `true` when using the Lambda layer.
+   * If Sentry events should be proxied through the Lambda extension when using the Lambda layer.
+   * Defaults to `true` when using the Lambda layer.
+   *
+   * Can also be configured via the `SENTRY_LAYER_EXTENSION` environment variable.
    */
   useLayerExtension?: boolean;
 }
@@ -68,9 +72,23 @@ export function init(options: AwsServerlessOptions = {}): NodeClient | undefined
   const sdkSource = getSDKSource();
   const proxyWouldInterfere = shouldDisableLayerExtensionForProxy();
 
+  // Determine useLayerExtension value with the following priority:
+  // 1. Explicit option value (if provided)
+  // 2. Environment variable SENTRY_LAYER_EXTENSION (if set)
+  // 3. Default logic based on sdkSource, tunnel, and proxy settings
+  const useLayerExtensionFromEnv = envToBool(process.env.SENTRY_LAYER_EXTENSION, { strict: true });
+  const defaultUseLayerExtension = sdkSource === 'aws-lambda-layer' && !options.tunnel && !proxyWouldInterfere;
+
+  const useLayerExtension =
+    options.useLayerExtension !== undefined
+      ? options.useLayerExtension
+      : useLayerExtensionFromEnv !== null
+        ? useLayerExtensionFromEnv
+        : defaultUseLayerExtension;
+
   const opts = {
     defaultIntegrations: getDefaultIntegrations(options),
-    useLayerExtension: sdkSource === 'aws-lambda-layer' && !options.tunnel && !proxyWouldInterfere,
+    useLayerExtension,
     ...options,
   };
 

packages/aws-serverless/test/init.test.ts

@@ -22,6 +22,7 @@ describe('init', () => {
     // Clean up environment variables between tests
     delete process.env.http_proxy;
     delete process.env.no_proxy;
+    delete process.env.SENTRY_LAYER_EXTENSION;
   });
 
   describe('Lambda extension setup', () => {
@@ -386,4 +387,173 @@ describe('init', () => {
       );
     });
   });
+
+  describe('SENTRY_LAYER_EXTENSION environment variable', () => {
+    test('should enable useLayerExtension when SENTRY_LAYER_EXTENSION=true', () => {
+      process.env.SENTRY_LAYER_EXTENSION = 'true';
+      mockGetSDKSource.mockReturnValue('aws-lambda-layer');
+      const options: AwsServerlessOptions = {};
+
+      init(options);
+
+      expect(mockInitWithoutDefaultIntegrations).toHaveBeenCalledWith(
+        expect.objectContaining({
+          useLayerExtension: true,
+          tunnel: 'http://localhost:9000/envelope',
+        }),
+      );
+    });
+
+    test('should disable useLayerExtension when SENTRY_LAYER_EXTENSION=false', () => {
+      process.env.SENTRY_LAYER_EXTENSION = 'false';
+      mockGetSDKSource.mockReturnValue('aws-lambda-layer');
+      const options: AwsServerlessOptions = {};
+
+      init(options);
+
+      expect(mockInitWithoutDefaultIntegrations).toHaveBeenCalledWith(
+        expect.objectContaining({
+          useLayerExtension: false,
+        }),
+      );
+      expect(mockInitWithoutDefaultIntegrations).toHaveBeenCalledWith(
+        expect.not.objectContaining({
+          tunnel: expect.any(String),
+        }),
+      );
+    });
+
+    test('should support various truthy values (1, yes, on)', () => {
+      const truthyValues = ['1', 'yes', 'on', 'y', 't'];
+
+      truthyValues.forEach(value => {
+        mockGetSDKSource.mockReturnValue('aws-lambda-layer');
+        process.env.SENTRY_LAYER_EXTENSION = value;
+
+        init({});
+
+        expect(mockInitWithoutDefaultIntegrations).toHaveBeenCalledWith(
+          expect.objectContaining({
+            useLayerExtension: true,
+          }),
+        );
+      });
+    });
+
+    test('should support various falsy values (0, no, off)', () => {
+      const falsyValues = ['0', 'no', 'off', 'n', 'f'];
+
+      falsyValues.forEach(value => {
+        mockGetSDKSource.mockReturnValue('aws-lambda-layer');
+        process.env.SENTRY_LAYER_EXTENSION = value;
+
+        init({});
+
+        expect(mockInitWithoutDefaultIntegrations).toHaveBeenCalledWith(
+          expect.objectContaining({
+            useLayerExtension: false,
+          }),
+        );
+      });
+    });
+
+    test('should fall back to default behavior when SENTRY_LAYER_EXTENSION is not set', () => {
+      mockGetSDKSource.mockReturnValue('aws-lambda-layer');
+      const options: AwsServerlessOptions = {};
+
+      init(options);
+
+      expect(mockInitWithoutDefaultIntegrations).toHaveBeenCalledWith(
+        expect.objectContaining({
+          useLayerExtension: true,
+          tunnel: 'http://localhost:9000/envelope',
+        }),
+      );
+    });
+
+    test('should fall back to default behavior when SENTRY_LAYER_EXTENSION has invalid value', () => {
+      process.env.SENTRY_LAYER_EXTENSION = 'invalid';
+      mockGetSDKSource.mockReturnValue('aws-lambda-layer');
+      const options: AwsServerlessOptions = {};
+
+      init(options);
+
+      expect(mockInitWithoutDefaultIntegrations).toHaveBeenCalledWith(
+        expect.objectContaining({
+          useLayerExtension: true,
+          tunnel: 'http://localhost:9000/envelope',
+        }),
+      );
+    });
+
+    test('should prioritize explicit option over environment variable', () => {
+      process.env.SENTRY_LAYER_EXTENSION = 'true';
+      mockGetSDKSource.mockReturnValue('aws-lambda-layer');
+      const options: AwsServerlessOptions = {
+        useLayerExtension: false,
+      };
+
+      init(options);
+
+      expect(mockInitWithoutDefaultIntegrations).toHaveBeenCalledWith(
+        expect.objectContaining({
+          useLayerExtension: false,
+        }),
+      );
+      expect(mockInitWithoutDefaultIntegrations).toHaveBeenCalledWith(
+        expect.not.objectContaining({
+          tunnel: expect.any(String),
+        }),
+      );
+    });
+
+    test('should respect environment variable when explicit option is not provided', () => {
+      process.env.SENTRY_LAYER_EXTENSION = 'false';
+      mockGetSDKSource.mockReturnValue('aws-lambda-layer');
+      const options: AwsServerlessOptions = {};
+
+      init(options);
+
+      expect(mockInitWithoutDefaultIntegrations).toHaveBeenCalledWith(
+        expect.objectContaining({
+          useLayerExtension: false,
+        }),
+      );
+    });
+
+    test('should enable useLayerExtension via env var even with proxy when explicitly set', () => {
+      process.env.http_proxy = 'http://proxy.example.com:8080';
+      process.env.SENTRY_LAYER_EXTENSION = 'true';
+      mockGetSDKSource.mockReturnValue('aws-lambda-layer');
+      const options: AwsServerlessOptions = {};
+
+      init(options);
+
+      expect(mockInitWithoutDefaultIntegrations).toHaveBeenCalledWith(
+        expect.objectContaining({
+          useLayerExtension: true,
+          tunnel: 'http://localhost:9000/envelope',
+        }),
+      );
+    });
+
+    test('should disable useLayerExtension via env var even without proxy', () => {
+      process.env.SENTRY_LAYER_EXTENSION = 'false';
+      mockGetSDKSource.mockReturnValue('aws-lambda-layer');
+      const options: AwsServerlessOptions = {};
+
+      init(options);
+
+      expect(mockInitWithoutDefaultIntegrations).toHaveBeenCalledWith(
+        expect.objectContaining({
+          useLayerExtension: false,
+        }),
+      );
+      expect(mockInitWithoutDefaultIntegrations).toHaveBeenCalledWith(
+        expect.not.objectContaining({
+          tunnel: expect.any(String),
+        }),
+      );
+    });
+  });
 });