serverless-newrelic-lambda-layers

A Serverless plugin to add New Relic observability using AWS Lambda Layers without requiring a code change.

Requirements

• serverless >= 1.34.0

Features

• Installs and configures the New Relic AWS Integration
• Supports Node.js and Python runtimes (more runtimes to come)
• No code change required to enable New Relic
• Bundles New Relic's agent in a single layer
• Configures CloudWatch subscription filters automatically

Install

With NPM:

npm install --save-dev serverless-newrelic-lambda-layers

With yarn:

yarn add --dev serverless-newrelic-lambda-layers

Add the plugin to your serverless.yml:

plugins:
  - serverless-newrelic-lambda-layers

If you don't yet have a New Relic account, sign up here.

Grab your New Relic Account ID, your New Relic Personal API Key and plug them into your serverless.yml:

custom:
  newRelic:
    accountId: your-new-relic-account-id-here
    apiKey: your-new-relic-personal-api-key-here

Deploy:

sls deploy

And you're all set.

Usage

This plugin wraps your handlers without requiring a code change. If you're currently using a New Relic agent, you can remove the wrapping code you currently have and this plugin will do it for you automatically.

• Node.js Instrumentation Guide
• Python Instrumentation Guide

Config

The following config options are available via the newRelic section of the custom section of your serverless.yml:

accountId (required)

Your New Relic Account ID.

custom:
  newRelic:
    accountId: your-account-id-here

apiKey (required)

Your New Relic Personal API Key.

custom:
  newRelic:
    apiKey: your-api-key-here

linkedAccount (optional)

A label for the New Relic Linked Account. This is how this integration will appear in New Relic. If not set, it will default to "New Relic Lambda Integration - ".

custom:
  newRelic:
    linkedAccount: your-linked-account-name

#### `trustedAccountKey` (optional)

Only required if your New Relic account is a sub-account. This needs to be the account ID for the root/parent account.

```yaml
custom:
  newRelic:
    trustedAccountKey: your-parent-account-id

debug (optional)

Whether or not to enable debug mode. Must be a boolean value. This sets the log level to debug.

custom:
  newRelic:
    debug: true

logEnabled (optional)

Enables logging. Defaults to false

enableIntegration (optional)

Allows the creation of New Relic aws cloud integration when absent. Defaults to false

custom:
  newRelic:
    enableIntegration: true

logLevel (optional)

Sets a log level on all functions. Possible values: 'fatal', 'error', 'warn', 'info', 'debug', 'trace' or 'silent'. Defaults to 'error'

You can still override log level on a per function basis by configuring environment variable NEW_RELIC_LOG_LEVEL.

custom:
  newRelic:
    logLevel: debug

Logging configuration is considered in the following order:

1. function NEW_RELIC_LOG_LEVEL environment
2. provider NEW_RELIC_LOG_LEVEL environment
3. custom newRelic logLevel property
4. custom newRelic debug flag

customRolePolicy (optional)

Specify an alternative IAM role policy ARN for this integration here if you do not want to use the default role policy.

custom:
  newRelic:
    customRolePolicy: your-custom-role-policy-arn

stages (optional)

An array of stages that the plugin will be included for. If this key is not specified then all stages will be included. stages: - prod

#### `include` (optional)

An array of functions to include for automatic wrapping. (You can set `include` or `exclude` options, but not both.)

```yaml
custom:
  newRelic:
    include:
      - include-only-func
      - another-included-func

exclude (optional)

An array of functions to exclude from automatic wrapping. (You can set include or exclude options, but not both.)

custom:
  newRelic:
    exclude:
      - excluded-func-1
      - another-excluded-func

layerArn (optional)

Pin to a specific layer version. The latest layer ARN is automatically fetched from the New Relic Layers API

custom:
  newRelic:
    layerArn: arn:aws:lambda:us-east-1:451483290750:layer:NewRelicPython37:2

cloudWatchFilter (optional)

Provide a list of quoted filter terms for the CloudWatch log subscription to the newrelic-log-ingestion Lambda. Combines all terms into an OR filter. Defaults to "NR_LAMBDA_MONITORING" if not set. Use "*" to capture all logs

custom:
  newRelic:
    cloudWatchFilter:
      - "NR_LAMBDA_MONITORING"
      - "trace this"
      - "ERROR"

If you want to collect all logs:

custom:
  newRelic:
    cloudWatchFilter: "*"

Be sure to set the LOGGING_ENABLED environment variable to true in your log ingestion function. See the aws-log-ingestion documentation for details.

prepend (optional)

Whether or not to prepend the IOpipe layer. Defaults to false which appends the layer.

custom:
  newRelic:
    prepend: true

logIngestionFunctionName (optional)

Only required if your New Relic log ingestion function name is different from newrelic-log-ingestion.

custom:
  newRelic:
    logIngestionFunctionName: log-ingestion-service

disableAutoSubscription (optional)

Only required if you want to disable auto subscription.

custom:
  newRelic:
    disableAutoSubscription: true

Supported Runtimes

This plugin currently supports the following AWS runtimes:

• nodejs8.10
• nodejs10.x
• nodejs12.x
• python2.7
• python3.6
• python3.7
• python3.8

Contributing

Testing

1. Make changes to examples/nodejs/serverless.yml based on what you are planning to test
2. Generate a test case by executing script generate:test:case

# Example
npm run generate:test:case

3. Rename generated file tests/fixtures/example.service.input.json to test case e.g. tests/fixtures/log-level.service.input.json
4. Create expected output file tests/fixtures/example.service.output.json for test case e.g. tests/fixtures/log-level.service.output.json
5. Run tests

# Example
npm run test