Layered instrumentation

You can instrument your Lambda function with the newrelic-lambda CLI quickstart.

To install or upgrade the New Relic instrumentation layer, run this command:

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

This command automatically finds the newest available layer for your Lambda's region and runtime.

This command provides a rapid way to initiate New Relic instrumentation and can be easily integrated into your CI/CD pipeline. However, since it modifies existing Lambda function resources, redeployment of updated code may inadvertently remove the instrumentation. To ensure continuous monitoring, either re-run the command after each deployment or, preferably, incorporate the New Relic layer and configuration directly into your deployment process.

Note that the CLI can operate on many functions in a batch: use --function all, --function installed, or --function not-installed to operate on all functions in a region, or only those with or without existing New Relic instrumentation.

AWS's Serverless Application Model, or SAM is a variant of CloudFormation templates that simplifies relating functions to the resources they depend on, and managing the lifecycle of an entire application. We use SAM and CloudFormation for most of our Lambda example functions, and many other tools are built on top of CloudFormation templates, providing an addition layer of abstraction.

CloudFormation is an AWS service that simplifies the provisioning and management of AWS resources. By defining the desired state of resources in YAML or JSON templates, CloudFormation automatically handles the underlying API calls to create, update, or delete resources as needed. This declarative approach automates infrastructure management, ensuring consistency and reproducibility.

To monitor your Lambda function with New Relic:

1. Install the New Relic Lambda layer. Here's an example of a simple CloudFormation template for a Node.js Lambda function:

   AWSTemplateFormatVersion: '2010-09-09'
   Transform: AWS::Serverless-2016-10-31
   Description: And example of a simple instrumented Node.js Lambda
   
   Resources:
     NewRelicExample:
       Type: AWS::Serverless::Function
       Properties:
         # In this example, we're using the SAM CLI to package and deploy our lambda. SAM will transform this value during the publish step.
         CodeUri: newrelic-example-node/
         # The handler for your function needs to be the one provided by the instrumentation layer, below.
         Handler: newrelic-lambda-wrapper.handler
         Runtime: nodejs22.x
         Environment:
           Variables:
             # For the instrumentation handler to invoke your real handler, we need this value
             NEW_RELIC_LAMBDA_HANDLER: YOUR_PATH_TO_INITIAL_LAMBDA_HANDLER
             # Distributed tracing needs your account ID, and your trusted account ID
             NEW_RELIC_ACCOUNT_ID: YOUR_ACCOUNT_ID_HERE
             # If your New Relic account has a parent account, this value should be that account ID. Otherwise, just
             # your account id.
             NEW_RELIC_TRUSTED_ACCOUNT_KEY: YOUR_PARENT_ACCOUNT_ID_HERE
             NEW_RELIC_APM_LAMBDA_MODE: 'true'
         Tags:
         # This tag is to enable APM mode. 
           NR.Apm.Lambda.Mode: true
         Layers:
           # This layer includes the New Relic Lambda extension, a sidecar process that sends telemetry,
           # as well as the New Relic agent for Node.js, and a handler wrapper that makes integration easy.
           - !Sub arn:${AWS::Partition}:lambda:${AWS::Region}:451483290750:layer:NewRelicNodeJS16X:103
         Policies:
           # This policy allows the lambda to know the value of the New Relic license key. We need this so
           # that we can send telemetry back to New Relic
           - AWSSecretsManagerGetSecretValuePolicy:
               SecretArn: !ImportValue NewRelicLicenseKeySecret-NewRelic-LicenseKeySecretARN

   Copy

   Typically, you'll have a file named template.yaml that describes your function, and its resources.

2. Configure the required environment variables.

3. Deploy your Lambda function with the updated configuration.

Serverless Framework is a popular development and deployment tool for serverless applications. It's written for AWS in Node.js, and acts mostly as a high level abstraction on top of CloudFormation templates. It works well for Node, Python, Ruby, Java, and .NET functions.

New Relic provides a Serverless Framework Plugin to simplify instrumentation of your Serverless Framework application.

Prerequisites:

• An existing application that uses the Serverless Framework.

• New Relic Account ID

• New Relic Personal API Key

  To install and configure your Serverless Framework application with New Relic:

1. If you use npm, run the following command:

   bash

   Copy

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

   OR, If you use yarn, run the following command:

   bash

   Copy

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

2. Open your serverless.yaml file and add the following configuration:

   1. Add serverless-newrelic-lambda-layers to your plugins list.

   2. Add the following New Relic configuration in the custom section:

      plugins:
          - serverless-newrelic-lambda-layers
        custom:
          newRelic:
            accountId: your-new-relic-account-id-here
            apiKey: your-new-relic-personal-api-key-here
            linkedAccount: your-new-relic-integration-account-name-here
            apm: true

      Copy

   3. Add the following NR.Apm.Lambda.Mode: true tag in the provider section:

      provider:
          tags:
            NR.Apm.Lambda.Mode: true

      Copy

3. Configure the required environment variables.

4. Deploy your Lambda function with the updated configuration.

The AWS Cloud Development Kit (AWS CDK) is a framework for defining cloud resources in code and provisioning it through AWS CloudFormation.

To use New Relic with AWS CDK, follow these steps:

1. Install the New Relic Lambda layer. Below is an example of a basic CDK app that deploys a New Relic instrumented Node.js Lambda function:

   import * as cdk from 'aws-cdk-lib';
   import { Construct } from 'constructs';
   import * as lambda from 'aws-cdk-lib/aws-lambda';
   
   export class NewRelicExampleCdkStack extends cdk.Stack {
     constructor(scope: Construct, id: string, props?: cdk.StackProps) {
       super(scope, id, props);
       // Add latest New Relic Lambda layer ARN from https://layers.newrelic-external.com
       const NewReliclayerArn = 'arn:aws:lambda:us-east-1:451483290750:layer:NewRelicNodeJS22X:38';
       const myFunction = new lambda.Function(this, "NewRelicExampleLambda", {
         runtime: lambda.Runtime.NODEJS_20_X,
         // Update functions handler to point to the New Relic Lambda wrapper
         handler: "newrelic-lambda-wrapper.handler",
         code: lambda.Code.fromAsset('lib/lambda-runtime-code'),
         layers: [lambda.LayerVersion.fromLayerVersionArn(this, 'NewRelicLayer', NewReliclayerArn)],
         environment: {
           // Set the NEW_RELIC_LAMBDA_HANDLER environment variable to the path of your initial handler.
           NEW_RELIC_LAMBDA_HANDLER: 'index.handler',
           NEW_RELIC_APM_LAMBDA_MODE: 'true'
         },
       });
       // Add the New Relic APM Lambda Mode tag
       cdk.Tags.of(myFunction).add('NR.Apm.Lambda.Mode', 'true');
     }
   }

   Copy

2. Configure the required environment variables.

3. Deploy your Lambda function with the updated configuration.

Terraform is a popular general-purpose infrastructure as code tool. It can be used to manage AWS resources. We offer some examples of New Relic instrumented Lambda functions deployed using Terraform scripts.

You can use the New Relic Terraform provider to set up your AWS integrations. Upon setting up the provider, configure the required environment variables, and add the NR.Apm.Lambda.Mode: true tag to your Lambda function.

While it is more error prone and labor intensive than the approaches above, you can manually alter the configuration of a Lambda function to use New Relic from the AWS Lambda Console, for Node.js, Python, Ruby and Java.

Here's an example for how to instrument New Relic Lambda monitoring for a Ruby runtime:

1. Navigate to the Lambda service section in the AWS web console. From there, find the Lambda function you would like to connect to New Relic.

2. In the default Code tab, scroll down to the Layers section, and click on the Add a layer button.

3. Click the Create layer button.

4. Go to the Choose a layer and select the Specify an ARN option.

5. Go to New Relic's list of layers and use the drop-down list to select the AWS region where your Lambda function is hosted. From there, locate the ARN that matches your Lambda function's Ruby version and architecture. There should be two options: X86 and ARM64. Use the Copy to clipboard button or manually copy the ARN string.

6. In the Specify an ARN section of the AWS console form, paste in the New Relic Lambda layer ARN.

7. On the AWS console form, click the Add button to add the layer to your Lambda function.

8. On your Lambda function's page, with the default Code tab selected, scroll down to the Runtime settings section and click the Edit button.

9. Make a safe copy of the existing Handler value. You'll need it for a later step.

10. Change the Handler value to: newrelic_lambda_wrapper.handler and click Save.

11. Switch to the Configuration tab on your Lambda function's page.

12. Select the Environment variables sub-tab and based on your requirement, define the Environmental Variables.

13. Modify the Execution Role to allow access to the New Relic license key secret.

    • Find the ARN of the secret named NEW_RELIC_LICENSE_KEY.
    • Add a new inline policy in the function's execution role that looks like this the code below. Replace the SECRET_ARN with the value you found above.

      "Statement": [
        {
          "Action": [
            "secretsmanager:GetSecretValue"
          ],
          "Resource": "SECRET_ARN",
          "Effect": "Allow"
        }
      ]

      Copy

      Tip

      The New Relic layer will automatically deliver the New Relic Ruby agent and be loaded via a Ruby require prior to your Lambda function's invocation. To avoid conflicts, don't include a copy of the Ruby agent anywhere else. Feel free to perform any desired New Relic Ruby agent API calls within your function to take advantage of the agent's presence.

14. In your AWS Management Console, on the Configuration tab, add the NR.Apm.Lambda.Mode: true tag to your Lambda function.

15. Deploy your Lambda function with the updated configuration.

    Java, Python, Node.js, and .Net runtimes will follow the same instrumentation flow as Ruby, but with some different handlers. Here's how to update your function's handler to point to the newly attached layer in the console for your function:

• Java:

  • RequestHandler implementation: com.newrelic.java.HandlerWrapper::handleRequest.
  • RequestStreamHandlerWrapper implementation: com.newrelic.java.HandlerWrapper::handleStreamsRequest.

• Python: newrelic_lambda_wrapper.handler (underscores).

• Node:

  • CommonJS: newrelic-lambda-wrapper.handler (hyphens).
  • ESM: /opt/nodejs/node_modules/newrelic-esm-lambda-wrapper/index.handler (hyphens).

• For .Net you don't have to set the handler.

  Note that for Go, you must make source code changes to your Lambda function to instrument it. Configuration changes are not enough.