Enable serverless monitoring using the Lambda layer

Serverless monitoring for AWS Lambda offers in-depth performance monitoring for your Lambda functions. Read on to learn how to enable this feature using our Lambda layer and get started using it.

Using this feature may result in AWS charges. See Lambda monitoring requirements.​​​​​​​​​​

How does it work

When you enable serverless monitoring using our Lambda extension, this is what happens:

Lambda monitoring with New Relic layer
Lambda monitoring with the New Relic Lambda layer
  1. You configure your Lambda function to include our layer for the runtime you've chosen.
  2. As your code runs, our Lambda layer gathers telemetry data about the invocation and its execution.
  3. Just before execution finishes, the Lambda layer sends the data it has gathered to the New Relic Lambda extension, which is bundled with the layer.
  4. The extension sends the data to New Relic, along with additional information from AWS Lambda.

The layer for your runtime contains the New Relic Lambda extension. This executable extends your Lambda function. The extension sends telemetry data to New Relic, and interacts with AWS directly to enhance the data we gather, while minimizing the impact of instrumentation on your application's performance.

For Node.js and Python, the layer contains the New Relic agent code, and a wrapper for your Lambda handler. For other runtimes, we take an SDK approach, providing you with the tools to instrument your code, while taking advantage of emerging standards like OpenTracing and OpenTelemetry.

What do you need

To enable serverless monitoring using our Lambda layer, you need the following:

  • AWS CLI v2 installed and configured using aws configure.
  • Python version 3.3 or higher installed.
  • newrelic-lambda CLI, which you can install by running pip install newrelic-lambda-cli.
  • A New Relic account. You must be an admin, or have the Infrastructure manager add-on role.
  • A user key.
  • An AWS account with permissions for creating IAM resources, managed secrets, and Lambdas. You also need permissions for creating CloudFormation stacks and S3 buckets.

Note that you may need to use pip3 instead of pip if your system uses Python 2 by default.

Enable serverless monitoring

There are a few things that have to happen to let New Relic gather telemetry from your Lambda functions.

  1. Link your AWS account with your New Relic account.
  2. Configure each of your functions to include our Lambda extension.

While there are several ways to accomplish both steps, this guide focuses on the most frequent setup scenario.

When you link your AWS account to New Relic, you're granting permission to New Relic to create an inventory of your AWS account, and gather CloudWatch metrics for your Lambda functions. Resources in your AWS account then show up as entities in the entity explorer, decorated with config information.

When all the requirements are in place, link your AWS account with your New Relic account by running the following command using your user key (replace all the highlighted values):

newrelic-lambda integrations install --nr-account-id YOUR_NR_ACCOUNT_ID \
    --linked-account-name YOUR_LINKED_ACCOUNT_NAME \
    --nr-api-key YOUR_NEW_RELIC_USER_KEY 

The newrelic-lambda CLI adds your New Relic license key as a secret in AWS Secret Manager for greater security. The --linked-account-name parameter is to name the integration that will appear in New Relic.

Storing the New Relic license key in the AWS Secrets Manager

Your New Relic license key identifies and authenticates you to New Relic, allowing us to associate your telemetry with your New Relic account. Each function that sends telemetry needs access to this value, and it needs to be managed securely. The AWS Secrets Manager solves these problems.

If your organization prevents you from using AWS Secrets Manager, see below for an alternative method to set your license key.

After linking your accounts, you have to install or upgrade the New Relic Lambda layer to the latest version. All future layers versions will include the Lambda extension by default. To install/upgrade the layer, run:

newrelic-lambda layers install --nr-account-id YOUR_NR_ACCOUNT_ID --function my-function --upgrade

This command automatically finds the available layer for your Lambda's region and runtime. If the layer can't be found, you can add a layer manually. To add the layer manually, read our example code.

Deploy our examples and verify they work

Once you've linked your AWS and New Relic accounts, instrumenting your Lambda function using our Lambda extension involves a series of steps:

  1. Pick an example and install it.
  2. Invoke the Lambda and see data in New Relic.

  3. Clean up and adapt the example to your code.

We recommend trying out our example code for the following languages:

Each example contains instructions, sample code, and a deploy script to get started. After you've gotten the example to work for you, you can clean up by deleting the CloudFormation stack, using either the AWS Console, or the AWS CLI: aws cloudformation delete-stack --stack-name <stack-name>

Our examples are based on the AWS SAM CLI. There are other tools available for managing and deploying Lambda functions. New Relic offers a plugin for the Serverless Framework, and the CLI can modify your existing Lambda functions to add instrumentation. You can integrate the necessary Lambda layer and function permission using whatever AWS resource management tool you choose.


If your organization does not allow the use of AWS Secrets Manager, the New Relic Lambda Extension will accept a NEW_RELIC_LICENSE_KEY environment variable. Add the --disable-license-key-secret flag from the newrelic-lambda integrations install command. Then set this environment variable to your New Relic license key in your Lambda function configuration.

The newrelic-lambda CLI should be run once per region, with the --aws-region parameter. Use the same linked account name, and the tool will detect that the account link has been created already. The license key secret needs to be created in each region.

Similarly, several AWS accounts can be linked to a New Relic account. Give each account a different linked account name. The --aws-profile argument to the CLI tool will select the named profile. The tool uses the same configuration as the AWS CLI.

Your lambda code requires the execution role which has permission to read AWS Secrets Manager. If you find a log like the following, add the appropriate permission to the policy of the execution role. In our examples, check out the template.yaml file to see an easy way to grant this permission.

Failed to retrieve license key AccessDeniedException: User: <ARN> is not authorized to perform: secretsmanager:GetSecretValue on resource: <ARN>

What's next?

After you complete these steps, here's what you can do next:

For more help

If you need more help, check out these support and learning resources: