From 9ce5a04b3f1c4c576364571bad6a94dec5d52a21 Mon Sep 17 00:00:00 2001 From: Alex Angelillo Date: Fri, 20 Nov 2026 14:44:09 -0500 Subject: [PATCH 1/3] [SVLS-10133] Warn when instrumenting Lambda functions below 256 MB Co-Authored-By: Claude Opus 5.5 --- README.md | 1 + src/env.spec.ts | 16 +++++++ src/env.ts | 5 +++ src/index.spec.ts | 110 ++++++++++++++++++++++++++++++++++++++++++++++ src/index.ts | 8 ++++ src/layer.ts | 41 +++++++++++++++++ 6 files changed, 181 insertions(+) diff --git a/README.md b/README.md index e44bca9a..7e8dc4ee 100644 --- a/README.md +++ b/README.md @@ -73,6 +73,7 @@ To further configure your plugin, use the following custom parameters in your `s | `llmObsEnabled` | Toggle to enable submitting data to LLM Observability. Defaults to `false`. | | `llmObsMlApp` | The name of your LLM application, service, or project, under which all traces and spans are grouped. This helps distinguish between different applications or experiments. See [Application naming guidelines](https://docs.datadoghq.com/llm_observability/sdk/?tab=nodejs#application-naming-guidelines) for allowed characters and other constraints. To override this value for a given root span, see [Tracing multiple applications](https://docs.datadoghq.com/llm_observability/sdk/?tab=nodejs#tracing-multiple-applications). Required if `llmObsEnabled` is `true` | | `llmObsAgentlessEnabled` | Only required if you are not using the Datadog Lambda Extension, in which case this should be set to `true`. Defaults to `false`. | +| `suppressLowMemoryWarning` | The plugin prints a warning (reason `lambda_low_memory`) for each instrumented function with less than 256 MB of memory, because the Datadog Lambda Extension and tracer add memory overhead (about 69 MB for Python) that can cause out-of-memory errors and timeouts. The function's memory is `memorySize` on the function, then `provider.memorySize`, then the Serverless Framework default of 1024 MB. The function is still instrumented. Set to `true` to silence this warning. Defaults to `false`. | To use any of these parameters, add a `custom` > `datadog` section to your `serverless.yml` similar to this example: diff --git a/src/env.spec.ts b/src/env.spec.ts index f0d59ea1..7777cf29 100644 --- a/src/env.spec.ts +++ b/src/env.spec.ts @@ -193,6 +193,7 @@ describe("getConfig", () => { subscribeToAccessLogs: true, subscribeToExecutionLogs: false, subscribeToStepFunctionLogs: false, + suppressLowMemoryWarning: false, enableSourceCodeIntegration: true, uploadGitMetadata: true, failOnError: false, @@ -234,6 +235,7 @@ describe("getConfig", () => { subscribeToAccessLogs: true, subscribeToExecutionLogs: false, subscribeToStepFunctionLogs: false, + suppressLowMemoryWarning: false, enableSourceCodeIntegration: true, uploadGitMetadata: true, failOnError: false, @@ -275,6 +277,7 @@ describe("getConfig", () => { subscribeToAccessLogs: true, subscribeToExecutionLogs: false, subscribeToStepFunctionLogs: false, + suppressLowMemoryWarning: false, customHandler: "/src/custom-handler.handler", enableSourceCodeIntegration: true, uploadGitMetadata: true, @@ -318,6 +321,7 @@ it("disable source code integration", () => { subscribeToAccessLogs: true, subscribeToExecutionLogs: false, subscribeToStepFunctionLogs: false, + suppressLowMemoryWarning: false, enableSourceCodeIntegration: false, uploadGitMetadata: true, failOnError: false, @@ -359,6 +363,7 @@ it("disable git metadata upload", () => { subscribeToAccessLogs: true, subscribeToExecutionLogs: false, subscribeToStepFunctionLogs: false, + suppressLowMemoryWarning: false, enableSourceCodeIntegration: true, uploadGitMetadata: false, failOnError: false, @@ -2349,3 +2354,14 @@ describe("setEnvConfiguration", () => { }); }); }); + +describe("suppressLowMemoryWarning", () => { + it("defaults to false", () => { + expect(getConfig({ custom: {} } as any).suppressLowMemoryWarning).toBe(false); + }); + + it("can be set to true", () => { + const result = getConfig({ custom: { datadog: { suppressLowMemoryWarning: true } } } as any); + expect(result.suppressLowMemoryWarning).toBe(true); + }); +}); diff --git a/src/env.ts b/src/env.ts index 442094fd..be9a8189 100644 --- a/src/env.ts +++ b/src/env.ts @@ -146,6 +146,10 @@ export interface Configuration { // Only required if you are not using the Datadog Agent. llmObsAgentlessEnabled?: boolean; + + // When set to `true`, the plugin does not warn about instrumented functions with less + // than LOW_MEMORY_THRESHOLD_MB of memory. Defaults to `false`. + suppressLowMemoryWarning?: boolean; } const webpackPluginName = "serverless-webpack"; const apiKeyEnvVar = "DD_API_KEY"; @@ -213,6 +217,7 @@ export const defaultConfiguration: Configuration = { propagateUpstreamTrace: false, enableStepFunctionsTracing: false, redirectHandlers: true, + suppressLowMemoryWarning: false, }; export function setEnvConfiguration( diff --git a/src/index.spec.ts b/src/index.spec.ts index c729be22..94aaec72 100644 --- a/src/index.spec.ts +++ b/src/index.spec.ts @@ -630,6 +630,116 @@ describe("ServerlessPlugin", () => { }); }); + describe("low-memory warning", () => { + const lowMemoryWarning = (name: string, memorySize: number) => + `Warning: Function ${name} has ${memorySize} MB of memory, below the recommended minimum of 256 MB (lambda_low_memory). The Datadog Lambda Extension and tracer add memory overhead (about 69 MB for Python), which can cause out-of-memory errors and timeouts. Increase the function's memory to at least 256 MB, or set custom.datadog.suppressLowMemoryWarning to true to silence this warning.`; + + afterEach(() => { + mock.restore(); + }); + + async function runBeforePackage( + functions: Record>, + provider: Record = {}, + datadog: Record = {}, + ): Promise<{ logs: string[]; serverless: any }> { + mock({}); + const logs: string[] = []; + const serverless = { + cli: { log: (message: string) => logs.push(message) }, + getProvider: (_name: string) => awsMock(), + service: { + getServiceName: () => "dev", + provider: { region: "us-east-1", ...provider }, + functions, + custom: { datadog: { apiKey: 1234, ...datadog } }, + }, + }; + const plugin = new ServerlessPlugin(serverless, {}); + await plugin.hooks["before:package:createDeploymentArtifacts"](); + return { logs, serverless }; + } + + it("warns for a function below 256 MB and still instruments it", async () => { + const { logs, serverless } = await runBeforePackage({ + python1: { handler: "my-func.ev", runtime: "python3.12", memorySize: 128 }, + }); + expect(logs).toContain(lowMemoryWarning("python1", 128)); + expect(serverless.service.functions.python1.layers).toEqual([ + expect.stringMatching(/arn:aws:lambda:us-east-1:.*:layer:Datadog-Python312:.*/), + expect.stringMatching(/arn:aws:lambda:us-east-1:464622532012:layer:Datadog-Extension:.*/), + ]); + }); + + it("does not warn for a function with exactly 256 MB", async () => { + const { logs } = await runBeforePackage({ + python1: { handler: "my-func.ev", runtime: "python3.12", memorySize: 256 }, + }); + expect(logs.filter((log) => log.includes("lambda_low_memory"))).toEqual([]); + }); + + it("inherits provider.memorySize when the function doesn't set it", async () => { + const { logs } = await runBeforePackage( + { + python1: { handler: "my-func.ev", runtime: "python3.12" }, + python2: { handler: "my-func.ev", runtime: "python3.12", memorySize: 512 }, + }, + { memorySize: 128 }, + ); + expect(logs.filter((log) => log.includes("lambda_low_memory"))).toEqual([lowMemoryWarning("python1", 128)]); + }); + + it("does not warn when memorySize is unset (Serverless default of 1024 MB)", async () => { + const { logs } = await runBeforePackage({ + python1: { handler: "my-func.ev", runtime: "python3.12" }, + }); + expect(logs.filter((log) => log.includes("lambda_low_memory"))).toEqual([]); + }); + + it("does not warn when memorySize is not a plain number", async () => { + const { logs } = await runBeforePackage( + { + python1: { handler: "my-func.ev", runtime: "python3.12", memorySize: "${self:custom.memory}" }, + python2: { handler: "my-func.ev", runtime: "python3.12", memorySize: { Ref: "Memory" } }, + python3: { handler: "my-func.ev", runtime: "python3.12" }, + }, + { memorySize: "${param:memory}" }, + ); + expect(logs.filter((log) => log.includes("lambda_low_memory"))).toEqual([]); + }); + + it("does not warn when suppressLowMemoryWarning is true", async () => { + const { logs, serverless } = await runBeforePackage( + { python1: { handler: "my-func.ev", runtime: "python3.12", memorySize: 128 } }, + {}, + { suppressLowMemoryWarning: true }, + ); + expect(logs.filter((log) => log.includes("lambda_low_memory"))).toEqual([]); + expect(serverless.service.functions.python1.layers).toHaveLength(2); + }); + + it("does not warn for an excluded function", async () => { + const { logs } = await runBeforePackage( + { + python1: { handler: "my-func.ev", runtime: "python3.12", memorySize: 128 }, + python2: { handler: "my-func.ev", runtime: "python3.12", memorySize: 128 }, + }, + {}, + { exclude: ["python1"] }, + ); + expect(logs.filter((log) => log.includes("lambda_low_memory"))).toEqual([lowMemoryWarning("python2", 128)]); + }); + + it("does not warn when the plugin is disabled", async () => { + const { logs } = await runBeforePackage( + { python1: { handler: "my-func.ev", runtime: "python3.12", memorySize: 128 } }, + {}, + { enabled: false }, + ); + expect(logs).toEqual([]); + }); + }); + describe("validateConfiguration", () => { afterEach(() => { mock.restore(); diff --git a/src/index.ts b/src/index.ts index 0ca0dadb..d24226ef 100644 --- a/src/index.ts +++ b/src/index.ts @@ -43,6 +43,7 @@ import { applyLambdaLibraryLayers, findHandlers, FunctionInfo, + getLowMemoryWarnings, RuntimeType, getDefaultIsFIPSEnabledFlag, } from "./layer"; @@ -137,6 +138,13 @@ module.exports = class ServerlessPlugin { const defaultRuntime = this.serverless.service.provider.runtime; const handlers = findHandlers(this.serverless.service, config.exclude, defaultRuntime); + // Warn only: low-memory functions are still instrumented as before. + if (config.suppressLowMemoryWarning !== true) { + for (const warning of getLowMemoryWarnings(this.serverless.service, handlers)) { + this.logToCliOnce(`Warning: ${warning}`); + } + } + // Don't assign `provider.environment` here: without the extension nothing else creates it, and an empty one // would add an Environment block to excluded functions. (addDDEnvVars creates it when the extension is used.) const providerEnvironment = (this.serverless.service.provider as Provider).environment as diff --git a/src/layer.ts b/src/layer.ts index 6d58c122..380dd696 100644 --- a/src/layer.ts +++ b/src/layer.ts @@ -85,6 +85,47 @@ export function findHandlers(service: Service, exclude: string[], defaultRuntime ) as FunctionInfo[]; } +// Functions with less memory than this can run out of memory or time out once the Datadog +// Lambda Extension and tracer layers are added (about 69 MB of overhead for Python). +export const LOW_MEMORY_THRESHOLD_MB = 256; +export const LOW_MEMORY_REASON = "lambda_low_memory"; +// Serverless Framework v1 through v4 default `memorySize` to 1024 MB when neither the +// function nor the provider sets it. +export const SERVERLESS_DEFAULT_MEMORY_SIZE_MB = 1024; + +/** + * Returns the memory size the function is deployed with: `functions..memorySize`, then + * `provider.memorySize`, then the Serverless Framework default. Returns undefined when the + * value is not a plain number (for example, an unresolved variable or an object). + */ +export function getEffectiveMemorySize(service: Service, handler: FunctionInfo): number | undefined { + const memorySize: unknown = + handler.handler.memorySize ?? + (service.provider as unknown as { memorySize?: unknown }).memorySize ?? + SERVERLESS_DEFAULT_MEMORY_SIZE_MB; + return typeof memorySize === "number" && Number.isFinite(memorySize) ? memorySize : undefined; +} + +/** + * Returns a warning for each instrumented function with less than LOW_MEMORY_THRESHOLD_MB of memory. + * Functions with an unsupported runtime get no Datadog layers, so they are skipped. + */ +export function getLowMemoryWarnings(service: Service, handlers: FunctionInfo[]): string[] { + const warnings: string[] = []; + for (const handler of handlers) { + if (handler.type === RuntimeType.UNSUPPORTED) { + continue; + } + const memorySize = getEffectiveMemorySize(service, handler); + if (memorySize !== undefined && memorySize < LOW_MEMORY_THRESHOLD_MB) { + warnings.push( + `Function ${handler.name} has ${memorySize} MB of memory, below the recommended minimum of ${LOW_MEMORY_THRESHOLD_MB} MB (${LOW_MEMORY_REASON}). The Datadog Lambda Extension and tracer add memory overhead (about 69 MB for Python), which can cause out-of-memory errors and timeouts. Increase the function's memory to at least ${LOW_MEMORY_THRESHOLD_MB} MB, or set custom.datadog.suppressLowMemoryWarning to true to silence this warning.`, + ); + } + } + return warnings; +} + /** * Normalize the runtime in the yml to match our layers.json keys * For most runtimes the key in layers.json is the same as the string set in the From f21b8491d6edf93863ef029bc75175e7f073761f Mon Sep 17 00:00:00 2001 From: Alex Angelillo Date: Fri, 20 Nov 2026 15:40:29 -0500 Subject: [PATCH 2/3] Update README.md Co-authored-by: Alicia Thuerk --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7e8dc4ee..fe227868 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ To further configure your plugin, use the following custom parameters in your `s | `llmObsEnabled` | Toggle to enable submitting data to LLM Observability. Defaults to `false`. | | `llmObsMlApp` | The name of your LLM application, service, or project, under which all traces and spans are grouped. This helps distinguish between different applications or experiments. See [Application naming guidelines](https://docs.datadoghq.com/llm_observability/sdk/?tab=nodejs#application-naming-guidelines) for allowed characters and other constraints. To override this value for a given root span, see [Tracing multiple applications](https://docs.datadoghq.com/llm_observability/sdk/?tab=nodejs#tracing-multiple-applications). Required if `llmObsEnabled` is `true` | | `llmObsAgentlessEnabled` | Only required if you are not using the Datadog Lambda Extension, in which case this should be set to `true`. Defaults to `false`. | -| `suppressLowMemoryWarning` | The plugin prints a warning (reason `lambda_low_memory`) for each instrumented function with less than 256 MB of memory, because the Datadog Lambda Extension and tracer add memory overhead (about 69 MB for Python) that can cause out-of-memory errors and timeouts. The function's memory is `memorySize` on the function, then `provider.memorySize`, then the Serverless Framework default of 1024 MB. The function is still instrumented. Set to `true` to silence this warning. Defaults to `false`. | +| `suppressLowMemoryWarning` | When set to `true`, silences the warning the plugin prints for each instrumented function with less than 256 MB of memory (reason `lambda_low_memory`). The plugin still instruments these functions. The Datadog Lambda Extension and tracer add memory overhead (about 69 MB for Python), which can cause out-of-memory errors and timeouts. To determine a function's memory, the plugin uses the function's `memorySize`, then `provider.memorySize`, then the Serverless Framework default of 1024 MB. Defaults to `false`. | To use any of these parameters, add a `custom` > `datadog` section to your `serverless.yml` similar to this example: From afa596e3d8956388b39cd1583aa77d6cf79c1a54 Mon Sep 17 00:00:00 2001 From: Alex Angelillo Date: Fri, 20 Nov 2026 15:42:53 -0500 Subject: [PATCH 3/3] Round the memory overhead figure to about 70 MB Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- src/index.spec.ts | 2 +- src/layer.ts | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index fe227868..d4561dba 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ To further configure your plugin, use the following custom parameters in your `s | `llmObsEnabled` | Toggle to enable submitting data to LLM Observability. Defaults to `false`. | | `llmObsMlApp` | The name of your LLM application, service, or project, under which all traces and spans are grouped. This helps distinguish between different applications or experiments. See [Application naming guidelines](https://docs.datadoghq.com/llm_observability/sdk/?tab=nodejs#application-naming-guidelines) for allowed characters and other constraints. To override this value for a given root span, see [Tracing multiple applications](https://docs.datadoghq.com/llm_observability/sdk/?tab=nodejs#tracing-multiple-applications). Required if `llmObsEnabled` is `true` | | `llmObsAgentlessEnabled` | Only required if you are not using the Datadog Lambda Extension, in which case this should be set to `true`. Defaults to `false`. | -| `suppressLowMemoryWarning` | When set to `true`, silences the warning the plugin prints for each instrumented function with less than 256 MB of memory (reason `lambda_low_memory`). The plugin still instruments these functions. The Datadog Lambda Extension and tracer add memory overhead (about 69 MB for Python), which can cause out-of-memory errors and timeouts. To determine a function's memory, the plugin uses the function's `memorySize`, then `provider.memorySize`, then the Serverless Framework default of 1024 MB. Defaults to `false`. | +| `suppressLowMemoryWarning` | When set to `true`, silences the warning the plugin prints for each instrumented function with less than 256 MB of memory (reason `lambda_low_memory`). The plugin still instruments these functions. The Datadog Lambda Extension and tracer add memory overhead (about 70 MB for Python), which can cause out-of-memory errors and timeouts. To determine a function's memory, the plugin uses the function's `memorySize`, then `provider.memorySize`, then the Serverless Framework default of 1024 MB. Defaults to `false`. | To use any of these parameters, add a `custom` > `datadog` section to your `serverless.yml` similar to this example: diff --git a/src/index.spec.ts b/src/index.spec.ts index 94aaec72..f045a39f 100644 --- a/src/index.spec.ts +++ b/src/index.spec.ts @@ -632,7 +632,7 @@ describe("ServerlessPlugin", () => { describe("low-memory warning", () => { const lowMemoryWarning = (name: string, memorySize: number) => - `Warning: Function ${name} has ${memorySize} MB of memory, below the recommended minimum of 256 MB (lambda_low_memory). The Datadog Lambda Extension and tracer add memory overhead (about 69 MB for Python), which can cause out-of-memory errors and timeouts. Increase the function's memory to at least 256 MB, or set custom.datadog.suppressLowMemoryWarning to true to silence this warning.`; + `Warning: Function ${name} has ${memorySize} MB of memory, below the recommended minimum of 256 MB (lambda_low_memory). The Datadog Lambda Extension and tracer add memory overhead (about 70 MB for Python), which can cause out-of-memory errors and timeouts. Increase the function's memory to at least 256 MB, or set custom.datadog.suppressLowMemoryWarning to true to silence this warning.`; afterEach(() => { mock.restore(); diff --git a/src/layer.ts b/src/layer.ts index 380dd696..e758d8df 100644 --- a/src/layer.ts +++ b/src/layer.ts @@ -86,7 +86,7 @@ export function findHandlers(service: Service, exclude: string[], defaultRuntime } // Functions with less memory than this can run out of memory or time out once the Datadog -// Lambda Extension and tracer layers are added (about 69 MB of overhead for Python). +// Lambda Extension and tracer layers are added (about 70 MB of overhead for Python). export const LOW_MEMORY_THRESHOLD_MB = 256; export const LOW_MEMORY_REASON = "lambda_low_memory"; // Serverless Framework v1 through v4 default `memorySize` to 1024 MB when neither the @@ -119,7 +119,7 @@ export function getLowMemoryWarnings(service: Service, handlers: FunctionInfo[]) const memorySize = getEffectiveMemorySize(service, handler); if (memorySize !== undefined && memorySize < LOW_MEMORY_THRESHOLD_MB) { warnings.push( - `Function ${handler.name} has ${memorySize} MB of memory, below the recommended minimum of ${LOW_MEMORY_THRESHOLD_MB} MB (${LOW_MEMORY_REASON}). The Datadog Lambda Extension and tracer add memory overhead (about 69 MB for Python), which can cause out-of-memory errors and timeouts. Increase the function's memory to at least ${LOW_MEMORY_THRESHOLD_MB} MB, or set custom.datadog.suppressLowMemoryWarning to true to silence this warning.`, + `Function ${handler.name} has ${memorySize} MB of memory, below the recommended minimum of ${LOW_MEMORY_THRESHOLD_MB} MB (${LOW_MEMORY_REASON}). The Datadog Lambda Extension and tracer add memory overhead (about 70 MB for Python), which can cause out-of-memory errors and timeouts. Increase the function's memory to at least ${LOW_MEMORY_THRESHOLD_MB} MB, or set custom.datadog.suppressLowMemoryWarning to true to silence this warning.`, ); } }