Registry / aws / middy-profiler

middy-profiler

library1.0.11jsnpmunverified

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.

aws observability

npm install middy-profiler

github ↗package ↗

INSTALL

IMPORT

SIG · MIDDY-PROFILER

middy-profiler

awsjavascriptv1.0.11

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

profiler

✓ import profiler from 'middy-profiler';

✗ 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

✓ import middy from '@middy/core';

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

Common ESM import for the Middy core library.

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';

Debug

Known issues

gotchaThe 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.

affects: >=1.0.0

gotchaYour 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/*"}`.

affects: >=1.0.0

gotchaTo 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.

affects: >=1.0.2

gotchaThis 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`.

affects: >=1.0.0

Errors

Common errors & fixes

Profiling disabled: S3 bucket name is not specified.

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' } })`.

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

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.

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

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/*`).

TypeError: middy is not a function

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.

Upgrade

Version history

1.0.11latest on npm

Audit

Dependencies

@middy/corerequiredRequired as a peer dependency for Middy framework integration (version 2.0.0+).

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/serkan-ozal/middy-profiler ↗

packagehttps://www.npmjs.com/package/middy-profiler ↗