---
title: SDK based instrumentation
source: https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/instrument-lambda-function/sdk-based-instrumentation
---

SDK based instrumentation requires you to enable New Relic agent as an SDK for your chosen runtime. Additionally, you must configure the New Relic extension or the `newrelic-log-ingestion` lambda to send data to New Relic.

Select your runtime below and follow the setup instructions.

**Go**

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:

        ```shell
        go get -u github.com/newrelic/go-agent/v3/newrelic
        ```

    2.  Install the `nrlambda` integration by running:

        ```shell
        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](https://github.com/newrelic/newrelic-lambda-extension/tree/main/examples/sam/go)
    -   [Go agent repo](https://github.com/newrelic/go-agent/blob/master/v3/integrations/nrlambda/example/main.go)

3.  Optionally, add [custom events](https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/getting-started/glossary#custom-event) that will be associated with your Lambda invocation by using the [`RecordCustomEvent` API](https://docs.newrelic.com/docs/agents/go-agent/features/create-custom-events-insights-go). For example:

    ```go
    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!")
    }
    ```

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
        GOOS=linux go build -o main
        ```
    2.  Zip the binary into a deployment package using:

        ```bash
        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](https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/instrument-lambda-function/env-variables-lambda).

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](https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/instrument-lambda-function/cloud-watch-fallback).

**Java**

> #### 💡 TIP
>
> This solution does not use the APM Java Agent. If you wish to use the APM Java Agent in AWS Lambda, please refer to our [Java Agent Serverless Solution Doc](https://docs.newrelic.com/docs/apm/agents/java-agent/getting-started/java-agent-approaches-lambda).
> The APM agent based solution should not be run with the SDK based solution.

Monitoring for AWS Lambda in Java using the SDK based solution uses two Open Tracing dependencies:

-   AWS Lambda OpenTracing Java SDK: [OpenTracing](https://github.com/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](https://search.maven.org/artifact/com.newrelic.opentracing/newrelic-java-lambda/1.1.1/jar)
    >     -   Lambda SDK: [com.newrelic.opentracing:java-aws-lambda:1.0.0](https://search.maven.org/artifact/com.newrelic.opentracing/java-aws-lambda/1.0.0/jar)
    > -   **OpenTracing 0.32.0, 0.33.0**:
    >     -   Lambda Tracer: [com.newrelic.opentracing:newrelic-java-lambda:2.2.3](https://search.maven.org/artifact/com.newrelic.opentracing/newrelic-java-lambda)
    >     -   Lambda SDK: [com.newrelic.opentracing:java-aws-lambda:2.1.1](https://search.maven.org/artifact/com.newrelic.opentracing/java-aws-lambda)

    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:

    ```java
    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")
    }
    ```
2.  Implement the AWS Lambda `RequestHandler` interface as shown in the [Java Lambda example](https://github.com/newrelic/newrelic-lambda-tracer-java#usage) 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](https://github.com/newrelic/newrelic-lambda-tracer-java#usage).
5.  [Create a ZIP deployment package](https://docs.aws.amazon.com/lambda/latest/dg/java-package.html) 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](https://github.com/newrelic/newrelic-lambda-tracer-java#usage), 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](https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/instrument-lambda-function/env-variables-lambda).
8.  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](https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/instrument-lambda-function/cloud-watch-fallback).

    Please see the [AWS Lambda distributed tracing example](https://github.com/newrelic/newrelic-lambda-tracer-java/tree/main/examples/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

**Node.js**

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
    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:

    ```js
    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();
    });
    ```

    -   Sample Code for ES Module:

    ```js
    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();
    });
    ```

3.  Optional: You can also add [custom events](https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/getting-started/glossary#custom-event) to your Lambda using the [`recordCustomEvent` API](https://docs.newrelic.com/docs/agents/nodejs-agent/api-guides/nodejs-agent-api#record_custom_event). For example:

    -   Sample code for CommonJS:

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

    -   Sample code for ES Module:

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

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](https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/instrument-lambda-function/env-variables-lambda).

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)](https://layers.newrelic-external.com/) layer arn. You can either use AWS CLI to install the layer or manually add it to your Lambda.
    ```bash
    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](https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/instrument-lambda-function/cloud-watch-fallback/) for detailed steps.

**Python**

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
    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](https://github.com/Homebrew/brew/blob/master/docs/Homebrew-and-Python.md#note-on-pip-install---user).

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:

    ```py
    import newrelic.agent
    from newrelic_lambda.lambda_handler import lambda_handler

    newrelic.agent.initialize()

    @lambda_handler()
    def handler(event, context):
      ...
    ```

4.  Optional: You can also add [custom events](https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/getting-started/glossary#custom-event) to your Lambda using the [`record_custom_event` API](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/record_custom_event). Here's an example:

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

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](https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/instrument-lambda-function/env-variables-lambda).

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](https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/instrument-lambda-function/cloud-watch-fallback).

**.NET**

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](https://www.nuget.org/packages/NewRelic.Agent) to your AWS Lambda project. For more information, see our [installation guide](https://docs.newrelic.com/docs/apm/agents/net-agent/install-guides/install-net-agent-using-nuget/).
2.  Configure the [environment variables](https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/instrument-lambda-function/env-variables-lambda).
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](https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/enable-lambda-monitoring/account-linking/) 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.

## Find and use data [#find-data]

After you instrument your AWS Lambda functions, you can find and use the data in the New Relic APM interface. The data is organized into several key areas, each providing different insights into the performance and health of your Lambda functions.

In the APM interface, you can explore various aspects of your Lambda functions including [distributed tracing](https://docs.newrelic.com/docs/distributed-tracing/concepts/introduction-distributed-tracing/), [service maps](https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/ui-data/service-maps/service-maps/), [transactions](docs/apm/transactions/intro-transactions/transactions-new-relic-apm//), and [error analysis](docs/errors-inbox/getting-started/), and many more. Each of these areas provides detailed insights into the performance, latency, and error rates of your Lambda functions, allowing you to quickly identify and resolve issues.

> #### 💡 TIP
>
> The Invocation experience is now integrated with APM transaction traces. This allows you to use a specific `AWS RequestId` to drill-down into an APM transaction trace for detailed information about that particular Lambda execution.

To view your Lambda functions in the New Relic APM interface:

1.  Go to <https://one.newrelic.com> > APM & Services.
2.  Set the search criteria as `isLambdaFunction = true`.
3.  From the displayed list, select your Lambda Function to view the data.

## Related articles [#related-docs]

[Compatibility and requirement](https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/instrument-lambda-function/compatibility-requirement-lambda-monitoring)

Learn more about supported runtimes and prerequisites

[Troubleshooting](https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/troubleshooting/troubleshoot-enabling-serverless-monitoring-aws-lambda)

Learn how to troubleshoot installation related issues