Beta test instructions for observing Ruby based AWS Lambda functions with New Relic

README.md

Beta test instructions for observing Ruby based AWS Lambda functions with New Relic

Synopsis

These instructions will explain how to enhance an existing Ruby based AWS Lambda function to have it observed by New Relic.

No Ruby expertise will be required, and any existing Ruby based AWS Lambda functions being observed will not need to have their source code altered.

The observability works through the association of an AWS Lamdba layer with any Lambda function that needs to be observed.

The Lambda layer delivers a copy of the latest New Relic Ruby APM agent, a Lambda extension that runs alongside the observed function and relays observability data from the agent to New Relic's servers, and a small Ruby wrapper script.

In the future, all of these instructions can optionally be automated with the use of the New Relic Lambda CLI tool once it has been updated to support Ruby functions.

NOTE: Given the beta test nature of these instructions, you may wish to make a copy of any existing functions and modify the copies for testing purposes instead of directly modifying the originals.

NOTE: AWS recently introduced support for Ruby 3.3. These instructions will work for 3.3 and 3.2. Be sure to select the appropriate .zip file that matches your Ruby runtime.

Prerequisites

The instructions will require sufficient AWS admin privileges to perform the following:

• Creating a new AWS Lambda layer from a .zip file
• Updating the configuration of any existing Lambda function to be observed

Additionally, the following pieces of information will be required:

• A New Relic account id
• A New Relic license key

Create a Lambda layer

New Relic will eventually publish Ruby AWS Lambda layers for public consumption as it does for Java, Node.js, and Python. For now, customers can create their own AWS Lambda layer by uploading one of the provided .zip files. Two .zip files are provided; one each for the x86 and arm architectures. Use either one or both depending on the architecture needs of your Lambda functions.

1. From the Lamdba section of the AWS console, select "Layers" from the "Additional resources" menu on the left
2. Click on the "Create layer" button
3. Fill out the "Create layer" form and then click "Create"

• Use a suitable "Name"
• Select "Upload a .zip file"
• Click the "Upload" button and select the appropriate New Relic provided layer .zip file
• Checkmark the lone appropriate architecture that matches the .zip file
• Select the appropriate Ruby runtime from the "Compatible runtimes" drop-down list

Modify an existing Lambda function to use the New Relic layer

Each existing Lambda function that is to be observed by New Relic will need to be set up to use the New Relic layer that was created from a .zip file.

1. From the Lambda section of the AWS console, select "Functions" from the main menu on the left
2. Click on an existing function
3. Click on the "Layers" box to jump to or manually scroll down to the "Layers" section of the "Code" tab
4. Click on "Add a layer"
5. Checkmark "Custom layers"
6. Select the New Relic layer that was created from a .zip file using the "Custom layers" drop-down list
7. Click on "Add" to add the layer to the function

Modify the handler of an existing Lambda function

1. From the Lambda section of the AWS console, select "Functions" from the main menu on the left
2. Click on an existing function
3. Select the "Code" tab
4. Scroll down to the "Runtime settings" section and click on the "Edit" button
5. IMPORTANT: make an offline copy of the existing "Handler" value
6. Change the "Handler" value to read "newrelic_lambda_wrapper.handler" and click "Save"

Add environment variables to an existing Lambda function

1. From the Lambda section of the AWS console, select "Functions" from the main menu on the left
2. Click on an existing function
3. Select the "Configuration" tab
4. Select the "Environment variables" sub-tab
5. Define the following environment variables

Variable	Value
NEW_RELIC_ACCOUNT_ID	(YOUR NEW RELIC ACCOUNT ID)
NEW_RELIC_LAMBDA_HANDLER	(YOUR HANDLER)*
NEW_RELIC_LICENSE_KEY	(YOUR NEW RELIC LICENSE KEY)
NEW_RELIC_LOG_ENDPOINT	https://log-api.newrelic.com/log/v1
NEW_RELIC_TELEMETRY_ENDPOINT	https://cloud-collector.newrelic.com/aws/lambda/v1

• For the NEW_RELIC_LAMBDA_HANDLER value, use the original handler value that was copied down earlier (see "Modify the handler of an existing Lambda function" above). example: 'lambda_function.lambda_handler'

Reporting Logs to New Relic

Optionally, the Lambda extension included in the Lambda layer can be configured to forward the function's logs to New Relic. These logs will include anything that the function writes to STDOUT. To have the function's logs sent to New Relic, add a new NEW_RELIC_EXTENSION_SEND_FUNCTION_LOGS environment variable with a value of true.

NOTE: The New Relic Ruby agent will itself produce some log output at a default log level of info. This log level can be raised to warn or error if you desire less verbosity. To set the agent's log level, add a new NEW_RELIC_LOG_LEVEL environment variable with the desired log level value.

NOTE: The New Relic Lambda extension will itself produce some log output. To prevent the extension from producing log output, add a NEW_RELIC_EXTENSION_LOGS_ENABLED environment variable with a value of true.

NOTE: In a non-Lambda server based context for something like a Ruby on Rails application, the application's logs can be forwarded to New Relic as long as the logger class involved is of or inherits from the Ruby Logger class. This type of application log forwarding is not currently supported in a serverless context. Only the function's AWS logs can be forwarded.

Reporting Errors to New Relic

If the Lambda function raises an exception that is not rescued, the Ruby agent will notice this and report the exception to New Relic. It will appear in the "Errors" tab of the function's page in the New Relic web UI. If the Lambda function rescues an exception (preventing the overall function invocation from crashing), then the exception will not be noticed by New Relic. Only unhandled exceptions will be noticed.

Using newrelic_rpm in Your Function

New Relic's Lambda layer provides the New Relic Ruby agent gem, newrelic_rpm, and will have already performed a require on the gem prior the start of the Lambda function's invocation. To prevent conflicts, do not include the gem in any other layers used by the function and do not perform any require statements for it.

Some New Relic layers for other languages include custom logic to detect and warn about the presence of agent code existing in other layers. The Ruby layer does not perform such detection at this time, so any conflicts must be manually detected.

Testing

If all of the above steps have been completed and the integration is successful, then any updated Lambda functions should continue to run successfully and return the same expected output as usual. Observability data for the updated function(s) should appear in the New Relic UI. To troubleshoot the absence of expected instrumentation, the NEW_RELIC_LOG_LEVEL environment variable can be added to the function's configuration with a value of debug.

Removing New Relic from Lambda functions

To revert back to not using New Relic, simply repeat the steps outlined in the "Modify the handler of an existing Lambda function" section and put the original handler string back in place. Optionally remove the New Relic Lambda layer and environment variables. They will be ignored without the New Relic handler string in place.

ruby32.arm64_v0.75.zip

ruby32.x86_64_v0.75.zip

ruby33.arm64_v0.75.zip

ruby33.x86_64_v0.75.zip