SDK based instrumentation

To instrument your Go-language Lambda:

1. Download our Go agent package, and place it in the same directory as your function.

   1. Install the agent by running:

      bash

      Copy

      $
      go get -u github.com/newrelic/go-agent/v3/newrelic

   2. Install the nrlambda integration by running:

      bash

      Copy

      $
      go get -u github.com/newrelic/go-agent/v3/integrations/nrlambda

2. In your Lambda code, import our components, create an application, and update how you start your Lambda. See our instrumentation examples:

   • Extension repo
   • Go agent repo

3. Optionally, add custom events that will be associated with your Lambda invocation by using the RecordCustomEvent API. For example:

   func handler(ctx context.Context) {
     if txn := newrelic.FromContext(ctx); nil != txn {
       txn.Application().RecordCustomEvent("MyEvent", map[string]interface{}{
         "zip": "zap",
       })
     }
     fmt.Println("hello world!")
   }

   Copy

4. Build and zip your Lambda function and upload it to AWS.

   Zip and upload recommendations

   Here are suggestions for zipping and uploading the Lambda:

   1. Build the binary for execution on Linux. This produces a binary file called main. You can use:

      bash

      Copy

      $
      GOOS=linux go build -o main

   2. Zip the binary into a deployment package using:

      bash

      Copy

      $
      zip deployment.zip main

   3. Upload the zip file to AWS using either the AWS Lambda console or the AWS CLI. Name the handler main (to match the name given during the binary build).

5. Configure the environment variables.

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

7. Invoke the Lambda at least once. This creates a CloudWatch log group, which must be present for the next step to work.

   Our wrapper gathers data about the Lambda execution, generates a JSON message, and logs it to CloudWatch Logs. Next, you'll configure CloudWatch to send those logs to New Relic.

Monitoring for AWS Lambda in Java doesn't use our APM Java agent. Instead, it uses these two OpenTracing dependencies:

• AWS Lambda OpenTracing Java SDK: OpenTracing instrumentation for AWS Lambda RequestHandler and RequestStreamHandler.

• Our AWS Lambda OpenTracing Tracer: An OpenTracing Tracer implementation designed to monitor AWS Lambda. It generates spans, error events, transaction events, error traces, and provides distributed tracing support.

  Important

  Version 3.0.0 of New Relic AWS Lamdba OpenTracing Java SDK library made changes to the versions of AWS dependencies. The following dependencies are now used:

  • com.amazonaws:aws-lambda-java-core:1.2.3 (previous version: 1.1.0)

  • com.amazonaws:aws-lambda-java-events:3.15.0 (previous version: 2.2.7)

  • software.amazon.awssdk:s3:2.31.43 (replaces com.amazonaws:aws-java-sdk-s3:1.12.771)

  • software.amazon.awssdk:s3-event-notifications:2.31.43 (replaces com.amazonaws:aws-java-sdk-s3:1.12.771)

    It is recommended that functions that utilize the New Relic AWS Lamdba OpenTracing Java SDK utilize the same (or higher) versions of the underlying AWS libraries as noted above. Functions that are unable to upgrade should remain on version 2.2.0 of this library.

  Tip

  Supported OpenTracing Versions

  • OpenTracing 0.31.0:
    • Lambda Tracer: com.newrelic.opentracing:newrelic-java-lambda:1.1.1
    • Lambda SDK: com.newrelic.opentracing:java-aws-lambda:1.0.0
  • OpenTracing 0.32.0, 0.33.0:
    • Lambda Tracer: com.newrelic.opentracing:newrelic-java-lambda:2.2.3
    • Lambda SDK: com.newrelic.opentracing:java-aws-lambda:2.1.1

  To instrument your Java Lambda:

1. In your project's build.gradle file, include our OpenTracing AWS Lambda Tracer and the AWS Lambda OpenTracing SDK dependencies:

   dependencies {
       compile("com.newrelic.opentracing:java-aws-lambda:2.1.1")
       compile("com.newrelic.opentracing:newrelic-java-lambda:2.2.3")
       compile("io.opentracing:opentracing-util:0.33.0")
   }

   Copy

2. Implement the AWS Lambda RequestHandler interface as shown in the Java Lambda example and override the doHandleRequest method.

3. In the doHandleRequest method, call the LambdaTracing.instrument(...) API to create a root span to trace the lambda function's execution. This is also where you will define your business logic for the lambda function.

4. Register a LambdaTracer.INSTANCE as the OpenTracing Global tracer, as shown in the Java Lambda example.

5. Create a ZIP deployment package and upload it to AWS Lambda. Or deploy it via other means.

6. In the AWS Lambda console, set the handler. For the example Java Lambda, the handler would be com.handler.example.MyLambdaHandler::handleRequest. Because handleRequest is assumed, you could also use com.handler.example.MyLambdaHandler.

7. Configure the environment variables.

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

9. Invoke the Lambda at least once. This creates a CloudWatch log group, which must be present for the next step to work.

   Our wrapper gathers data about the Lambda execution, generates a JSON message, and logs it to CloudWatch Logs. Next, you'll configure CloudWatch to send those logs to New Relic.

   Please see the AWS Lambda distributed tracing example for a complete project that illustrates common use cases such as:

• Distributed tracing between Lambda functions
• Manual span creation (aka custom instrumentation)
• Tracing external calls
• Adding custom attributes (aka Tags) to spans

To instrument your Node.js Lambda:

1. Download our Node.js agent package and place it in the same directory as your function, ensuring the agent is installed as a dependency in the node_modules directory. Use the Node Package Manager:

   bash

   Copy

   $
   npm install newrelic --save

2. In your Lambda code, require the agent module at the top of the file, and wrap the handler function with the newrelic setLambdaHandler. For example:

   • Sample Code for CommonJS:

   const newrelic = require('newrelic');
   // Other module loads go under the require statement above
   
   module.exports.handler = newrelic.setLambdaHandler((event, context, callback) => {
     // This is your handler function code
     console.log('Lambda executed');
     callback();
   });

   Copy
   • Sample Code for ES Module:

   import newrelic from 'newrelic';
   // Other module loads go under the require statement above
   
   export const handler = newrelic.setLambdaHandler((event, context, callback) => {
     // This is your handler function code
     console.log('Lambda executed');
     callback();
   });

   Copy

3. Optional: You can also add custom events to your Lambda using the recordCustomEvent API. For example:

   • Sample code for CommonJS:

   module.exports.handler = newrelic.setLambdaHandler((event, context, callback) => {
     newrelic.recordCustomEvent('MyEventType', { foo: 'bar' });
     console.log('Lambda executed');
     callback();
   });

   Copy
   • Sample code for ES Module:

   export const lambdaHandler = newrelic.setLambdaHandler((event, context, callback) => {
     newrelic.recordCustomEvent('MyEventType', { foo: 'bar' });
     console.log('Lambda executed');
     callback();
   });

   Copy

4. Zip your Lambda function and the Node.js agent folder together. Requirements and recommendations:

   • The New Relic files outside the New Relic agent folder don't need to be included.
   • If your Lambda function file name is, for example, lambda_function.node, we recommend naming your zip file lambda_function.zip. Do not use a tarball.
   • Your Lambda and its associated modules must all be in the zip file's root directory. This means that if you zip a folder that contains the files, it won't work.

5. Upload the zipped file to your AWS Lambda account.

6. Configure the environment variables.

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

8. To complete the instrumentation, follow one of the following steps to send the telemetry data to New Relic:

   • Use the New Relic Lambda Extension layer. You can get the latest (NewRelicLambdaExtension) layer arn. You can either use AWS CLI to install the layer or manually add it to your Lambda.
   bash

   Copy

   $
   aws lambda update-function-configuration --function-name <your-lambda-function-name> --layers arn:aws:lambda:<aws-region>:451483290750:layer:NewRelicLambdaExtension:<version>

   • Use the newrelic-log-ingestion. You can refer to the CloudWatch fallback for detailed steps.

To instrument your Python Lambda:

1. Download both the Python agent and Python lambda wrapper packages and place them in the same directory as your function code. To do this, use pip:

   bash

   Copy

   $
   pip install -t . newrelic newrelic-lambda

   Important

   If you use Homebrew, you may get this error: DistutilsOptionError: must supply either home or prefix/exec-prefix -- not both. For details, see the Homebrew GitHub post.

2. In your Lambda code, import both the Python agent module and the Python lambda wrapper module.

3. Decorate the handler function using the New Relic decorator. The New Relic package must be imported first in your code. Here's an example:

   import newrelic.agent
   from newrelic_lambda.lambda_handler import lambda_handler
   
   newrelic.agent.initialize()
   
   @lambda_handler()
   def handler(event, context):
     ...

   Copy

4. Optional: You can also add custom events to your Lambda using the record_custom_event API. Here's an example:

   @lambda_handler()
   def handler(event, context):
     newrelic.agent.record_custom_event('CustomEvent', {'foo': 'bar'})
     ...

   Copy

5. Zip your lambda_function.py and newrelic/ folder together using these guidelines:

   • The New Relic files outside the newrelic/ folder don't need to be included.
   • If your Lambda function file name is, for example, lambda_function.py, name your zip file lambda_function.zip. Do not use a tarball.
   • Your Lambda and its associated modules must all be in the zip file's root directory. This means that if you zip a folder that contains the files, it won't work.

6. Upload the zipped file to your AWS Lambda account.

7. Configure the environment variables.

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

9. Invoke the Lambda at least once. This creates a CloudWatch log group, which must be present for the next step to work.

   The New Relic decorator gathers data about the Lambda execution, generates a JSON message, and logs it to CloudWatch Logs. Next, configure CloudWatch to send those logs to New Relic.

In most cases, the .NET Agent will automatically instrument your AWS Lambda function and switch into a "serverless mode" that will disable sending data directly to New Relic as well some other features. You must either use the New Relic Lambda Extension or the newrelic-log-ingestion lambda method to send data to New Relic.

To instrument your .NET Lambda:

1. Add the NewRelic.Agent nuget package to your AWS Lambda project. For more information, see our installation guide.
2. Configure the environment variables.
3. In your AWS Management Console, on the Configuration tab, add the NR.Apm.Lambda.Mode: true tag to your Lambda function.
4. Publish the project to your AWS Lambda account.
5. Configure either the New Relic Lambda Extension or the newrelic-log-ingestion lambda.
6. Invoke the Lambda at least once to check for errors and ensure the data is visible in the New Relic UI.