PLEASE NOTE: As of February 2018, Emulambda is not actively maintained by Fugue.
When Python support was announced for AWS Lambda at re:Invent, we were excited to start using it. As you could see with our emoji-powered Votebot for Slack, we put it to quick use, converting our skirmishes about lunch orders into a peaceful, democratic process.
Building Lambda functions is great, but there can be some challenges during development. There are many that we may yet cover, but the one we wanted to start with was just writing and debugging the function. As such, we wanted to build a local harness for lambda functions that could shorten the feedback loop on development, be used for attaching debuggers, drive test data through the function, and profile it as well so we'd have an idea what it would cost to run.
To do this, we developed Emulambda. To be clear, that's a portmanteau of the words "emulator" and "lambda," but if you want to think it's some sort of anonymous emu, go for it! Emulambda, just like AWS Lambda, works with Python 2.7.
Installing Emulambda is simple:
git clonethe Emulambda repo
- Install it with
pip install -e emulambda(You might need to sudo this command if you're using your system Python instead of a virtualenv or similar.)
These steps should make the
emulambda script available as a runnable file in your path. The
-e argument means the installation is "editable," so that you can hack on it if you need or want to. Soon, we'll put the project in PyPi and update these instructions to be even easier.
The repository comes with an example lambda function and example event document to show you exactly how this works. The simplest way to run Emulambda is to simply give an import path for your function and an event JSON document. You can run the example from the repository root with this command:
<code class="language-bash">emulambda example.example_handler example/example.json</code>
This will print the return value of the function to stdout, like so:
If you want a little more information, add the
<code class="language-bash">Executed example.example_handlerEstimated......execution clock time: 157ms (200ms billing bucket)...execution peak RSS memory: 368M (385888256 bytes)----------------------RESULT----------------------value1</code>
Now, we have an idea what our function takes to run. You can also set a timeout for the function, just as you can in AWS, so that tests can fail if the function takes too long. The timing and memory usage measurements are based on informed guesses about how AWS determines these things, but they should be viewed as approximate at best. Over time we might be able to refine these estimates. You can find out more about the profiling mechanism in the project README.
Another cool thing you can do is send the event into the function via
stdin. Just use the
- (dash) character in place of a filename, like this:
<code><span class="hljs-typename">emulambda -<span class="hljs-variable">v example</span>.<span class="hljs-variable">example_handler</span> - < <span class="hljs-variable">example</span>/<span class="hljs-variable">example</span>.<span class="hljs-variable">json</span></span></code>
Since stdin is supported by... well, everything that uses stdout, you can easily integrate Emulambda with other scripts or utilities.
The input document can be either a single JSON document, or a Line-Delimited JSON (LDJSON) stream. In either case, a file or stdin can be used. For more information on the LDJSON stream support, see the README.
We hope Emulambda is useful to you at both development and test time when you're working with AWS Lambda.
For development, you can
- run your lambda functions instantly locally, without packaging and sending to AWS;
- shorten your feedback loop on lambda executions; and
- easily attach debuggers to your lambda.
And for testing, Emulambda lets you
- easily integrate with test tools using a simple CLI and various input methods;
- use stream mode to test many cases or run fuzz tests; and
- use profiling information to identify expensive/problematic lambdas early.
Some future features we'd like to see in the project:
- SQS Support (though for now, you can easily pipe AWS CLI output to Emulambda stdin)
- Kinesis support / emulation
- An AWS event library, for common integrations with other services
- Context support! Probably an optional argument to provide context objects in the same way as event objects.
We are excited about the opportunities in serverless computing, and how Fugue will support you in pursuing those opportunities in the near future.