🐛 Debug your Lambda Functions written in Go, and generate sample payloads for 50+ events

This release of SAM CLI makes it even easier to test and debug your serverless applications locally. There are two big features in this release:

1. Go Debugging: You can now use Delve to debug your Go Functions! Get started here: Debugging Go functions. Huge shout out to @austinlparker for this contribution!
2. Sample event generation: Previously, you could generate sample event payloads from S3, Kinesis Streams, DynamoDB, CloudWatch Scheduled Events, API Gateway, and SNS. Now, you can generate and customize sample payloads from 50+ events (including those from CloudFront, CloudFormation, Step Functions, and Alexa). You can also generate different types of events from each service - so, in addition to S3/Put, you can also generate sample payloads for S3/Delete.

BREAKING CHANGE: Because we support multiple event types from each service, the syntax of the generate-command is now different.

For example:
sam local generate-event s3

Has become
sam local generate-event s3 [put/delete]

Changelog:

feat(debugging): Fixing issues around debugging Golang functions. #565
fix(init): Improve current init samples around docs and fixes #558
refactor(init): renamed handler for camel case, moved callback call up #586
chore: aws-lambda-java-core 1.1.0 -> 1.2.0 for java sam init #578
feat(validate): Add profile and region options #582
fix(start-lambda): Remove Content-Type Header check #594
fix: Fix stringifying λ environment variables when using Python2 #579
feat(generate-event): Added support for 50+ events #612
feat(invoke): Add region parameter to all invoke related commands #608
chore: Update JVM size params to match docker-lambda #615
feat(invoke): Invoke Function Without Parameters through --no-event #604
Many many doc updates!

New features to simplify automated testing and troubleshooting of your serverless applications 💯

What is new in 🐿?

This release has two exciting features that make it even easier to programmatically test and troubleshoot your serverless applications. Here is the TL;DR:

1. Run your automated tests in a local, Lambda-like environment using the AWS SDKs
2. Troubleshoot your Lambda functions using the sam logs command to fetch, tail & filter your function logs.

Upgrade now to v0.5.0

pip install --upgrade aws-sam-cli

Run automated tests in a local, lambda-like environment

Previously, you could use the sam local invoke command to run your Lambda functions locally and manually test your code. With this release, SAM CLI makes it easier to author automated integration tests by letting you run tests against local Lambda functions before deploying to the cloud. The new sam local start-lambda command starts a local endpoint that emulates the AWS Lambda service’s invoke endpoint, and you can invoke it from your automated tests. Because this endpoint emulates the Lambda service's invoke endpoint, you can write tests once and run them (without any modifications) against the local Lambda function or against a deployed Lambda function. You can also run the same tests against a deployed SAM stack in your CI/CD pipeline.

Here is how this works:

1. Start the Local Lambda Endpoint
Start the local Lambda endpoint by running the following command in the directory that contains your AWS SAM template:

sam local start-lambda

This command starts a local endpoint at http://127.0.0.1:3001 that emulates the AWS Lambda service, and you can run your automated tests against this local Lambda endpoint. When you send an invoke to this endpoint using the AWS CLI or SDK, it will locally execute the Lambda function specified in the request and return a response.

2. Run integration test against local Lambda endpoint
In your integration test, you can use AWS SDK to invoke your Lambda function with test data, wait for response, and assert that the response what you expect. To run the integration test locally, you should configure AWS SDK to send Lambda Invoke API call to local Lambda endpoint started in previous step.

Here is an Python example (AWS SDK for other languages have similar configurations):

import boto3

# Set "running_locally" flag if you are running the integration test locally
if running_locally:

    # Create Lambda SDK client to connect to appropriate Lambda endpoint
    lambda_client = boto3.client('lambda',
                                 endpoint_url="http://127.0.0.1:3001",
                                 use_ssl=False,
                                 verify=False,
                                 config=Config(signature_version=UNSIGNED,
                                               read_timeout=0,
                                               retries={'max_attempts': 0}))
else:
    lambda_client = boto3.client('lambda')
                                        

# Invoke your Lambda function as you normally usually do. The function will run 
# locally if it is configured to do so
response = lambda_client.invoke(FunctionName="HelloWorldFunction")

# Verify the response 
assert response == "Hello World"

This code can run without modifications against a Lambda function which is deployed. To do so, set the running_locally flag to False . This will setup AWS SDK to connect to AWS Lambda service on the cloud.

Fetch, tail, and filter your function logs using the new sam logs command

To simplify troubleshooting, we added a new command called sam logs to SAM CLI. sam logs lets you fetch logs generated by your Lambda function from the command line. In addition to printing the logs on the terminal, this command has several nifty features to help you quickly find the bug. Note: This command works for all AWS Lambda functions; not just the ones you deploy using SAM.

Basic Usage: Using CloudFormation Stack
When your function is a part of a CloudFormation stack, you can fetch logs using the function's LogicalID:

sam logs -n HelloWorldFunction --stack-name mystack

Basic Usage: Using Lambda Function name
Or, you can fetch logs using the function's name

sam logs -n mystack-HelloWorldFunction-1FJ8PD

Tail Logs
Add --tail option to wait for new logs and see them as they arrive. This is very handy during deployment or when troubleshooting a production issue.

sam logs -n HelloWorldFunction --stack-name mystack --tail

View logs for specific time range
You can view logs for specific time range using the -s and -e options

sam logs -n HelloWorldFunction --stack-name mystack -s '10min ago' -e '2min ago'

Filter Logs
Use the --filter option to quickly find logs that match terms, phrases or values in your log events

sam logs -n HelloWorldFunction --stack-name mystack --filter "error"

In the output, SAM CLI will underline all occurrences of the word “error” so you can easily locate the filter keyword within the log output.

Error Highlighting
When your Lambda function crashes or times out, SAM CLI will highlight the timeout message in red. This will help you easily locate specific executions that are timing out within a giant stream of log output.

JSON pretty printing
If your log messages print JSON strings, SAM CLI will automatically pretty print the JSON to help you visually parse and understand the JSON.

More features & Bug fixes

• Support for running dotnetcore2.1 Lambda functions locally (#545)
• Support for long running Lambda functions & debugging sessions. Previously SAM CLI's socket connection to the Docker container will break when session lasted > 60 seconds (#422)
• Fixing the bug where SAM CLI didn't work when arbitrary proxy path names (#505)

Thanks to the amazing community for contributing features, reporting bugs, and helping out with pull requests. You are awesome 🔥

Version 0.4.0 with Python3.6 Support

This release captures another milestone with Python3.6 being fully supported. We have also captured numerous bug/regressions fixes since version 0.3.0. See Changelog below for more details.

CHANGELOG

Tell Flask we are running the service in main (#491)
Proper setting of permissions for the tempdir on posix systems. (#485)
add version field to schedule event generator (#471)
Prevent form data from being consumed by Flask (#419)
Preserve file permissions when decompressing a zip file (#464)
Python3 support (#446)
Options requests not invoking Local Lambda (#468)
Update Flask version to 1.0.2 (#459)
Value of QueryString in the API Event should be a string (#405)
download a swagger file form a given S3 location (#444)
Do not add DefinitionUri when Definitionbody Property is given (#447)
sam init Dotnet templates to use Cake for builds (#401)
Allow for case insensitive header names (#398)

SAM CLI Refresh 🎉: `sam init`, Better validation, Tons of bug fixes, and 🐍

What's new in 🐿?

This release is an important milestone - New command to get started with SAM apps, full fidelity SAM Template validation, tons of bug fixes, and greatly improved stability. Oh did I mention, we rewrote the entire CLI from the ground up?! Yes, in 🐍. With this refresh, SAM CLI uses the recently open sourced transform, enabling you leverage any new SAM functionality immediately after release.

Features

New Command: sam init

sam init is a new command that lets you quickly get started with a SAM app in any runtime of your choice. Just install the CLI and type sam init to create a new "Hello World" SAM app that includes everything (directory structure, tests, SAM template, instructions) you need to get started with serverless and eventually grow into a production scale application.

The cool part is, you can use custom templates to initialize a SAM app. For example, you could create a boilerplate SAM app specific for your organization and publish to a private GitHub repo. Others in your organization can run sam init --location gh:your-org/your-repo to initialize an app. Applications initialized using sam init can be customized to use a different project name, Lambda runtime or even include/exclude various functionalities. Check out the sam init documentation for more information.

Full Fidelity SAM Validation

SAM CLI now provides full-fidelity validation of SAM templates because it uses the recently open-sourced SAM implementation. A template that passes sam validate command locally will pass the validation when deployed through AWS CloudFormation.

SAM Local CLI → SAM CLI

If you didn't already notice, we have started calling this tool "SAM CLI" instead of "SAM Local CLI". This is a non-functional change we are making to better align the tool with its purpose - simplify the process of creating, deploying and maintaining serverless apps using the command line.

Installation Instructions

We now support a PIP-based installation method. To install the new SAM CLI, use the following

# Uninstall the old CLI if you had originally installed
npm uninstall -g aws-sam-local

# Install the new CLI through PIP
pip install --user aws-sam-cli

Go → Python

With this release, we have rewritten SAM CLI in Python to use the open-sourced AWS SAM implementation. As a user, you should notice no difference but as a contributor to the CLI, you would have to adjust your development workflow. We have a detailed DEVELOPMENT_GUIDE.rst to help you quickly ramp up. Read the DESIGN.rst for more details on design rationale and decisions.

Changes to CloudFormation intrinsic functions support

There are two notable changes regarding how intrinsic functions are handled within the CLI:

1. If you use an Inline Swagger definition (in DefinitionBody property) property and use Fn::Join to construct the Lambda Integration ARN in the x-amazon-apigateway-integration section, you would have to convert this to Fn::Sub to work with SAM CLI as of this release. You can easily convert Fn::Join to Fn::Sub without any loss of functionality. For example:

A Fn::Join usage like this:
{
"Fn::Join": ["", ["arn:aws:apigateway:", {"Ref": "AWS::Region"}, ":lambda:path/2015-03-31/functions/", {"Fn::GetAtt": ["MyFunction", "Arn"]}, "/invocations"]]
}

Can be converted to:
{
"Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${MyFunction.Arn}/invocations"
}

2. If you use CloudFormation parameters with default values to reference a Lambda Function's Timeout or Runtime properties, you now need to specify the values of these in the template. If you are using template parameters to standardize the value of Runtime or Timeout across all your functions, you use Globals to specify the value once and have it applied to all your functions.

Parameters:
  NodeRuntime:
    Default: nodejs6.10

Function1:
  Type: AWS::Serverless::Function
  Properties:
    Runtime: !Ref NodeRuntime
    ...
```yaml

You can convert it to:
```yaml
Globals:
  Function:
    # All your functions will get nodejs6.10 runtime
    Runtime: nodejs6.10

Function1:
  Type: AWS::Serverless::Function
  Properties:
    ...

Bug Fixes

• Full fidelity SAM template validation #342
• Globals support #234 and #226
• Value of APIGW Path property on proxy response is now correct #244
• NPM Installation issues #263
• Empty values in Api Event are 'null' instead of empty map/lists #338 and #340
• Content-Type of application/json is always added to headers #329 and #325 and #361
• Full featured YAML support for parsing complex intrinsic functions like !Ref, !GetAtt without failing in template parsing - #342
• Parity with credential resolutions mechanisms supported by AWS CLI since SAM CLI now uses boto3 #372
• Better support for ANY method #289
• Encode JSON output from generate-event #214
• Works with Chalice out-of-box #141 (comment)
• Compatibility with API Gateway Binary Media Types implementation #312
• Relative paths in CodeUri get resolved with respect to template path #279 #170
• Make multiple invokes in parallel #301 (comment)
• Support AWS::Include to inline a Swagger file

v0.2.11

This is a bug fix release. It fixes a bug due to which Node6 debugging was broken for the "legacy" protocol, and Node8 debugging didn't work altogether.

Changelog

a04b791 Fix node debugger protocol (#358)

---

Automated with GoReleaser
Built with go version go1.8.3 linux/amd64

Supports Nodejs 8.10

This release adds supports for Nodejs 8.10 and fixes a minor issue with compatibility with API Gateway X-Forwarded-For headers

Update to latest version

npm update -g aws-sam-local

Big thanks @mhart for adding Node 8.10 container and sending a pull request!

Changelog

290b208 Merge pull request #339 from SAPessi/develop
c9bdb4b Merge branch 'develop' into develop
2844be1 Merge pull request #344 from mhart/add-nodejs.810
ee1789f Merge branch 'develop' into add-nodejs.810
520fd02 Merge pull request #345 from mhart/update-debug-flags
e33c658 Update debug flags to match latest on live Lambda
af5ad08 Add support for the Node.js 8.10 Runtime
0aeacd7 Added Forward headers similar to API Gateway's. Helps address aws/serverless-java-container#138
ffcd2e5 Adding standard files (#335)

---

Automated with GoReleaser
Built with go version go1.8.3 linux/amd64

v0.2.9

Changelog

290b208 Merge pull request #339 from SAPessi/develop
c9bdb4b Merge branch 'develop' into develop
2844be1 Merge pull request #344 from mhart/add-nodejs.810
ee1789f Merge branch 'develop' into add-nodejs.810
520fd02 Merge pull request #345 from mhart/update-debug-flags
e33c658 Update debug flags to match latest on live Lambda
af5ad08 Add support for the Node.js 8.10 Runtime
0aeacd7 Added Forward headers similar to API Gateway's. Helps address aws/serverless-java-container#138
ffcd2e5 Adding standard files (#335)

---

Automated with GoReleaser
Built with go version go1.8.3 linux/amd64

v0.2.8

What's new in 🐿?

Fixed a bug introduced in 0.2.7 due to which debugging did not work.

Update to latest version

npm update -g aws-sam-local

Changelog

629e627 Handle the case of empty debug arguments. Fixes #314 (#316)
64cd99d Add Python3.6 to debug overrides section (#315)
2c3cb7c Merge pull request #285 from kintalapps/develop
892a36e Merge branch 'develop' into develop
9b1584f Update README.md
7b0c3ac Merge branch 'develop' into develop
3c6b9ee Merge branch 'develop' into develop
08b6a9f Update runtime.go
489862a Update runtime.go
6c65824 Update runtime.go

---

Automated with GoReleaser
Built with go version go1.8.3 linux/amd64

v0.2.7

What's new in 🐿?

Dotnetcore2.0 support!

A big thanks for @mhart for building the DotnetCore2.0 Docker container

Several other bug fixes and improvement. Thanks to the amazing community of contributors who had found bugs, sent pull requests, and in general, use this tool ❤️

Update to latest version

npm update -g aws-sam-local

Changelog

453c34a Allow debugger args to be passed to via environment variable (#307)
89ed4e3 Merge pull request #228 from TatchNicolas/hotfix-howto
4e35dc4 Merge branch 'develop' into hotfix-howto
acaae37 Merge pull request #265 from tgfjt/patch-1
c3cbe60 Merge branch 'develop' into patch-1
7f7ba7e Merge pull request #313 from SAPessi/develop
26f373b Merge branch 'develop' into develop
c37ddc5 Merge pull request #241 from deddu/develop
9e7e9c6 Merge branch 'develop' into develop
7aab176 Merge pull request #246 from danielwhatmuff/develop
1e767fa Merge branch 'develop' into develop
edd30f8 Merge pull request #215 from wtbgas/patch-1
7494e8e Merge branch 'develop' into patch-1
d8f7568 Merge pull request #256 from BeardedSteve/develop
b2e2e59 Merge branch 'develop' into develop
f700f68 Merge pull request #235 from frob/patch-1
cf94e9b Merge branch 'develop' into patch-1
2c7cf78 Merge pull request #250 from shinichy/develop
04d200e Merge branch 'develop' into develop
2b3813b Merge pull request #218 from ollyjshaw/document_validate
4d22ec4 Merge branch 'develop' into document_validate
5fc9da3 Merge pull request #273 from awslabs/upstreamDevelop
14e33d6 Merge branch 'develop' into upstreamDevelop
5a9b704 Merge pull request #309 from crx/readme-swagger-inline
15002a3 Merge branch 'develop' into readme-swagger-inline
5fd075c Merge pull request #311 from mhart/add-dotnetcore2.0
e25ff0c Addressing Swagger YAML issue reported in #275.
bf81186 Merge branch 'develop' into develop
9f9ba56 Add .NET Core 2.0 support
84f9e82 Update README to mark inline Swagger as supported
aa5bddc Merge remote-tracking branch 'upstream/develop' into develop
7ed321a Merge pull request #288 from teknogeek0/teknogeek0-upgrade-command
541fcc1 Readme.md removing space
4611fd7 update README.md to add upgrade instructions per CLI's nag
9746025 Create a new event in mount.go and pass it to Handler
2293b5d Check if body is not a valid utf8 string before encoding it to base64.
2cbfe32 Ignore an empty Accept header
967104a Call mime.ParseMediaType(contentType) once outside of the loop
f1c4c49 Add samples/hello-world/golang example (#276)
a6fcaec Empty string check when comparing binary media types
a5567fd Check Accept media type to decide whether to decode the base64 body or not
98a4d31 Add IsBase64Encoded to the Event struct
14160e2 Use mime.ParseMediaType instead of exact match when comparing Contetn-Type
bf0922b Adding Go Lambda function example
d92644b Merge remote-tracking branch 'upstream/master' into develop
4275487 Fix format of package.json
c097ce1 changed event names to match operation
0cf2b6e added python API event event source sample
a208898 Add binary support
6ada78b Merge branch 'develop' into develop
4da7f7f fixing erroneous newline
fbfb225 adds support for cloudformation configuration.json by passing content of key Parameters to all functions
0a35154 Update README.md
31e83eb Removed output line from review feedback
c8a71f6 Fixed issue reported in #225. Swagger mounts that don't have a function associated to them are automatically assigned an error handler. Function data is carried over from Function mount when merging
47721f0 Change OR operator to ternary operator
a83c187 link to the CF/SAM schema
69c3a58 Update the readme to reflect validate functionality
2ab9484 Some useful but import info for debugging SAMLocal
28eacbd add new sam local banner (#17)

---

Automated with GoReleaser
Built with go version go1.8.3 linux/amd64

v0.2.6

What's new in 🐿?

GoLang 1.x support!

Follow instructions from the docs to build a Go binary and package it into a zip file. Use SAM Local just like how you would for other compiled languages.

Follow the example at: #273

A big thanks for @mhart for building the Golang Docker container

Update to latest version

npm update -g aws-sam-local

Changelog

1cfd626 Fix issue where a template with no AWS::Serverless:Function.Timeout set causes AWS_LAMBDA_FUNCTION_TIMEOUT=0 to be sent to the Lambda runtime. Instead it should default to the SAM specification default (3 seconds). Also included the same default behaviour for the memory size as this was missing too. (#271)

---

Automated with GoReleaser
Built with go version go1.8.3 linux/amd64