# AWS Lambda Power Tuning: a Step Functions state machine that measures your memory curve

> It runs your own Lambda function at a range of memory settings, reads the logs, and hands back a chart of cost against duration, so the memory setting becomes a measurement rather than a guess.

**alexcasalboni/aws-lambda-power-tuning** — AWS Lambda Power Tuning is an open-source tool that can help you visualize and fine-tune the memory/power configuration of Lambda functions. It runs in your own AWS account - powered by AWS Step Functions - and it supports three optimization strategies: cost, speed, and balanced.

- Repository: https://github.com/alexcasalboni/aws-lambda-power-tuning
- Stars: 6,077 · Forks: 415
- Language: JavaScript
- License: Apache-2.0
- Published: 2026-10-06 · Updated: 2026-10-06 · Language: en
- Canonical page: https://hysenlabs.com/projects/alexcasalboni-aws-lambda-power-tuning

## The problem is that memory doubles as CPU on Lambda

On AWS Lambda the memory setting is not just a memory limit. It is how much CPU the function gets, which means it changes execution time, and because price is charged per GB-second, changing it changes cost as well. The two move in different directions for different workloads, and that is the trap. Too little memory and a compute-bound function runs slowly and cheaply; too much and it runs quickly at a price that may exceed the saving.

AWS Lambda Power Tuning is a state machine powered by AWS Step Functions that resolves this by measurement rather than intuition. You hand it a Lambda function ARN and a list of power configurations, and it invokes that function at each one, from 128MB up to 10GB, with the values you choose. It then analyses all the execution logs and suggests the configuration that minimises cost or maximises performance.

The README is clear that this runs in your own AWS account and that the tool is language agnostic, so it works on any Lambda function you can invoke rather than only on Node or Python. It describes three optimisation strategies, cost, speed and balanced, so the question you are asking it is parameterised rather than hard-coded.

## The output is a chart plus a recommended value

The state machine returns a JSON object where `results.power` is the recommended memory value, `results.cost` is the average cost per invocation at that value, and `results.duration` is the average duration per invocation. Nested under `stateMachine` are the execution cost of the tuning run itself, the Lambda cost, and a `visualization` field holding a URL in the form `https://lambda-power-tuning.show/#<encoded_data>`. A `stats` array carries `averagePrice`, `averageDuration` and `value` for every configuration tried.

The chart is the reason to bother, and the README walks through two real shapes it can take. For CPU-intensive functions, execution time drops from 35s at 128MB to under 3s at 1.5GB while the function also gets 14% cheaper to run. For a second shape, time falls from 2.4s at 128MB to 300ms at 1GB at the very same average cost. Both are cases where guessing wrong was expensive, and neither could be derived from reading the function.

The encoded-URL approach deserves a note. Nothing needs to be hosted for the visualisation to work, which is why a tool that runs entirely inside your account can still hand you a shareable result. What lands in that URL is your own measurements, so treat it as sensitive if the function handles anything private.

## Deploying with SAM, where Docker is the actual requirement

The README says there are five deployment options using infrastructure as code, and the quick start uses the AWS SAM CLI, with `README-DEPLOY.md` covering the rest. The prerequisite that matters is Docker, because `sam build -u` builds inside a container image that approximates your function's runtime.

The sequence is short. Configure credentials, clone, build, deploy guided:

```bash
$ aws configure
$ git clone https://github.com/alexcasalboni/aws-lambda-power-tuning.git
$ cd ./aws-lambda-power-tuning
$ sam build -u
$ sam deploy -g
```

A successful build prints `Build Succeeded` and a successful deploy prints `Successfully created/updated stack`. The guided deploy asks for a stack name and a region and writes the answers to `samconfig.toml` for reuse, which is worth knowing because it means a later redeploy after a `git pull` is a single command.

Teardown is equally short:

```bash
sam delete
```

You answer `Y` at the prompts and the stack goes away. Between those two steps, `sam build -u` reads your SAM template for the functions and layers in this project, so `template.yml` is the file that actually defines what gets created.

## The execution input is four parameters

Running the state machine is separate from deploying it, and the README points at `README-EXECUTE.md` for the full list of execution parameters. The quick start runs it from the CLI using a script in the `scripts` directory, and the minimal input looks like this:

```json
+{
    "lambdaARN": "your-lambda-function-arn",
    "powerValues": [128, 256, 512, 1024],
    "num": 50,
    "payload": {}
}
```

`scripts/sample-execution-input.json` is the checked-in version of that shape, so you can copy it and edit it rather than writing JSON by hand. `powerValues` is your memory ladder, and choosing it is the main decision you make: four values is a quick run, and a wider ladder costs proportionally more invocations.

`num` is the invocation count per configuration, which is the statistical floor on the whole exercise. Too few and cold starts and network jitter dominate; the README notes that the tool supports parallel execution to generate results in just a few seconds, which is how you afford a large `num`. `payload` is what gets sent to your function, so a tuning run that passes an empty object tests a code path your production traffic never takes.

The README also notes the state machine supports cross-region invocations, which matters when your function is not deployed in the region you are running the tool from.

## Where the project lives in the repository, and what it costs to run

The tree is informative. `statemachine/` holds the state machine definition, `lambda/` the functions it invokes, `layer-sdk/` the shared library layer, `cdk/` an alternative infrastructure path, and `template.yml` the SAM template the build reads. Alongside the main `README.md` sit focused documents: `README-ADVANCED.md`, `README-DEPLOY.md`, `README-EXECUTE.md`, `README-IAM-PERMISSIONS.md` and `README-SAR.md`, the last covering the serverless application repository. `test/` and `.mocharc.js` are the test setup.

`package.json` gives version 4.4.0 and three scripts: `npm run lint` through eslint with `eslint-config-strongloop`, `npm test` through mocha, and `npm run coverage` through c8 emitting lcov and cobertura. The AWS SDK clients in devDependencies are `@aws-sdk/client-lambda` and `@aws-sdk/client-s3`, which tells you the two services the local test and build path touches.

The cost warning belongs here rather than at the end. The README states plainly that the input function will be executed in your AWS account and perform real HTTP requests, SDK calls and cold starts. A tuning run is therefore a load test with a bill attached, and the `stateMachine.executionCost` and `stateMachine.lambdaCost` fields in the output exist so you can see what that run cost. Tuning a function that writes to a database or calls a payment API fifty times per memory value is a design decision, not an oversight.

## How it compares to guessing, and to the managed alternatives

The alternative most teams actually use is reading the AWS documentation about memory and CPU, then picking 1024MB because that is the tutorial value. That works when a function is idle most of the time and fails when it is not. The chart this tool produces replaces that with a curve for your code, which is the real difference in approach: measurement on production-shaped payloads rather than general guidance about how Lambda allocates vCPU.

The other comparison is with power tuning services offered for other platforms, which cannot touch a Lambda ARN in your account without the same invocation permission this state machine already has. Its dependence on Step Functions is also a constraint worth naming. Each configuration is a separate branch of execution, and a very wide ladder across many regions adds state machine cost and timeout risk that the README's fast parallel execution note partly offsets but does not remove.

For the reading order, `README-DEPLOY.md` first if you deploy, `README-EXECUTE.md` second if you tune, and `README-IAM-PERMISSIONS.md` before you grant anything, since the tool needs permission to invoke and configure the function under test. Licence is Apache 2.0 (`LICENSE.txt`), the repository is not archived, and the last push was on 2026-09-13. There are no GitHub releases attached, so version tracking runs through `CHANGELOG.md` and the version field in `package.json`.

## Conclusion

AWS Lambda Power Tuning answers a question no amount of reading will: which memory value makes your particular function cheaper or faster, measured on your real payloads. It earns its place when you own the account, control the source, and can accept that a tuning run costs real invocations at every step of the memory ladder. Skip it if the function calls something you do not want executed fifty times, since the tool deliberately runs the function for real. The repository is not archived and the last push was on 2026-09-13, with version 4.4.0 in `package.json`, and the README notes there are no GitHub releases, so `CHANGELOG.md` is where version history lives. Deploy with SAM first, run `scripts/execute.sh` once with a narrow `powerValues` list, and read the visualization URL in the output before automating it.

## FAQ

### How do I make an AWS Lambda function run faster?

On Lambda, memory also determines CPU, so raising the memory setting often cuts execution time. AWS Lambda Power Tuning measures this for your function by invoking it at each value in `powerValues` and charting duration against cost. The README's example goes from 35s at 128MB to under 3s at 1.5GB for a CPU-intensive function, while getting cheaper.

### What does a Lambda Power Tuning run cost?

The state machine reports what the run itself cost under `stateMachine.executionCost` and what the invocations cost under `stateMachine.lambdaCost`, alongside the recommended configuration's `cost` and `duration` per invocation. Cost scales with how many memory values you list in `powerValues` and how many invocations you set in `num`, because every combination runs your real function.

### Does running the tuner have side effects on my function?

Yes, and the README says so directly: the input function will be executed in your AWS account and perform real HTTP requests, SDK calls and cold starts. `num` defaults to repeated invocations per memory value in the sample input, so a function with side effects will repeat them. Point the `payload` field at realistic data and treat the first run as a controlled experiment.

## Sources

- [alexcasalboni/aws-lambda-power-tuning on GitHub](https://github.com/alexcasalboni/aws-lambda-power-tuning)
- [Issues](https://github.com/alexcasalboni/aws-lambda-power-tuning/issues)
- [License: Apache-2.0](https://github.com/alexcasalboni/aws-lambda-power-tuning/blob/master/LICENSE)
- [README](https://github.com/alexcasalboni/aws-lambda-power-tuning/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/alexcasalboni-aws-lambda-power-tuning