| title | metaDescription | redirects | freshnessValidatedDate | |||||||
|---|---|---|---|---|---|---|---|---|---|---|
Layerless instrumentation for Lambda monitoring |
Legacy instructions for manually enabling New Relic monitoring for AWS Lambda. |
|
never |
On this page, you will learn how to manually instrument your lambda function. It's organized by runtime language. If you haven't already, create your free New Relic account below to start monitoring your data today.
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](/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](/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.
<CollapserGroup>
<Collapser
id="zip-upload"
title="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).
</Collapser>
</CollapserGroup>
5. The following environment variables are not required for Lambda monitoring to function, but they are required if you want your Lambda functions to be included in distributed traces. To enable [distributed tracing](/docs/apm/distributed-tracing/getting-started/introduction-distributed-tracing), set these [environment variables](https://docs.aws.amazon.com/amplify/latest/userguide/environment-variables.html) in the AWS console:
- `NEW_RELIC_ACCOUNT_ID`. Your [account ID](/docs/accounts/install-new-relic/account-setup/account-id).
- `NEW_RELIC_TRUSTED_ACCOUNT_KEY.` This is also your [account ID](/docs/accounts/install-new-relic/account-setup/account-id). If your account is a child account, this is the account ID for the root/parent account.
6. Optionally, to configure logging, see [Go agent logging](/docs/agents/go-agent/configuration/go-agent-logging).
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](/docs/serverless-function-monitoring/aws-lambda-monitoring/enable-lambda-monitoring/instrument-your-own/#manual-stream-logs).
<Collapser id="java" title="Java"
Monitoring for AWS Lambda in Java doesn't use our [APM Java agent](/docs/agents/java-agent). Instead, it uses these two OpenTracing 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.
<Callout variant="tip">
<DoNotTranslate>**Supported OpenTracing Versions**</DoNotTranslate>
* <DoNotTranslate>**OpenTracing 0.31.0**</DoNotTranslate>:
* 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)
* <DoNotTranslate>**OpenTracing 0.32.0, 0.33.0**</DoNotTranslate>:
* 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)
</Callout>
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. The following [AWS console environment variables](https://docs.aws.amazon.com/amplify/latest/userguide/environment-variables.html) are required if you want your Lambda function to be included in [distributed tracing](/docs/apm/distributed-tracing/getting-started/introduction-distributed-tracing). This is recommended.
* `NEW_RELIC_ACCOUNT_ID`. Your [account ID](/docs/accounts/install-new-relic/account-setup/account-id).
* `NEW_RELIC_PRIMARY_APPLICATION_ID`. This is also your [account ID](/docs/accounts/install-new-relic/account-setup/account-id).
* `NEW_RELIC_TRUSTED_ACCOUNT_KEY`. This is also your [account ID](/docs/accounts/install-new-relic/account-setup/account-id). If your account is a child account, this must be the account ID for the root/parent account.
8. Optional: In the Lambda console, enable debug logging by adding this environment variable: `NEW_RELIC_DEBUG` is `true`.
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](/docs/serverless-function-monitoring/aws-lambda-monitoring/enable-lambda-monitoring/instrument-your-own/#manual-stream-logs).
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
<Collapser id="node" title="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. For example:
```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();
});
```
3. Optional: You can also add [custom events](/docs/using-new-relic/welcome-new-relic/getting-started/glossary#custom-event) to your Lambda using the [`recordCustomEvent` API](/docs/agents/nodejs-agent/api-guides/nodejs-agent-api#record_custom_event). For example:
```js
module.exports.handler = 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. In the AWS console, set these [environment variables](https://docs.aws.amazon.com/lambda/latest/dg/env_variables.html):
* `NEW_RELIC_NO_CONFIG_FILE`. Set to `true` if not using a configuration file.
* `NEW_RELIC_APP_NAME`: Your application name.
* `NEW_RELIC_ACCOUNT_ID`. Your [account ID](/docs/accounts/install-new-relic/account-setup/account-id).
* `NEW_RELIC_TRUSTED_ACCOUNT_KEY`. This is also your [account ID](/docs/accounts/install-new-relic/account-setup/account-id). If your account is a child account, this needs to be the account ID for the root/parent account.
7. Optional: To run the agent in serverless mode outside of AWS in a local environment, set the environment variable `NEW_RELIC_SERVERLESS_MODE_ENABLED` to `true`. (When executing this in an AWS Lambda environment, the agent will automatically run in serverless mode. <DoNotTranslate>**Do not use this variable if you're running in AWS**</DoNotTranslate>.)
8. Optional: To enable logging in serverless mode, set these environment variables:
* Set `NEW_RELIC_LOG_ENABLED` to `true`.
* Set `NEW_RELIC_LOG` to `stdout` for output to CloudWatch, or set to any writeable file location.
* `NEW_RELIC_LOG_LEVEL` is set to `info` by default, and it's only used when sending function logs in your Lambda. See [other log levels](/docs/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration#logging_config).
9. Optional: If your Lambda function is using ES Modules, set the environment variable `NEW_RELIC_USE_ESM` to `true`. Note that if using ES Modules, you must use async/await or promises for your function. Callback-based functions are not supported.
10. 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](/docs/serverless-function-monitoring/aws-lambda-monitoring/enable-lambda-monitoring/instrument-your-own/#manual-stream-logs).
Read more on how to [send function logs with Lambda](https://github.com/newrelic/newrelic-lambda-extension).
<Collapser id="python" title="Python"
To instrument your Python Lambda:
1. Download our Python agent package and place it in the same directory as your function. To do this, use pip:
```bash
pip install -t . newrelic
```
<Callout variant="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).
</Callout>
2. In your Lambda code, import the Python agent module and decorate the handler function using the New Relic decorator. <DoNotTranslate>**The New Relic package must be imported first in your code.**</DoNotTranslate> Here's an example:
```py
import newrelic.agent
newrelic.agent.initialize()
@newrelic.agent.lambda_handler()
def handler(event, context):
...
```
3. Optional: You can also add [custom events](/docs/using-new-relic/welcome-new-relic/getting-started/glossary#custom-event) to your Lambda using the [`record_custom_event` API](/docs/agents/python-agent/python-agent-api/record_custom_event). Here's an example:
```py
@newrelic.agent.lambda_handler()
def handler(event, context):
newrelic.agent.record_custom_event('CustomEvent', {'foo': 'bar'})
...
```
4. 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.
5. Upload the zipped file to your AWS Lambda account.
6. In the AWS console, set this [environment variable](https://docs.aws.amazon.com/lambda/latest/dg/env_variables.html):
* `NEW_RELIC_SERVERLESS_MODE_ENABLED`. Set to `true`
7. The following environment variables are not required for Lambda monitoring to function but they are required if you want your Lambda functions to be included in distributed traces. To enable [distributed tracing](/docs/apm/distributed-tracing/getting-started/introduction-distributed-tracing), set these [environment variables](https://docs.aws.amazon.com/amplify/latest/userguide/environment-variables.html) in the AWS console:
* `NEW_RELIC_DISTRIBUTED_TRACING_ENABLED`. Set to true.
* `NEW_RELIC_ACCOUNT_ID`. Your [account ID](/docs/accounts/install-new-relic/account-setup/account-id).
* `NEW_RELIC_TRUSTED_ACCOUNT_KEY`. This is also your [account ID](/docs/accounts/install-new-relic/account-setup/account-id). If your account is a child account, this needs to be the account ID for the root/parent account.
8. Optional: To configure logging, use the [`NEW_RELIC_LOG` and `NEW_RELIC_LOG_LEVEL` environment variables](/docs/agents/python-agent/configuration/python-agent-configuration#environment-variables) in the AWS Console.
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](/docs/serverless-function-monitoring/aws-lambda-monitoring/enable-lambda-monitoring/instrument-your-own/#manual-stream-logs).
<Collapser id="ruby" title="Ruby"
There are two ways to instrument your Ruby Lambda functions: automatically or manually.
Automatic instrumentation:
1. Download and install our Lambda CLI tool, [newrelic-lambda-cli](https://github.com/newrelic/newrelic-lambda-cli).
1. Use the tool to issue a `newrelic-lambda integrations install` command. See the [usage instructions](https://github.com/newrelic/newrelic-lambda-cli?tab=readme-ov-file#usage) for more information.
Manual instrumentation:
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.
1. In the default **Code** tab, scroll down to the **Layers** section and click on the **Add a layer** button.
1. Click the **Create layer** button.
1. Now go to the **Choose a layer** and select the **Specify an ARN** option.
1. Go to [New Relic's list of layers](https://layers.newrelic-external.com/) 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.
1. In the **Specify an ARN** section of the AWS console form, paste in the New Relic Lambda layer ARN.
1. On the AWS console form, click the **Add** button to add the layer to your Lambda function.
1. On your Lambda function's page, with the default **Code** tab selected, scroll down to the **Runtime settings** section and click the **Edit** button.
1. Make a safe copy of the existing **Handler** value. You'll need it for a later step.
1. Change the **Handler** value to: `newrelic_lambda_wrapper.handler` and click **Save**.
1. Switch to the **Configuration** tab on your Lambda function's page.
1. Select the **Environment variables** sub-tab.
1. Define the following environment variables:
* `NEW_RELIC_ACCOUNT_ID` Set to your New Relic [account ID](/docs/accounts/install-new-relic/account-setup/account-id)
* `NEW_RELIC_LAMBDA_HANDLER` Set to your function's original Handler value copied down in step 8 earlier
* `NEW_RELIC_LICENSE_KEY` Set to your New Relic license key
* `NEW_RELIC_LOG_ENDPOINT` Set to 'https://log-api.newrelic.com/log/v1'
* `NEW_RELIC_TELEMETRY_ENDPOINT` Set to 'https://cloud-collector.newrelic.com/aws/lambda/v1'
1. If you want to send your Lambda function's logs to New Relic, which will include everything your function writes to STDOUT, make sure you set the `NEW_RELIC_EXTENSION_SEND_FUNCTION_LOGS` environment variable to 'true'.