Home

Awesome

CircleCI

DAZN Lambda Powertools

dazn-lambda-powertools is a collection of middlewares, AWS clients and helper libraries that make working with lambda easier.

Motivation

Writing Lambdas often involves the bootstrapping of specific tooling, like reading and forwarding on correlation-id's, emitting logs on a lambda timeout, and more.

Re-writing and maintaining this bootstrapping logic into every individual lambda can be a pain, so to prevent this re-work we created dazn-lambda-powertools.

Usage

The quickest way to get setup is to use the opinionated pattern basic package.

npm install @dazn/lambda-powertools-pattern-basic

const wrap = require('@dazn/lambda-powertools-pattern-basic')

module.exports.handler = wrap(async (event, context) => {
  return 42
})

For more control, you can pick and choose from the individual packages.

Powertools and Middy

All of the powertool middlewares use the middy library (v2.x), and therefore adhere to the middy API.

However, the other tools such as the clients are generic.

What's in Powertools

An integrated suite of powertools for Lambda functions that reduces the effort to implement common lamdba tasks, such as dealing with correlation-ids.

Overview of available tools

Client libraries

Patterns

Installing the powertools

via NPM

PackageInstall command
cloudwatchevents-clientnpm install @dazn/lambda-powertools-cloudwatchevents-client
correlation-idsnpm install @dazn/lambda-powertools-correlation-ids
dynamodb-clientnpm install @dazn/lambda-powertools-dynamodb-client
eventbridge-clientnpm install @dazn/lambda-powertools-eventbridge-client
firehose-clientnpm install @dazn/lambda-powertools-firehose-client
http-clientnpm install @dazn/lambda-powertools-http-client
kinesis-clientnpm install @dazn/lambda-powertools-kinesis-client
lambda-clientnpm install @dazn/lambda-powertools-lambda-client
loggernpm install @dazn/lambda-powertools-logger
middleware-correlation-idsnpm install @dazn/lambda-powertools-middleware-correlation-ids
middleware-log-timeoutnpm install @dazn/lambda-powertools-middleware-log-timeout
middleware-obfuscaternpm install @dazn/lambda-powertools-middleware-obfuscater
middleware-sample-loggingnpm install @dazn/lambda-powertools-middleware-sample-logging
middleware-stop-infinite-loopnpm install @dazn/lambda-powertools-middleware-stop-infinite-loop
pattern-basicnpm install @dazn/lambda-powertools-pattern-basic
pattern-obfuscatenpm install @dazn/lambda-powertools-pattern-obfuscate
sns-clientnpm install @dazn/lambda-powertools-sns-client
sqs-clientnpm install @dazn/lambda-powertools-sqs-client
step-functions-clientnpm install @dazn/lambda-powertools-step-functions-client

via Lambda layer

You can also deploy the layer via our SAR app, which you can deploy either via this page (click Deploy and follow the instructions) or using CloudFormation/Serverless framework/AWS SAM:

DaznLambdaPowertoolsLayer:
  Type: AWS::Serverless::Application
  Properties:
    Location:
      ApplicationId: arn:aws:serverlessrepo:us-east-1:570995107280:applications/dazn-lambda-powertools
      SemanticVersion: <enter latest version>

and reference the output Outputs.LayerVersion to get the ARN of the layer to reference in your function. e.g. Fn::GetAtt: [DaznLambdaPowertoolsLayer, Outputs.LayerVersion].

You can find the latest version of the SAR app in the lerna.json file here, in the version property.

Design goal

Compliance with best practices around logging and monitoring should be the default behaviour. These tools make it simple for you to do the right thing and gets out of your way as much as possible.

Individually they are useful in their own right, but together they're so much more useful!

The middlewares capture incoming correlation IDs, and the logger automatically includes them in every log message, and the other clients (HTTP, Kinesis, SNS, etc.) would also automatically forward them on to external systems.

Even if your function doesn't do anything with correlation IDs, the tools make sure that it behaves correctly as these correlation IDs flow through it.

Did you consider monkey-patching the clients instead?

Instead of forcing you to use dazn-powertools AWS clients, we could have monkey patched the AWS SDK clients (which we already do in the tests). We could also monkey patch Node's http module (like what Nock does) to intercept HTTP requests and inject correlation IDs as HTTP headers.

We could apply the monkey patching when you apply the correlation IDs middleware, and your function would "automagically" forward correlation IDs without having to use our own client libraries. That way, as a user of the tools, you could use whatever HTTP client you wish, and can use the standard SDK clients as well.

We did entertain this idea, but I wanted to leave at least one decision for you to make. The rationale is that when things go wrong (e.g. unhandled error, or bug in our wrapper code) or when they don't work as expected (e.g. you're using an AWS SDK client that we don't support yet), at least you have that one decision to start debugging (change the require statement to use the official library instead of our own to see if things things still work).

Useful commands

bootstrapping locally

Because of the inter-dependencies between packages, it can be tricky to test your changes haven't broken another package.

You can use Lerna CLI to bootstrap all the dependencies with the current local version:

lerna bootstrap

run all tests

npm test

run tests for a specific package

PKG=correlation-ids npm run test-package

create a new package

lerna create <name of package>

and follow the instruction to bootstrap the new project.

Contributing

Please read our contribution guide to see how you can contribute towards this project.