Skip to content

Commit

Permalink
Merge pull request #18327 from keegoid-nr/patch-21
Browse files Browse the repository at this point in the history 
docs: improve Lambda monitoring steps
  • Loading branch information
@jeff-colucci
jeff-colucci committed Aug 10, 2024
2 parents 4d1e225 + c514bb6 commit 70027e3
Showing 1 changed file with 126 additions and 80 deletions.
206 changes: 126 additions & 80 deletions ...toring/aws-lambda-monitoring/instrument-lambda-function/introduction-lambda.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,122 +52,168 @@ We will show you to instrument your Lambda function using each method in our ins

Before enabling serverless monitoring using our Lambda layer, you'll need:

1. A New Relic account with either an admin role or have the **Infrastructure manager**[add-on role](/docs/accounts/original-accounts-billing/original-users-roles/users-roles-original-user-model#add-on).
1. A New Relic account with either an admin role or have the **Infrastructure manager** [add-on role](/docs/accounts/original-accounts-billing/original-users-roles/users-roles-original-user-model#add-on).
2. A <InlinePopover type="userKey" />.
3. An AWS account with permissions for creating IAM resources, managed secrets, and Lambdas. You also need permissions for creating CloudFormation stacks and S3 buckets.

Then you'll need to complete the following:

1. Install[AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) configure using `aws configure`. You will need an AWS Access Key ID and AWS Secret Access Key.
2. Install [Python](https://www.python.org/downloads/) version 3.3 or higher.
3. Install the [newrelic-lambda CLI](https://github.com/newrelic/newrelic-lambda-cli#installation). To install, run the following:
```bash
pip3 install newrelic-lambda-cli
```
4. By default, we use the AWS Managed Policy `ReadOnlyAccess`. This allows the Infrastructure integration to see
all the resources in your account, rather than just your Lambda functions and CloudWatch metrics. New Relic
recommends this default, but we understand that some organizations prefer a strict security posture for
third party integrations. If you'd like to limit New Relic's access, the IAM role can be granted with a minimum of these permissions:

```yaml
Resource: "*"
Action:
- "cloudwatch:GetMetricStatistics"
- "cloudwatch:ListMetrics"
- "cloudwatch:GetMetricData"
- "lambda:GetAccountSettings"
- "lambda:ListFunctions"
- "lambda:ListAliases"
- "lambda:ListTags"
- "lambda:ListEventSourceMappings"
```
5. Before running the CLI, you will need to grant New Relic a minimum of these permissions in AWS:

```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "CLIAccessPolicy",
"Action": [
"cloudformation:CreateChangeSet",
"cloudformation:CreateStack",
"cloudformation:DescribeStacks",
"cloudformation:ExecuteChangeSet",
"iam:AttachRolePolicy",
"iam:CreateRole",
"iam:GetRole",
"iam:PassRole",
"lambda:AddPermission",
"lambda:CreateFunction",
"lambda:GetFunction",
"logs:DeleteSubscriptionFilter",
"logs:DescribeSubscriptionFilters",
"logs:PutSubscriptionFilter",
"s3:GetObject",
"serverlessrepo:CreateCloudFormationChangeSet",
"secretsmanager:CreateSecret"
],
"Effect": "Allow",
"Resource": "*"
},
{
"Sid": "NRLogAccessPolicy",
"Effect": "Allow",
"Action": [
"serverlessrepo:CreateCloudFormationTemplate",
"serverlessrepo:GetCloudFormationTemplate"
],
"Resource": "arn:aws:serverlessrepo:us-east-1:463657938898:applications/NewRelic-log-ingestion"
}
]
}
```

If you'd like to learn more about our CLI, see [our CLI repo](https://github.com/newrelic/newrelic-lambda-cli#installation).
1. Install[AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) configure using `aws configure`. You will need an AWS Access Key ID and AWS Secret Access Key.
2. Install [Python](https://www.python.org/downloads/) version 3.3 or higher.
3. Install the [newrelic-lambda CLI](https://github.com/newrelic/newrelic-lambda-cli#installation). To install, run the following:
```bash
pip3 install newrelic-lambda-cli
```
4. By default, we use the AWS Managed Policy `ReadOnlyAccess`. This allows the Infrastructure integration to see
all the resources in your account, rather than just your Lambda functions and CloudWatch metrics. New Relic
recommends this default, but we understand that some organizations prefer a strict security posture for
third party integrations. If you'd like to limit New Relic's access, the IAM role can be granted with a minimum of these permissions:
```yaml
Resource: "*"
Action:
- "cloudwatch:GetMetricStatistics"
- "cloudwatch:ListMetrics"
- "cloudwatch:GetMetricData"
- "lambda:GetAccountSettings"
- "lambda:ListFunctions"
- "lambda:ListAliases"
- "lambda:ListTags"
- "lambda:ListEventSourceMappings"
```
5. Before running the CLI, you will need to grant New Relic a minimum of these permissions in AWS:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "CLIAccessPolicy",
"Action": [
"cloudformation:CreateChangeSet",
"cloudformation:CreateStack",
"cloudformation:DescribeStacks",
"cloudformation:ExecuteChangeSet",
"iam:AttachRolePolicy",
"iam:CreateRole",
"iam:GetRole",
"iam:PassRole",
"lambda:AddPermission",
"lambda:CreateFunction",
"lambda:GetFunction",
"logs:DeleteSubscriptionFilter",
"logs:DescribeSubscriptionFilters",
"logs:PutSubscriptionFilter",
"s3:GetObject",
"serverlessrepo:CreateCloudFormationChangeSet",
"secretsmanager:CreateSecret"
],
"Effect": "Allow",
"Resource": "*"
},
{
"Sid": "NRLogAccessPolicy",
"Effect": "Allow",
"Action": [
"serverlessrepo:CreateCloudFormationTemplate",
"serverlessrepo:GetCloudFormationTemplate"
],
"Resource": "arn:aws:serverlessrepo:us-east-1:463657938898:applications/NewRelic-log-ingestion"
}
]
}
```
If you'd like to learn more about our CLI, see [our CLI repo](https://github.com/newrelic/newrelic-lambda-cli#installation).

## Recommended AWS Lambda language runtimes [#recommended]

We recommend the following runtimes:

* Node.js: `nodejs16.x`, `nodejs18.x`, `nodejs20.x`
* Python: `python3.8`, `python3.9`, `python3.10`, `python3.11`, `python3.12`
* Go: `provided.al2`
* Java: `java8.al2`, `java11`, `java17`
* Go: `provided.al2`, `provided.al2023`
* Java: `java8.al2`, `java11`, `java17`, `java21`
* Ruby: `ruby3.2`, `ruby3.3`
* .NET: `dotnet6`, `dotnet8`

## Consider costs [#costs]

Enabling serverless monitoring for AWS Lambda may result in Amazon Web Services charges. Our `newrelic-log-ingestion` Lambda function, which reports your Lambda data to us, is considered a [Third Party Service](/docs/licenses/license-information/acceptable-use-policy/acceptable-use-policy): AWS charges resulting from your use of it are your responsibility.

If you use the [Lambda Extension](https://github.com/newrelic/newrelic-lambda-extension), you can avoid the CloudWatch Logs ingest charge for telemetry gathered by New Relic.
If you use our [newrelic-lambda-extension](https://github.com/newrelic/newrelic-lambda-extension) bundled in our [New Relic Lambda Layers](https://github.com/newrelic/newrelic-lambda-layers), you can avoid sending logs and telemetry via CloudWatch and the [newrelic-log-ingestion](https://github.com/newrelic/aws-log-ingestion) function. It's also possible to configure the [newrelic-log-ingestion](https://github.com/newrelic/aws-log-ingestion) function as a [CloudWatch fallback](/docs/serverless-function-monitoring/aws-lambda-monitoring/instrument-lambda-function/cloud-watch-fallback/) method for functions that require high availability of observability data.

## Link your AWS and New Relic accounts [#link]
## Install Lambda monitoring [#setup]

Lambda monitoring includes:

Before you can instrument your function, you will need to link your AWS account to New Relic. By linking accounts, you are granting New Relic permission to create an inventory of your AWS account and automatically gather CloudWatch metrics for your Lambda functions. After you've linked accounts, resources in your AWS account will appear as entities in the entity explorer.
* An AWS integration to ingest CloudWatch metrics and perform entity synthesis within New Relic.
* A New Relic agent operating in "serverless" mode, included in our [New Relic Lambda Layers](https://github.com/newrelic/newrelic-lambda-layers) or [in your deployment](/docs/serverless-function-monitoring/aws-lambda-monitoring/instrument-lambda-function/enable-serverless-monitoring-aws-lambda-layerless/).
* A method of sending "instrumented" payloads and optionally logs to New Relic via our [newrelic-log-ingestion](https://github.com/newrelic/aws-log-ingestion) function or [Extension](https://github.com/newrelic/newrelic-lambda-extension), also included in our [New Relic Lambda Layers](https://github.com/newrelic/newrelic-lambda-layers).

<Steps>
<Step>
## Instrument New Relic's Lambda layer with the `newrelic-lambda` CLI
## Link your AWS and New Relic accounts [#link]

Before you can receive telemetry for your "instrumented" Lambda function in New Relic, you will need to link your AWS account to New Relic. By linking accounts, you are granting New Relic permission to create an inventory of your AWS account and automatically gather CloudWatch metrics for your Lambda functions. After you've linked accounts, resources in your AWS account will appear as entities in the entity explorer. Lambda function entities will be found in the Serverless Functions view.

### Set up an AWS Metric Streams integration (recommended)

For New Relic to monitor your Lambda functions, you'll need to set up an integration between New Relic and AWS. We recommend using [Metric Streams](/docs/infrastructure/amazon-integrations/connect/aws-metric-stream) to help reduce latency and avoid throttling of our polling requests.

To instrument New Relic's Lambda layer, run:
### Set up an API Polling integration with AWS

```bash
If not using a Metric Streams integration, you can choose to set up an [API Polling](/docs/infrastructure/amazon-integrations/connect/connect-aws-new-relic-infrastructure-monitoring) integration instead. By default, an API Polling integration with the Lambda service enabled will poll every 5 minutes for CloudWatch metrics.

The [newrelic-lambda-cli](https://github.com/newrelic/newrelic-lambda-cli) can be used to set up an API Polling integration, but not a Metric Streams integration.

```sh
newrelic-lambda integrations install --nr-account-id YOUR_NR_ACCOUNT_ID \
--nr-api-key YOUR_NEW_RELIC_USER_KEY
```

The `newrelic-lambda` CLI adds New Relic as a secret in [AWS Secret Manager](https://aws.amazon.com/secrets-manager/) for greater security.
One step in the [integrations install command](https://github.com/newrelic/newrelic-lambda-cli?tab=readme-ov-file#aws-lambda-integration) will create a `NEW_RELIC_LICENSE_KEY` secret in [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) for improved security. This is configurable with a `--disable-license-key-secret` flag, along with other options and flags.
</Step>

<Step>
## Install Metric Streams [#metric-streams]
## Instrument your Lambda function [#instrument]

There are several ways to go about adding instrumentation to your Lambda function. For "no code change" instrumentation, use a New Relic layer. You can add the layer [added directly to your Lambda function](/docs/serverless-function-monitoring/aws-lambda-monitoring/instrument-lambda-function/instrument-your-own/) or [included in your dockerfile](/docs/serverless-function-monitoring/aws-lambda-monitoring/instrument-lambda-function/containerized-images/). Each layer, except the extension layer, includes an agent, handler wrapper, and extension for payload and log shipping.

The [newrelic-lambda-cli](https://github.com/newrelic/newrelic-lambda-cli) is the quickest and easiest method to add a [New Relic Lambda Layer](https://github.com/newrelic/newrelic-lambda-layers). It's often used for testing rather than for CI/CD.

To add a New Relic layer via your existing CI/CD pipeline, we have a [Serverless Framework plugin](https://github.com/newrelic/serverless-newrelic-lambda-layers) along with examples for [SAM and Terraform](https://github.com/newrelic/newrelic-lambda-extension/tree/main/examples).

For performance or to more tightly integrate New Relic with your function's code, you can alternatively use [layerless instrumentation](https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/instrument-lambda-function/enable-serverless-monitoring-aws-lambda-layerless/) for all runtimes except Ruby.
</Step>

<Step>
## Configure your Lambda function [#configure]

After instrumenting your function, check in the AWS console to ensure the configuration is correct.

Distributed tracing commonly needs three environment variables:

* `NEW_RELIC_ACCOUNT_ID`
* `NEW_RELIC_TRUSTED_ACCOUNT_KEY`
* `NEW_RELIC_DISTRIBUTED_TRACING_ENABLED`

For the extension, sending of function logs is disabled by default. Here are some popular environment variables:

* `NEW_RELIC_LICENSE_KEY` to override the secret in the AWS Secrets Manager. This is a good check in case the secret has been created with the wrong [ingest license key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#overview-keys).
* `NEW_RELIC_DATA_COLLECTION_TIMEOUT` to reduce time spent sending logs and payloads to New Relic when a timeout occurs. The default is `10s`.
* `NEW_RELIC_EXTENSION_SEND_FUNCTION_LOGS` to send function logs. The default is `false`.

For the Node.js agent:

* `NEW_RELIC_USE_ESM` if your function uses the ECMAScript standard instead of CommonJS. Make sure to [instrument your handler manually](https://github.com/newrelic/newrelic-lambda-layers?tab=readme-ov-file#manual-instrumentation-for-es-modules) to avoid performance impacts on cold starts.
* `NEW_RELIC_NATIVE_METRICS_ENABLED` should be disabled to avoid performance impacts. Instrumentation of native metrics are not needed in Lambda. Defaults to `true`.

For New Relic to monitor your Lambda function, you will need to install either [Metric Streams](/docs/infrastructure/amazon-integrations/connect/aws-metric-stream) or [API Polling](/docs/infrastructure/amazon-integrations/connect/connect-aws-new-relic-infrastructure-monitoring). We recommend using Metric Streams but you can let also let the CLI automatically install the API Polling integration for you.
For the Python agent:

If you'd like to use Metric Streams, install that now before running the CLI. You can install that using our [Connect AWS integrations using Metric Streams](docs/infrastructure/amazon-integrations/connect/aws-metric-stream/) documentation.
* `NEW_RELIC_PACKAGE_REPORTING_ENABLED` should be disabled to improve cold start performance. The package reporting feature is not needed in Lambda. Defaults to `true`.

See the next step for more commonly used environment variables by runtime.
</Step>

<Step>
Expand Down

0 comments on commit 70027e3

Please sign in to comment.