serverless-newrelic-lambda-layers

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

Requirements

serverless >= 3.x (v3.x of this plugin has been tested to work with Serverless v2, but future compatibility is not guaranteed.)
Node >= 14.x (if using Serverless version 3)

Features

Installs and configures the New Relic AWS Integration
Supports Node.js, Python and Java 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

(Note: this plugin's production dependencies are now defined as peer dependencies. NPM v7 and later will install missing peer dependencies automatically, but v6 does not.)

With yarn:

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

Add the plugin to your serverless.yml:

plugins:
  - serverless-newrelic-lambda-layers

This plugin should come last in your plugin ordering, particularly if you're also using plugins such as serverless-plugin-typescript or serverless-webpack.

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.

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

If your function's source is committed to version control, you can avoid committing your license key by including it in your serverless.yml as a variable. See the Serverless docs on template variables for more information.

`nrRegion` (required for EU; optional for US)

If your New Relic account is based in the EU, make sure to specify your nrRegion in the custom block:

custom:
  newRelic:
    nrRegion: 'eu'

`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.

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

`enableExtension` (optional)

Allows your function to deliver its telemetry to New Relic via AWS Lambda Extension. Defaults to true, so it can be omitted. To avoid delivering your telemetry via the extension, set to false.

custom:
  newRelic:
    enableExtension: true

`enableFunctionLogs` (optional)

Allows your function to deliver all of your function logs to New Relic via AWS Lambda Extension. This would eliminate the need for a CloudWatch log subscription + the NR log ingestion Lambda function. This method of log ingestion is lower-cost, and offers faster time to glass.

custom:
  newRelic:
    enableFunctionLogs: true

`enableExtensionLogs` (optional)

The New Relic Lambda Extension writes diagnostic logs by default. If you'd prefer to mute them, set this to false. (Defaults to true.)

custom:
  newRelic:
    enableExtensionLogs: false

`logEnabled` (optional)

Enables logging when using CloudWatch-based telemetry transport with the newrelic-log-ingestion Lambda function. Defaults to false

`enableIntegration` (optional)

Allows the creation of New Relic aws cloud integration when absent. Defaults to false. If an integration already exists for your AWS account,you can omit this.

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:

function NEW_RELIC_LOG_LEVEL environment
provider NEW_RELIC_LOG_LEVEL environment
custom newRelic logLevel property
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.

custom:
  newRelic:
    stages:
       - prod

`include` (optional)

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

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 New Relic 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

`disableLicenseKeySecret` (optional)

Only required if you want to disable creating license key in AWS Secrets Manager. Setting this as true would create NEW_RELIC_LICENSE_KEY environment variable for the New Relic Lambda Extension to access.

custom:
  newRelic:
    disableLicenseKeySecret: true

`javaNewRelicHandler` (optional)

Java runtimes only. Only required if you are implementing the RequestStreamHandler interface. Defaults to RequestHandler interface.

Accepted inputs:

handleRequest
handleStreamsRequest

custom:
  newRelic:
    javaNewRelicHandler: handleStreamsRequest

`proxy` (optional)

This plugin makes various HTTP requests to public APIs in order to retrieve data about the New Relic and cloud provider accounts. If you are behind a proxy when this plugin runs, the HTTP agent needs the proxy information to connect to those APIs. Use the given URL as a proxy for HTTP requests.

custom:
  newRelic:
    proxy: http://yourproxy.com:8080

Supported Runtimes

This plugin currently supports the following AWS runtimes:

nodejs12.x
nodejs14.x
nodejs16.x
nodejs18.x
python3.6
python3.7
python3.8
python3.9
java11
java8.al2

Contributing

Testing

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

# Example
npm run generate:test:case

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

# Example
npm run test

alphaadidas/serverless-newrelic-lambda-layers

serverless-newrelic-lambda-layers

Requirements

Features

Install

Usage

Config

accountId (required)

apiKey (required)

nrRegion (required for EU; optional for US)

linkedAccount (optional)

trustedAccountKey (optional)

debug (optional)

enableExtension (optional)

enableFunctionLogs (optional)

enableExtensionLogs (optional)

logEnabled (optional)

enableIntegration (optional)

logLevel (optional)

customRolePolicy (optional)

stages (optional)

include (optional)

exclude (optional)

layerArn (optional)

cloudWatchFilter (optional)

prepend (optional)

logIngestionFunctionName (optional)

disableAutoSubscription (optional)

disableLicenseKeySecret (optional)

javaNewRelicHandler (optional)