An AWS Lambda extension to collect, enhance, and transport telemetry data from your AWS Lambda functions to New Relic without requiring an external transport such as CloudWatch Logs or Kinesis.
This lightweight AWS Lambda Extension runs alongside your AWS Lambda functions and automatically handles the collection and transport of telemetry data from supported New Relic serverless agents. The extension requires a telemetry payload from a New Relic agent. Conditions that delay or prevent that payload from being written may result in longer-than-expected invocation durations.
To install the extension, simply include the layer with your instrumented Lambda function. The current layer ARN can be found here.
Note: This extension is included with all New Relic AWS Lambda layers going forward.
You'll also need to make the New Relic license key available to the extension. Use the New Relic Lambda CLI to install the managed secret, and then add the permission for the secret to your Lambda execution role.
newrelic-lambda integrations install \
--nr-account-id <account id> \
--nr-api-key <api key> \
--linked-account-name <linked account name> \
--enable-license-key-secret
Each of the example functions in the examples
directory has the appropriate license key secret permission.
After deploying your AWS Lambda function with one of the layer ARNs from the link above you should begin seeing telemetry data in New Relic.
See below for details on supported New Relic agents.
AWS's Extension API supports only a subset of all their runtimes. Notably absent as of this writing are Node JS before 10, Python before 3.7, Go (all versions), Dotnet before 3.1, and the older "java8" runtime, though "java8.al2" is supported.
For Go lambdas, we suggest using "provided" or "provided.al2". The Go example's deploy script contains compiler flags that produce a suitable self-hosting Go executable. See the Custom runtime docs for more details on this feature.
All of our layers include the extension, and the latest Agent version for the Layer's runtime. The latest
layer version ARNs for your runtime and region are available here. The
NewRelicLambdaExtension
layer is suitable for Go, Java and Dotnet.
Use the included Makefile
to compile the extension.
# build extension for x86_64 architecture
make dist-x86_64
# build extension for arm64 architecture
make dist-arm64
This creates the extension binary in ./extensions/newrelic-lambda-extension
. The binary is compiled for Amazon Linux, which is likely different from the platform you're working on.
To publish the extension to your AWS account, run the following command:
make publish
This packages the extension, and publishes a new layer version in your AWS account. Be sure that the AWS CLI is configured correctly. You can use the usual AWS CLI environment variables to control the account and region for the CLI.
This Lambda Extension will perform a series of checks on initialization to help customer troubleshoot configuration. Should any of
these checks fail, the extension wil attempt to output recommendations to both
CloudWatch Logs and New Relic Logs. If you have any issues using this extension, be sure
to check your logs for messages starting with Startup check warning:
for
troubleshooting recommendations. It is recommended to ignore all Extension checks after the lambda is successfully instrumented as mentioned here.
Startup checks include:
Check name | Description |
---|---|
agent | New Relic agent version check |
handler | Lambda handler configuration check |
sanity | Lambda environment variable, SSM, & Secrets Manager checks for license key |
vendor | If Vendored New Relic agent added along with layer check |
The New Relic Lambda Extension can also send your function's logs to New Relic. If you use the Lambda Extension, you can avoid the CloudWatch Logs ingest charge for telemetry gathered by New Relic. For additional Lambda Extension environment variables, you can refer to the docs. You can use the following extension environment variable for logging
Environment variable | Default value | Options | Description |
---|---|---|---|
NEW_RELIC_EXTENSION_SEND_FUNCTION_LOGS |
false |
true , false |
Send function logs to New Relic. |
NEW_RELIC_EXTENSION_LOGS_ENABLED |
true |
true , false |
Enable or disable [NR_EXT] log lines |
NR_TAGS |
Specify tags to be added to all log events. Optional. Each tag is composed of a colon-delimited key and value. Multiple key-value pairs are semicolon-delimited; for example, env:prod;team:myTeam. | ||
NR_ENV_DELIMITER |
Some users in UTF-8 environments might face difficulty in defining strings of NR_TAGS delimited by the semicolon ; character. Use NR_ENV_DELIMITER , to set custom delimiter for NR_TAGS . |
The New Relic Lambda Extension offers various features, which can be utilised by using the Lambda environment variables. These include:
Environment variable | Default value | Options | Description |
---|---|---|---|
NEW_RELIC_IGNORE_EXTENSION_CHECKS |
false |
all , agent , handler , sanity , vendor |
Ignore selected Extension Checks by using a comma-separated value, e.g., agent,handler , to ignore agent and handler checks. Use all to ignore all the Extension Checks as mentioned here. It is recommended to ignore all Extension checks after the lambda is successfully instrumented. |
NEW_RELIC_DATA_COLLECTION_TIMEOUT |
10s |
Time such as 5s . Valid time units are "ms", "s" |
Reduce time the Extension waits for sending telemetry. |
NEW_RELIC_LAMBDA_EXTENSION_ENABLED |
false |
true , false |
Disable the Extension. It is enabled by default |
To test locally, acquire the AWS extension test harness first. Then:
TODO: Link to the AWS SDK that has the test harness, assuming it gets published.
-
(Optional) Use the
newrelic-lambda
CLI to create the license key managed secret in your AWS account and region. -
Build the docker container for sample function code. Give it the tag
lambda_ext
.- Be sure to include your lambda function in the container.
-
Start up your container.
-
Using AWS Secret Manager
export AWS_ACCESS_KEY_ID=$(aws configure get aws_access_key_id --profile default) export AWS_SECRET_ACCESS_KEY=$(aws configure get aws_secret_access_key --profile default) export AWS_SESSION_TOKEN=$(aws configure get aws_session_token --profile default) docker run --rm -v $(pwd)/extensions:/opt/extensions -p 9001:8080 \ -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN \ lambda_ext:latest \ -h function.handler -c '{}' -t 60000
-
Or, setting the license key directly
docker run --rm \ -v $(pwd)/extensions:/opt/extensions \ -p 9001:8080 \ lambda_ext:latest \ -h function.handler -c '{"NEW_RELIC_LICENSE_KEY": "your-license-key-here"}' -t 60000
-
-
To invoke the sample lambda run:
curl -XPOST 'http://localhost:9001/2015-03-31/functions/function.handler/invocations' \ -d 'invoke-payload'
-
Finally, you can exercise the container shutdown lifecycle event with:
curl -XPOST 'http://localhost:9001/test/shutdown' \ -d '{"timeoutMs": 5000 }'
New Relic hosts and moderates an online forum where customers can interact with New Relic employees as well as other customers to get help and share best practices. Like all official New Relic open source projects, there's a related Community topic in the New Relic Explorers Hub. You can find this project's topic/threads in the Explorers Hub.
We encourage your contributions to improve newrelic-lambda-extension
! Keep in mind when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project.
If you have any questions, or to execute our corporate CLA, required if your contribution is on behalf of a company, please drop us an email at [email protected].
newrelic-lambda-extension
is licensed under the Apache 2.0 License. The newrelic-lambda-extension
also uses source code from third-party libraries. You can find full details on which libraries are used and the terms under which they are licensed in the third-party notices document.