Skip to content

Commit

Permalink
Merge pull request #262 from patmeiler/documentation-restructure
Browse files Browse the repository at this point in the history 
[Document restructure] Updated README and added Quick Start
  • Loading branch information
@alexcasalboni
alexcasalboni authored Nov 21, 2024
2 parents ea95282 + 920b0b9 commit 53bf280
Show file tree
Hide file tree
Showing 3 changed files with 115 additions and 65 deletions.
21 changes: 21 additions & 0 deletions README-DEPLOY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,27 @@ If you don't yet have a Terraform project, check out the [Terraform introduction
The Terraform modules are located in the [terraform](terraform) directory. Deployment documentation is [here](terraform/Readme.md).
## State machine configuration (at deployment time)
The CloudFormation template (used for option 1 to 4) accepts the following parameters:
| <div style="width:260px">**Parameter**</div> | Description |
|:-----------------------------------------------------------------------------------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **PowerValues**<br>type: _list of numbers_<br>default: [128,256,512,1024,1536,3008] | These power values (in MB) will be used as the default in case no `powerValues` input parameter is provided at execution time. |
| **visualizationURL**<br>type: _string_<br>default: `lambda-power-tuning.show` | The base URL for the visualization tool, you can bring your own visualization tool. |
| **totalExecutionTimeout**<br>type: _number_<br>default: `300` | The timeout in seconds applied to all functions of the state machine. |
| **lambdaResource**<br>type: _string_<br>default: `*` | The `Resource` used in IAM policies; it's `*` by default but you could restrict it to a prefix or a specific function ARN. |
| **permissionsBoundary**<br>type: _string_<br> | The ARN of a permissions boundary (policy), applied to all functions of the state machine. |
| **payloadS3Bucket**<br>type: _string_<br> | The S3 bucket name used for large payloads (>256KB); if provided, it's added to a custom managed IAM policy that grants read-only permission to the S3 bucket; more details in the [S3 payloads section](README-ADVANCED.md#user-content-s3-payloads). |
| **payloadS3Key**<br>type: _string_<br>default: `*` | The S3 object key used for large payloads (>256KB); the default value grants access to all S3 objects in the bucket specified with `payloadS3Bucket`; more details in the [S3 payloads section](README-ADVANCED.md#user-content-s3-payloads). |
| **layerSdkName**<br>type: _string_<br> | The name of the SDK layer, in case you need to customize it (optional). |
| **logGroupRetentionInDays**<br>type: _number_<br>default: `7` | The number of days to retain log events in the Lambda log groups (a week by default). |
| **securityGroupIds**<br>type: _list of SecurityGroup IDs_<br> | List of Security Groups to use in every Lambda function's VPC Configuration (optional); please note that your VPC should be configured to allow public internet access (via NAT Gateway) or include VPC Endpoints to the Lambda service. |
| **subnetIds**<br>type: _list of Subnet IDs_<br> | List of Subnets to use in every Lambda function's VPC Configuration (optional); please note that your VPC should be configured to allow public internet access (via NAT Gateway) or include VPC Endpoints to the Lambda service. |
| **stateMachineNamePrefix**<br>type: _string_<br>default: `powerTuningStateMachine` | Allows you to customize the name of the state machine. Maximum 43 characters, only alphanumeric (plus `-` and `_`). The last portion of the `AWS::StackId` will be appended to this value, so the full name will look like `powerTuningStateMachine-89549da0-a4f9-11ee-844d-12a2895ed91f`. Note: `StateMachineName` has a maximum of 80 characters and 36+1 from the `StackId` are appended, allowing 43 for a custom prefix. |

Please note that the total execution time should stay below 300 seconds (5 min), which is the default timeout. You can estimate the total execution timeout based on the average duration of your functions. For example, if your function's average execution time is 5 seconds and you haven't enabled `parallelInvocation`, you should set `totalExecutionTimeout` to at least `num * 5`: 50 seconds if `num=10`, 500 seconds if `num=100`, and so on. If you have enabled `parallelInvocation`, usually you don't need to tune the value of `totalExecutionTimeout` unless your average execution time is above 5 min. If you have set a sleep between invocations, remember to include that in your timeout calculations.
## How to execute the state machine once deployed
Expand Down
25 changes: 24 additions & 1 deletion README-EXECUTE.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,4 +52,27 @@ Click "**Start Execution**" again and the execution will start. In the next page

Once the execution has completed, you will find the execution results in the "**Output**" tab of the "**Execution Details**" section at the top of the page. The output will contain the optimal power configuration and its corresponding average cost per execution.


## State machine input (at execution time)

Each execution of the state machine will require an input where you can define the following input parameters:

| <div style="width:260px">**Parameter**</div> | Description |
|:-----------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **lambdaARN** (required)<br/>type: _string_<br/> | Unique identifier of the Lambda function you want to optimize. |
| **num** (required)<br/>type: _integer_ | The # of invocations for each power configuration (minimum 5, recommended: between 10 and 100). |
| **powerValues**<br/>type: _string or list of integers_ | The list of power values to be tested; if not provided, the default values configured at deploy-time are used; you can provide any power values between 128MB and 10,240MB. ⚠️ New AWS accounts have reduced concurrency and memory quotas (3008MB max). |
| **payload**<br/>type: _string, object, or list_ | The static payload that will be used for every invocation (object or string); when using a list, a weighted payload is expected in the shape of `[{"payload": {...}, "weight": X }, {"payload": {...}, "weight": Y }, {"payload": {...}, "weight": Z }]`, where the weights `X`, `Y`, and `Z` are treated as relative weights (not percentages); more details in the [Weighted Payloads section](README-ADVANCED.md#user-content-weighted-payloads). |
| **payloadS3**<br/>type: _string_ | An Amazon S3 object reference for large payloads (>256KB), formatted as `s3://bucket/key`; it requires read-only IAM permissions, see `payloadS3Bucket` and `payloadS3Key` below and find more details in the [S3 payloads section](README-ADVANCED.md#user-content-s3-payloads). |
| **parallelInvocation**<br/>type: _boolean_<br/>default: `false` | If true, all the invocations will run in parallel. ⚠️ Note: depending on the value of `num`, you might experience throttling. |
| **strategy**<br/>type: _string_<br/>default: `"cost"` | It can be `"cost"` or `"speed"` or `"balanced"`; if you use `"cost"` the state machine will suggest the cheapest option (disregarding its performance), while if you use `"speed"` the state machine will suggest the fastest option (disregarding its cost). When using `"balanced"` the state machine will choose a compromise between `"cost"` and `"speed"` according to the parameter `"balancedWeight"`. |
| **balancedWeight**<br/>type: _number_<br/>default: `0.5` | Parameter that represents the trade-off between cost and speed. Value is between 0 and 1, where 0.0 is equivalent to `"speed"` strategy, 1.0 is equivalent to `"cost"` strategy. |
| **autoOptimize**<br/>type: _boolean_<br/>default: `false` | If true, the state machine will apply the optimal configuration at the end of its execution. |
| **autoOptimizeAlias**<br/>type: _string_ | If provided - and only if `autoOptimize` is true, the state machine will create or update this alias with the new optimal power value. |
| **dryRun**<br/>type: _boolean_<br/>default: `false` | If true, the state machine will invoke the input function only once and disable every functionality related to logs analysis, auto-tuning, and visualization; this is intended for testing purposes, for example to verify that IAM permissions are set up correctly. |
| **preProcessorARN**<br/>type: _string_ | The ARN of a Lambda function that will be invoked before every invocation of `lambdaARN`; more details in the [Pre/Post-processing functions section](README-ADVANCED.md#user-content-prepost-processing-functions). |
| **postProcessorARN**<br/>type: _string_ | The ARN of a Lambda function that will be invoked after every invocation of `lambdaARN`; more details in the [Pre/Post-processing functions section](README-ADVANCED.md#user-content-prepost-processing-functions). |
| **discardTopBottom**<br/>type: _number_<br/>default: `0.2` | By default, the state machine will discard the top/bottom 20% of "outlier invocations" (the fastest and slowest) to filter out the effects of cold starts and remove any bias from overall averages. You can customize this parameter by providing a value between 0 and 0.4, where 0 means no results are discarded and 0.4 means 40% of the top/bottom results are discarded (i.e. only 20% of the results are considered). |
| **sleepBetweenRunsMs**<br/>type: _integer_ | If provided, the time in milliseconds that the tuner will sleep/wait after invoking your function, but before carrying out the Post-Processing step, should that be provided. This could be used if you have aggressive downstream rate limits you need to respect. By default this will be set to 0 and the function won't sleep between invocations. This has no effect if running the invocations in parallel. |
| **disablePayloadLogs**<br/>type: _boolean_<br/>default: `false` | If true, suppresses `payload` from error messages and logs. If `preProcessorARN` is provided, this also suppresses the output payload of the pre-processor. |
| **includeOutputResults**<br/>type: _boolean_<br/>default: `false` | If true, the average cost and average duration for every power value configuration will be included in the state machine output. |
| **onlyColdStarts**<br/>type: _boolean_<br/>default: `false` | If true, the tool will force all invocations to be cold starts. The initialization phase will be considerably slower as `num` versions/aliases need to be created for each power value.
Loading

0 comments on commit 53bf280

Please sign in to comment.