Naval Pilgrim's Mayflower


    0.0.3 • Public • Published

    Serverless HealthCheck Plugin

    serverless npm version npm downloads license

    Check the health of your lambdas.


    • Serverless v1.12.x or higher.
    • AWS provider

    How it works

    Healthcheck solves heart beat by creating one schedule event lambda that invokes all the service lambdas you select in a configured time interval (default: 5 minutes) or a specific time, forcing your containers to report their status. In aditional, it creates a new endpoint (named __health by default) which can be called to provide a json summary of the current status of each healthcheck.


    Install via npm in the root of your Serverless service:

    npm install serverless-plugin-healthcheck --save-dev
    • Add the plugin to the plugins array in your Serverless serverless.yml:
      - serverless-plugin-healthcheck
    • Add a healthcheck property to all the events in all the functions you want to be checked.
          - http:
              path: /schema/{TypeID}
              method: get
              private: false
                params: {"subjectType": "system"}
          - http:
              path: /schema/{TypeID}/{ItemID}
              method: get
              private: false
                params: {"subjectType": "system", "subjectID": "dewey"}
    • Add additional format properties to trigger the output of a full diagnotic for each check
                params: {"subjectType": "system"}
                  id: fullschema
                  name: Get system schema
                  ok: []
                  severity: 2
                  businessImpact: Unable to describe system records
                  technicalSummary: The schema for the system type cannot be read from the CMDB
                  checkOutput: false
                  lastUpdated: []

    Note that the ok and lastUpdated are reserved and will automatically be populated, as follows: o ok is true when statuscode is 200, false otherwise o lastUpdated is the date.time at which the check was ran

    • healthcheck to be able to invoke lambdas requires the following Policy Statement in iamRoleStatements:
      Effect: 'Allow'
          - 'lambda:InvokeFunction'
          - ':'
          - - arn:aws:lambda
            Ref: AWS::Region
            Ref: AWS::AccountId
            - function:${self:service}-${opt:stage, self:provider.stage}-*

    If using pre-check, the deployment user also needs a similar policy so it can run the healthcheck lambda.

    • All done! healthcheck will run on SLS deploy and package commands


    • cleanFolder (default true)
    • memorySize (default 128)
    • name (default ${service}-${stage}-healthcheck-plugin)
    • schedule (default rate(5 minutes))
    • timeout (default 10 seconds)
    • precheck (default false)
    • endpoint (default __health)
        cleanFolder: false,
        memorySize: 256
        name: 'make-them-pop'
        schedule: 'rate(15 minutes)'
        timeout: 20
        precheck: true
        endpoint: _show_health
    • define a custom header for the healtcheck to give the healtcheck output some contaxt
        endpoint: __health
          schemaVersion: 1
          name: A great system that uses healthchecks
          systemCode: greatsys
          checks: []

    Note that checks is reserved and is used to identify the location into which the array of check responses will be placed

    Lambdas invoked by healthcheck will have event source serverless-plugin-healthcheck:

      "Event": {
        "source": "serverless-plugin-healthcheck"


    If you are doing your own package artifact set option cleanFolder to false and run serverless package. This will allow you to extract the healthcheck NodeJS lambda file from the _healthcheck folder and add it in your custom artifact logic.


    If you are deploying to a VPC, you need to use private subnets with a Network Address Translation (NAT) gateway ( WarmUp requires this so it can call the other lambdas but this is applicable to any lambda that needs access to the public internet or to any other AWS service.


    Lambda pricing here. CloudWatch pricing here. You can use AWS Lambda Pricing Calculator to check how much will cost you monthly.


    Free Tier not included + Default WarmUP options + 10 lambdas to check, each with memorySize = 1024 and duration = 10:

    • Healthcheck: runs 8640 times per month = $0.18
    • 10 checked lambdas: each invoked 8640 times per month = $14.4
    • Total = $14.58

    CloudWatch costs are not in this example because they are very low.


    Help us making this plugin better and future proof.

    • Clone the code
    • Install the dependencies with npm install
    • Create a feature branch git checkout -b new_feature
    • Lint with standard npm run lint


    This software is released under the MIT license. See the license file for more details.


    npm i serverless-plugin-healthcheck

    DownloadsWeekly Downloads






    Last publish


    • de-tooling
    • the-ft