{"id":17809,"library":"middy-profiler","title":"Middy AWS Lambda CPU Profiler","description":"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.","status":"active","version":"1.0.11","language":"javascript","source_language":"en","source_url":"https://github.com/serkan-ozal/middy-profiler","tags":["javascript","middy","serverless","aws","lambda","profiler"],"install":[{"cmd":"npm install middy-profiler","lang":"bash","label":"npm"},{"cmd":"yarn add middy-profiler","lang":"bash","label":"yarn"},{"cmd":"pnpm add middy-profiler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for Middy framework integration (version 2.0.0+).","package":"@middy/core","optional":false}],"imports":[{"note":"The primary export is a default function for creating the middleware.","wrong":"import { profiler } from 'middy-profiler';","symbol":"profiler","correct":"import profiler from 'middy-profiler';"},{"note":"CommonJS usage, directly returns the middleware function.","symbol":"profiler","correct":"const profiler = require('middy-profiler');"},{"note":"Common ESM import for the Middy core library.","wrong":"import { middy } from '@middy/core';","symbol":"middy","correct":"import middy from '@middy/core';"}],"quickstart":{"code":"import middy from '@middy/core';\nimport profiler from 'middy-profiler';\n\n// A basic AWS Lambda handler function\nconst handler = async (event, context) => {\n  console.log('Lambda invoked with event:', event);\n  // Simulate some CPU-intensive work\n  let sum = 0;\n  for (let i = 0; i < 10000000; i++) {\n    sum += Math.sqrt(i);\n  }\n  console.log('Work done, sum:', sum);\n\n  return {\n    statusCode: 200,\n    body: JSON.stringify({ message: 'Profiling complete' }),\n  };\n};\n\n// Wrap the handler with middy and apply the profiler middleware\n// Ensure MIDDY_PROFILER_S3_BUCKET_NAME env var is set or pass it via options.\nexport const profiledHandler = middy(handler).use(\n  profiler({\n    s3: {\n      bucketName: process.env.MIDDY_PROFILER_S3_BUCKET_NAME ?? 'your-profiling-bucket-name' // Mandatory\n    },\n    fileName: 'my-function-profile' // Optional custom file name\n  })\n);\n\n// Example of how to enable coldstart profiling (requires setting NODE_OPTIONS env var outside of code)\n// process.env.NODE_OPTIONS = '--require /path/to/middy-profiler/bootstrap.js';\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure `MIDDY_PROFILER_S3_BUCKET_NAME` environment variable is set or pass `s3: { bucketName: '...' }` in the profiler middleware options.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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/*\"}`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.2"},{"fix":"Upgrade your `@middy/core` package to version `2.0.0` or later by running `npm install @middy/core@^2`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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' } })`.","cause":"The `MIDDY_PROFILER_S3_BUCKET_NAME` environment variable is not set, or the `s3.bucketName` option was not passed to the `profiler()` middleware.","error":"Profiling disabled: S3 bucket name is not specified."},{"fix":"Verify that the S3 bucket specified in your configuration (environment variable or middleware options) actually exists in the correct AWS region.","cause":"The S3 bucket configured for storing profiling data either does not exist or its name is misspelled.","error":"The specified bucket does not exist (Service: S3, Status Code: 404, Request ID: [...], S3 Extended Request ID: [...])"},{"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/*`).","cause":"The AWS Lambda function's execution role lacks the necessary `s3:PutObject` permission to write profiling data to the specified S3 bucket.","error":"Access Denied (Service: S3, Status Code: 403, Request ID: [...], S3 Extended Request ID: [...])"},{"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.","cause":"This usually indicates an incorrect import for `@middy/core` or that `@middy/core` is not installed or an incompatible version is used.","error":"TypeError: middy is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}