Middy AWS Lambda CPU Profiler

1.0.11 verified Thu Apr 23 auth: no javascript

middy-profiler is an AWS Lambda middleware designed to capture CPU profiling data for Node.js functions, integrating seamlessly with the Middy framework. As of its current stable version 1.0.11, it enables developers to identify performance bottlenecks within their serverless functions by saving detailed CPU profiles to a specified AWS S3 bucket. These `.cpuprofile` files can then be analyzed using standard tools like Chrome DevTools for in-depth performance analysis. The package maintains a consistent release cadence with minor updates addressing features like conditional reporting, start delays, and coldstart profiling. Key differentiators include its tight integration with Middy, a standalone usage option, and the ability to profile module initialization during cold starts, which is crucial for optimizing initial function execution. Proper configuration of an S3 bucket and corresponding Lambda permissions are mandatory for its operation. It requires `@middy/core` version 2.0.0 or higher.

Common errors

error Profiling disabled: S3 bucket name is not specified. ↓

cause The `MIDDY_PROFILER_S3_BUCKET_NAME` environment variable is not set, or the `s3.bucketName` option was not passed to the `profiler()` middleware.

fix

Set the MIDDY_PROFILER_S3_BUCKET_NAME environment variable in your Lambda configuration or provide the bucket name directly in the middleware options: profiler({ s3: { bucketName: 'your-bucket' } }).

error The specified bucket does not exist (Service: S3, Status Code: 404, Request ID: [...], S3 Extended Request ID: [...]) ↓

cause The S3 bucket configured for storing profiling data either does not exist or its name is misspelled.

fix

Verify that the S3 bucket specified in your configuration (environment variable or middleware options) actually exists in the correct AWS region.

error Access Denied (Service: S3, Status Code: 403, Request ID: [...], S3 Extended Request ID: [...]) ↓

cause The AWS Lambda function's execution role lacks the necessary `s3:PutObject` permission to write profiling data to the specified S3 bucket.

fix

Grant the s3:PutObject permission to your Lambda function's IAM role for the target S3 bucket. Ensure the resource ARN matches your bucket and key prefix (e.g., arn:aws:s3:::your-bucket-name/*).

error TypeError: middy is not a function ↓

cause This usually indicates an incorrect import for `@middy/core` or that `@middy/core` is not installed or an incompatible version is used.

fix

Ensure @middy/core is installed (npm install @middy/core@^2) and imported correctly: import middy from '@middy/core'; for ESM or const middy = require('@middy/core'); for CommonJS.

Warnings

gotcha The S3 bucket name for storing CPU profiling data is a mandatory configuration. If not specified via environment variable (`MIDDY_PROFILER_S3_BUCKET_NAME`) or middleware options, profiling will be silently disabled. ↓

fix Ensure `MIDDY_PROFILER_S3_BUCKET_NAME` environment variable is set or pass `s3: { bucketName: '...' }` in the profiler middleware options.

gotcha Your AWS Lambda execution role must have sufficient S3 permissions (`s3:PutObject`) to write to the specified profiling bucket. Lack of permissions will result in failed profile uploads. ↓

fix Update the AWS Lambda function's IAM role to include `s3:PutObject` permission for the target S3 bucket. Example policy: `{"Effect": "Allow", "Action": ["s3:PutObject"], "Resource": "arn:aws:s3:::your-bucket-name/*"}`.

gotcha To profile the module initialization phase (coldstart), you must configure the `NODE_OPTIONS` environment variable with the `bootstrap.js` file provided by `middy-profiler`. Standard middleware application only profiles from the request start. ↓

fix Set `NODE_OPTIONS` in your Lambda function's environment variables to include `--require /path/to/middy-profiler/bootstrap.js`. This path is typically derived from the Lambda layer or node_modules path.

gotcha This package requires `@middy/core` version `2.0.0` or higher as a peer dependency. Using an older version of Middy may lead to compatibility issues or errors. ↓

fix Upgrade your `@middy/core` package to version `2.0.0` or later by running `npm install @middy/core@^2`.

Install

npm install middy-profiler

yarn add middy-profiler

pnpm add middy-profiler

Imports

profiler
wrong
```
import { profiler } from 'middy-profiler';
```
correct
```
import profiler from 'middy-profiler';
```
The primary export is a default function for creating the middleware.
profiler
```
const profiler = require('middy-profiler');
```
CommonJS usage, directly returns the middleware function.

middy

wrong

import { middy } from '@middy/core';

correct

import middy from '@middy/core';

Common ESM import for the Middy core library.

Quickstart

Demonstrates how to integrate middy-profiler into an AWS Lambda handler using ESM, configure the S3 bucket for profile storage, and apply the middleware to an existing function.

import middy from '@middy/core';
import profiler from 'middy-profiler';

// A basic AWS Lambda handler function
const handler = async (event, context) => {
  console.log('Lambda invoked with event:', event);
  // Simulate some CPU-intensive work
  let sum = 0;
  for (let i = 0; i < 10000000; i++) {
    sum += Math.sqrt(i);
  }
  console.log('Work done, sum:', sum);

  return {
    statusCode: 200,
    body: JSON.stringify({ message: 'Profiling complete' }),
  };
};

// Wrap the handler with middy and apply the profiler middleware
// Ensure MIDDY_PROFILER_S3_BUCKET_NAME env var is set or pass it via options.
export const profiledHandler = middy(handler).use(
  profiler({
    s3: {
      bucketName: process.env.MIDDY_PROFILER_S3_BUCKET_NAME ?? 'your-profiling-bucket-name' // Mandatory
    },
    fileName: 'my-function-profile' // Optional custom file name
  })
);

// Example of how to enable coldstart profiling (requires setting NODE_OPTIONS env var outside of code)
// process.env.NODE_OPTIONS = '--require /path/to/middy-profiler/bootstrap.js';