diff --git a/README.md b/README.md index 78faab3c..31bfebea 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ [![Build Status](https://apm-ci.elastic.co/buildStatus/icon?job=library%2Fapm-aws-lambda-mbp%2Fmain)](https://apm-ci.elastic.co/job/library/job/apm-aws-lambda-mbp/job/main/) -This repository contains code and tools for working with Elastic APM's AWS Lambda solution. +This repository contains code and tools for working with the Elastic APM AWS Lambda extension. -If you're looking to get started with Elastic's AWS Lambda extension and agent instrumentation, the [AWS Lambda Extension](https://www.elastic.co/guide/en/apm/guide/current/monitoring-aws-lambda.html) documentation is the place to start. +Ready to use Elastic APM to monitor your Lambda functions? See [Monitoring AWS Lambda Functions](https://www.elastic.co/guide/en/apm/guide/current/monitoring-aws-lambda.html) to get started. ### Update the docs diff --git a/apm-lambda-extension/DEVELOPMENT.md b/apm-lambda-extension/DEVELOPMENT.md index f2199203..bae1331f 100644 --- a/apm-lambda-extension/DEVELOPMENT.md +++ b/apm-lambda-extension/DEVELOPMENT.md @@ -3,7 +3,7 @@ ### :robot: Automatically -Releasing a version of the Lambda Extension requires a tag release. +Releasing a version of the Elastic APM AWS Lambda extension requires a tag release. Tag the release via your preferred tagging method. Tagging a release (v0.0.2) via the command line looks something like this. @@ -22,7 +22,7 @@ and a Release in the Github UI. ### :thumbsdown: Manually -Releasing a version of the Lambda Extension is currently a three step manual process. +Releasing a version of the Elastic APM AWS Lambda extension is currently a three step manual process. 1. Tag the Release 2. Create the Build Artifacts @@ -33,7 +33,7 @@ Releasing a version of the Lambda Extension is currently a three step manual pro See the above section regarding tagging a release. ### Create the Build Artifacts -Next, create the build artifacts for the release. These are go binaries of the Lambda Extension, built for both Intel and ARM architectures. +Next, create the build artifacts for the release. These are go binaries of the Elastic APM AWS Lambda extension, built for both Intel and ARM architectures. If you were creating the build artifacts for the v0.0.2 release, that might look something like this diff --git a/apm-lambda-extension/e2e-testing/README.md b/apm-lambda-extension/e2e-testing/README.md index ab43eda4..2237ec73 100644 --- a/apm-lambda-extension/e2e-testing/README.md +++ b/apm-lambda-extension/e2e-testing/README.md @@ -1,11 +1,11 @@ # End-to-End Testing -The file `e2e_test.go` contains an end-to-end test of the Elastic APM Lambda Extension. This test is built on top of the AWS SAM CLI, which allows running Lambda functions and their associated layers locally. +The file `e2e_test.go` contains an end-to-end test of the Elastic APM AWS Lambda extension. This test is built on top of the AWS SAM CLI, which allows running Lambda functions and their associated layers locally. ## Setup Since this test is sensibly longer than the other unit tests, it is disabled by default. To enable it, go to `.e2e_test_config` and set the environment variable `RUN_E2E_TESTS` to `true`. -In order to run the Lambda functions locally, the following dependencies must be installed : +In order to run the Lambda functions locally, the following dependencies must be installed : - [Install](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html) the SAM CLI. Creating an AWS account is actually not required. - Install Docker - Install a Go Runtime @@ -17,7 +17,7 @@ cd apm-lambda-extension/e2e-testing go test ``` -### Command line arguments +### Command line arguments The command line arguments are presented with their default value. ```shell -rebuild=false # Rebuilds the Lambda function images @@ -31,4 +31,3 @@ Example : ```shell go test -rebuild=false -lang=java -timer=40 -java-agent-ver=1.28.4 ``` - diff --git a/docs/add-extension/add-extension-layer.asciidoc b/docs/add-extension/add-extension-layer.asciidoc index c1c231c6..2c9d9b28 100644 --- a/docs/add-extension/add-extension-layer.asciidoc +++ b/docs/add-extension/add-extension-layer.asciidoc @@ -5,7 +5,7 @@ To add a layer to a Lambda function through the AWS Management Console: 1. Navigate to your function in the AWS Management Console 2. Scroll to the Layers section and click the _Add a layer_ button image:images/config-layer.png[image of layer configuration section in AWS Console] 3. Choose the _Specify an ARN_ radio button -4. Copy and paste the following ARN of the APM Lambda Extension layer in the _Specify an ARN_ text input: + +4. Copy and paste the following ARN of the {apm-lambda-ext} layer in the _Specify an ARN_ text input: + +++EXTENSION_ARN+++ image:images/choose-a-layer.png[image of choosing a layer in AWS Console] 5. Click the _Add_ button @@ -19,10 +19,10 @@ To add the layers to your Lambda function through the AWS Management Console: 1. Navigate to your function in the AWS Management Console 2. Scroll to the Layers section and click the _Add a layer_ button image:images/config-layer.png[image of layer configuration section in AWS Console] 3. Choose the _Specify an ARN_ radio button -4. Copy and paste the following ARNs of the APM Lambda Extension layer and the APM agent layer in the _Specify an ARN_ text input: + +4. Copy and paste the following ARNs of the {apm-lambda-ext} layer and the APM agent layer in the _Specify an ARN_ text input: + APM Extension layer: + +++EXTENSION_ARN+++ + -APM Agent layer: + +APM agent layer: + +++AGENT_ARN+++ image:images/choose-a-layer.png[image of choosing a layer in AWS Console] 5. Click the _Add_ button @@ -31,7 +31,7 @@ image:images/choose-a-layer.png[image of choosing a layer in AWS Console] // tag::cli-extension-only[] -To add the APM Extension Layer ARN through the AWS command line interface execute the following command: +To add the {apm-lambda-ext} Layer ARN through the AWS command line interface execute the following command: [source,bash] ---- @@ -43,7 +43,7 @@ aws lambda update-function-configuration --function-name yourLambdaFunctionName // tag::cli-with-agent[] -To add the Layer ARNs of the APM Extension and the APM Agent through the AWS command line interface execute the following command: +To add the Layer ARNs of the {apm-lambda-ext} and the APM agent through the AWS command line interface execute the following command: [source,bash] ---- @@ -56,7 +56,7 @@ AGENT_ARN // tag::sam-extension-only[] -In your SAM `template.yml` file add the APM Extension Layer ARN as follows: +In your SAM `template.yml` file add the {apm-lambda-ext} Layer ARN as follows: [source,yml] ---- @@ -75,7 +75,7 @@ Resources: // tag::sam-with-agent[] -In your SAM `template.yml` file add the Layer ARNs of the APM Extension and the APM Agent as follows: +In your SAM `template.yml` file add the Layer ARNs of the {apm-lambda-ext} and the APM agent as follows: [source,yml] ---- @@ -95,7 +95,7 @@ Resources: // tag::serverless-extension-only[] -In your `serverless.yml` file add the APM Extension Layer ARN to your function as follows: +In your `serverless.yml` file add the {apm-lambda-ext} Layer ARN to your function as follows: [source,yml] ---- @@ -112,7 +112,7 @@ functions: // tag::serverless-with-agent[] -In your `serverless.yml` file add the Layer ARNs of the APM Extension and the APM Agent to your function as follows: +In your `serverless.yml` file add the Layer ARNs of the {apm-lambda-ext} and the APM agent to your function as follows: [source,yml] ---- @@ -129,7 +129,7 @@ functions: // end::serverless-with-agent[] // tag::terraform-extension-only[] -To add the APM Extension Layer to your function add the ARN to the `layers` property in your Terraform file: +To add the {apm-lambda-ext} Layer to your function add the ARN to the `layers` property in your Terraform file: [source,terraform] ---- @@ -144,7 +144,7 @@ resource "aws_lambda_function" "your_lambda_function" { // end::terraform-extension-only[] // tag::terraform-with-agent[] -To add the APM Extension and the APM Agent to your function add the ARNs to the `layers` property in your Terraform file: +To add the{apm-lambda-ext} and the APM agent to your function add the ARNs to the `layers` property in your Terraform file: [source,terraform] ---- @@ -159,7 +159,7 @@ resource "aws_lambda_function" "your_lambda_function" { // end::terraform-with-agent[] // tag::container-extension-only[] -To add the APM Extension to your container-based function extend the Dockerfile of your function image as follows: +To add the {apm-lambda-ext} to your container-based function extend the Dockerfile of your function image as follows: [source,Dockerfile] ---- @@ -174,7 +174,7 @@ COPY --from=lambda-extension /opt/elastic-apm-extension /opt/extensions/elastic- // end::container-extension-only[] // tag::container-with-agent[] -To add the APM Extension and the APM Agent to your container-based function extend the Dockerfile of your function image as follows: +To add the {apm-lambda-ext} and the APM agent to your container-based function extend the Dockerfile of your function image as follows: [source,Dockerfile] ---- diff --git a/docs/monitoring-aws-lambda.asciidoc b/docs/monitoring-aws-lambda.asciidoc index 5a81165b..256610cb 100644 --- a/docs/monitoring-aws-lambda.asciidoc +++ b/docs/monitoring-aws-lambda.asciidoc @@ -20,58 +20,58 @@ AWS Lambda uses a special execution model to provide a scalable, on-demand compu 1. To avoid data loss, APM data collected by APM agents needs to be flushed before the execution environment of a lambda function is frozen. 2. Flushing APM data must be fast so as not to impact the response times of lambda function requests. -To accomplish the above, Elastic's APM Agents instrument AWS Lambda functions and dispatch APM data via an https://docs.aws.amazon.com/lambda/latest/dg/using-extensions.html[AWS Lambda Extension]. +To accomplish the above, Elastic APM agents instrument AWS Lambda functions and dispatch APM data via an https://docs.aws.amazon.com/lambda/latest/dg/using-extensions.html[AWS Lambda extension]. -Normally, during the execution of a Lambda function, there's only a single language process running in the AWS Lambda execution environment. With an AWS Lambda Extension, Lambda users run a _second_ process alongside their main service/application process. +Normally, during the execution of a Lambda function, there's only a single language process running in the AWS Lambda execution environment. With an AWS Lambda extension, Lambda users run a _second_ process alongside their main service/application process. image:images/architecture-white.png[image showing data flow from lambda function, to extension, to APM Server] -By using an AWS Lambda Extension, Elastic APM Agents can send data to a local Lambda Extension process, and that process will forward data on to APM Server asynchronously. The Lambda Extension ensures that any potential latency between the Lambda function and the APM Server instance will not cause latency in the request flow of the Lambda function itself. +By using an AWS Lambda extension, Elastic APM agents can send data to a local Lambda extension process, and that process will forward data on to APM Server asynchronously. The Lambda extension ensures that any potential latency between the Lambda function and the APM Server instance will not cause latency in the request flow of the Lambda function itself. [[aws-lambda-config-options]] -== Configuration Options for APM on AWS Lambda +== Configuration options -The recommended way of configuring the APM Lambda Extension and the APM Agents on AWS Lambda is through the Lambda function's environment variables. +The recommended way of configuring the {apm-lambda-ext} and the APM agents on AWS Lambda is through the Lambda function's environment variables. -The configuration options for the APM Agents are documented in the corresponding language agents: +The configuration options for the APM agents are documented in the corresponding language agents: -* {apm-node-ref}/configuration.html[Configuration options - Node.js APM Agent] -* {apm-py-ref}/configuration.html[Configuration options - Python APM Agent] -* {apm-java-ref}/configuration.html[Configuration options - Java APM Agent] +* {apm-node-ref}/configuration.html[Configuration options - Node.js APM agent] +* {apm-py-ref}/configuration.html[Configuration options - Python APM agent] +* {apm-java-ref}/configuration.html[Configuration options - Java APM agent] -The following configuration options are particularly relevant for Elastic's APM on AWS Lambda: +The following configuration options are particularly relevant for the {apm-lambda-ext}: [[aws-lambda-extension]] === `ELASTIC_APM_LAMBDA_APM_SERVER` -This required config option controls where the Lambda extension will ship data. This should be the URL of the final APM Server destination for your telemetry. +This required config option controls where the {apm-lambda-ext} will ship data. This should be the URL of the final APM Server destination for your telemetry. [[aws-lambda-config-authentication-keys]] === `ELASTIC_APM_SECRET_TOKEN` or `ELASTIC_APM_API_KEY` -One of these (or, alternatively, the corresponding settings for the AWS Secrets Manager IDs) needs to be set as the authentication method that the extension uses when sending data to the URL configured via `ELASTIC_APM_LAMBDA_APM_SERVER`. Alternatively, you can store your APM Server credentials <> and use the <> config options, instead. Sending data to the APM Server if none of these options is set is possible, but your APM agent must be allowed to send data to your APM server in https://www.elastic.co/guide/en/apm/guide/current/configuration-anonymous.html[anonymous mode]. +One of these (or, alternatively, the corresponding settings for the AWS Secrets Manager IDs) needs to be set as the authentication method that the {apm-lambda-ext} uses when sending data to the URL configured via `ELASTIC_APM_LAMBDA_APM_SERVER`. Alternatively, you can store your APM Server credentials <> and use the <> config options, instead. Sending data to the APM Server if none of these options is set is possible, but your APM agent must be allowed to send data to your APM server in https://www.elastic.co/guide/en/apm/guide/current/configuration-anonymous.html[anonymous mode]. [[aws-lambda-config-secrets-manager-options]] === `ELASTIC_APM_SECRETS_MANAGER_SECRET_TOKEN_ID` or `ELASTIC_APM_SECRETS_MANAGER_API_KEY_ID` -Instead of specifying the <> as plain text in your Lambda environment variables, you can <> to securely store your APM authetication keys. The `ELASTIC_APM_SECRETS_MANAGER_API_KEY_ID` or `ELASTIC_APM_SECRETS_MANAGER_SECRET_TOKEN_ID` config options allow you to specify the Secrets Manager's secret id of the stored APM API key or APM secret token, respectively, to be used by the APM Lambda Extension for authentication. +Instead of specifying the <> as plain text in your Lambda environment variables, you can <> to securely store your APM authetication keys. The `ELASTIC_APM_SECRETS_MANAGER_API_KEY_ID` or `ELASTIC_APM_SECRETS_MANAGER_SECRET_TOKEN_ID` config options allow you to specify the Secrets Manager's secret id of the stored APM API key or APM secret token, respectively, to be used by the {apm-lambda-ext} for authentication. `ELASTIC_APM_SECRETS_MANAGER_SECRET_TOKEN_ID` takes precedence over <>, and `ELASTIC_APM_SECRETS_MANAGER_API_KEY_ID` over <>, respectively. === `ELASTIC_APM_SERVICE_NAME` -The configured name of your application or service. The APM Agent will use this value when reporting data to the APM Server. If unset, the APM Agent will automatically set the value based on the Lambda function name. Use this config option if you want to group multiple Lambda functions under a single service entity in APM. +The configured name of your application or service. The APM agent will use this value when reporting data to the APM Server. If unset, the APM agent will automatically set the value based on the Lambda function name. Use this config option if you want to group multiple Lambda functions under a single service entity in APM. === `ELASTIC_APM_DATA_RECEIVER_TIMEOUT_SECONDS` -The APM Lambda Extension's timeout value, in seconds, for receiving data from the APM Agent. The _default_ is `15`. +The {apm-lambda-ext}'s timeout value, in seconds, for receiving data from the APM agent. The _default_ is `15`. === `ELASTIC_APM_DATA_RECEIVER_SERVER_PORT` -The port on which the APM Lambda Extension listens to receive data from the APM Agent. The _default_ is `8200`. +The port on which the {apm-lambda-ext} listens to receive data from the APM agent. The _default_ is `8200`. === `ELASTIC_APM_DATA_FORWARDER_TIMEOUT_SECONDS` -The timeout value, in seconds, for the Lambda Extension's HTTP client sending data to the APM Server. The _default_ is `3`. If the Extension's attempt to send APM data during this time interval is not successful, the extension queues back the data. Further attempts at sending the data are governed by an exponential backoff algorithm: data will be sent after a increasingly large grace period of 0, then circa 1, 4, 9, 16, 25 and 36 seconds, provided that the Lambda function execution is ongoing. +The timeout value, in seconds, for the {apm-lambda-ext}'s HTTP client sending data to the APM Server. The _default_ is `3`. If the extension's attempt to send APM data during this time interval is not successful, the extension queues back the data. Further attempts at sending the data are governed by an exponential backoff algorithm: data will be sent after a increasingly large grace period of 0, then circa 1, 4, 9, 16, 25 and 36 seconds, provided that the Lambda function execution is ongoing. === `ELASTIC_APM_SEND_STRATEGY` -Whether to synchronously flush APM agent data from the extension to the APM Server at the end of the function invocation. +Whether to synchronously flush APM agent data from the {apm-lambda-ext} to the APM Server at the end of the function invocation. The two accepted values are `background` and `syncflush`. The _default_ is `syncflush`. -* The `background` strategy indicates that the extension will not flush when it receives a signal that the function invocation +* The `background` strategy indicates that the {apm-lambda-ext} will not flush when it receives a signal that the function invocation has completed. It will instead send any remaining buffered data on the next function invocation. The result is that, if the function is not subsequently invoked for that Lambda environment, the buffered data will be lost. However, for lambda functions that have a steadily frequent load pattern the extension could delay sending the data to the APM Server to the next lambda @@ -83,21 +83,21 @@ the next request until the extension has flushed all the data. This has a negati though it ensures that all APM data is sent to the APM server. === `ELASTIC_APM_LOG_LEVEL` -The logging level to be used by both the APM Agent and the Lambda Extension. Supported values are `trace`, `debug`, `info`, `warning`, `error`, `critical` and `off`. +The logging level to be used by both the APM Agent and the {apm-lambda-ext}. Supported values are `trace`, `debug`, `info`, `warning`, `error`, `critical` and `off`. [[aws-lambda-secrets-manager]] == Using AWS Secrets Manager to manage APM authentication keys -When using the config options <> for authentication of the APM Lambda Extension with Elastic APM, the corresponding keys are specified in plain text in the environment variables of your Lambda function. If you prefer to securely store the authentication keys, you can use the AWS Secrets Manager and let the APM Lambda Extension retrieve the actual keys from the AWS Secrets Manager. Follow the instructions below to set up the AWS Secrets Manager with the APM Lambda Extension. +When using the config options <> for authentication of the {apm-lambda-ext}, the corresponding keys are specified in plain text in the environment variables of your Lambda function. If you prefer to securely store the authentication keys, you can use the AWS Secrets Manager and let the extension retrieve the actual keys from the AWS Secrets Manager. Follow the instructions below to set up the AWS Secrets Manager with the extension. [[aws-lambda-secrets-manager-create-secret]] === Step 1: Create a secret in the AWS Secrets Manager. -https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html[Create a secret in the AWS Secrets Manager] for the {apm-guide-ref}/secret-token.html[APM Secret Token] or the {apm-guide-ref}/api-key.html[APM API key], depending on which one you prefer to use. Make sure to create the secret as a *Plaintext* typed secret and ensure it is created *in the same AWS region* as your target Lambda function that will use the secret. +https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html[Create a secret in the AWS Secrets Manager] for the {apm-guide-ref}/secret-token.html[APM Secret Token] or the {apm-guide-ref}/api-key.html[APM API key], depending on which one you prefer to use. Make sure to create the secret as a *Plaintext* typed secret and ensure it is created *in the same AWS region* as your target Lambda function that will use the secret. We recommend using the AWS-managed encryption key `aws/secretsmanager`. However, you can optionally create and select a custom KMS key for encryption. Note that with a custom encryption key, you will need additional key permissions on your Lambda function (see <>). include::./secrets-manager/create-secret-widget.asciidoc[] -Remember your chosen secret name. You will use the secret name as the value for the config options <> when configuring your APM Lambda Extension. +Remember your chosen secret name. You will use the secret name as the value for the config options <> when configuring your {apm-lambda-ext}. [[aws-lambda-secrets-manager-permissions]] === Step 2: Add permissions to your AWS Lambda function @@ -105,10 +105,10 @@ For your Lambda function to be able to retrieve the authentication key from the include::./secrets-manager/add-permissions-widget.asciidoc[] -=== Step 3: Configure the APM Lambda extension -Finally, you will need to configure the APM Lambda extension to use the secret from the Secrets Manager _instead of_ the value provided through <>. +=== Step 3: Configure the {apm-lambda-ext} +Finally, you will need to configure the {apm-lambda-ext} to use the secret from the Secrets Manager _instead of_ the value provided through <>. -Provide the name of the secret you created in <> as the value for the <> config option, respectively, depending on whether you want to use the {apm-guide-ref}/secret-token.html[APM Secret Token] or the {apm-guide-ref}/api-key.html[APM API key]. +Provide the name of the secret you created in <> as the value for the <> config option, respectively, depending on whether you want to use the {apm-guide-ref}/secret-token.html[APM Secret Token] or the {apm-guide-ref}/api-key.html[APM API key]. The language-specific instructions describe how to set environment variables for configuring AWS Lambda for Elastic APM: @@ -116,7 +116,7 @@ The language-specific instructions describe how to set environment variables for * {apm-py-ref}/lambda-support.html#_step_3_configure_apm_on_aws_lambda[Configure APM on AWS Lambda - Python] * {apm-java-ref}/aws-lambda.html#_step_3_configure_apm_on_aws_lambda[Configure APM on AWS Lambda - Java] -That's it. With the first invocation (cold start) of your Lambda function you should see a log message from the APM Lambda extension indicating that a secret from the secrets manager is used: +That's it. With the first invocation (cold start) of your Lambda function you should see a log message from the {apm-lambda-ext} indicating that a secret from the secrets manager is used: [source, yml] ----