+++++
\ No newline at end of file
diff --git a/docs/lambda/configure-lambda.asciidoc b/docs/lambda/configure-lambda.asciidoc
new file mode 100644
index 0000000000..6110c37f6a
--- /dev/null
+++ b/docs/lambda/configure-lambda.asciidoc
@@ -0,0 +1,95 @@
+// tag::console-with-agent[]
+
+To configure APM through the AWS Management Console:
+
+1. Navigate to your function in the AWS Management Console
+2. Click on the _Configuration_ tab
+3. Click on _Environment variables_
+4. Add the following required variables:
+
+[source,bash]
+----
+AWS_LAMBDA_EXEC_WRAPPER = /opt/elastic-apm-handler # use this exact fixed value
+ELASTIC_APM_LAMBDA_APM_SERVER = # this is your APM Server URL
+ELASTIC_APM_SECRET_TOKEN = # this is your APM secret token
+----
+
+--
+include::{apm-aws-lambda-root}/docs/images/images.asciidoc[tag=java-env-vars]
+--
+
+// end::console-with-agent[]
+
+// tag::cli-with-agent[]
+
+To configure APM through the AWS command line interface execute the following command:
+
+[source,bash]
+----
+aws lambda update-function-configuration --function-name yourLambdaFunctionName \
+ --environment "Variables={AWS_LAMBDA_EXEC_WRAPPER=/opt/elastic-apm-handler,ELASTIC_APM_LAMBDA_APM_SERVER=,ELASTIC_APM_SECRET_TOKEN=}"
+----
+
+// end::cli-with-agent[]
+
+// tag::sam-with-agent[]
+
+In your SAM `template.yml` file add the Layer ARNs of the APM Extension and the APM Agent as follows:
+
+[source,yml]
+----
+...
+Resources:
+ yourLambdaFunction:
+ Type: AWS::Serverless::Function
+ Properties:
+ ...
+ Environment:
+ Variables:
+ AWS_LAMBDA_EXEC_WRAPPER: /opt/elastic-apm-handler
+ ELASTIC_APM_LAMBDA_APM_SERVER:
+ ELASTIC_APM_SECRET_TOKEN:
+...
+----
+
+// end::sam-with-agent[]
+
+// 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:
+
+[source,yml]
+----
+...
+functions:
+ yourLambdaFunction:
+ ...
+ environment:
+ AWS_LAMBDA_EXEC_WRAPPER: /opt/elastic-apm-handler
+ ELASTIC_APM_LAMBDA_APM_SERVER:
+ ELASTIC_APM_SECRET_TOKEN:
+...
+----
+
+// end::serverless-with-agent[]
+
+// 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:
+
+[source,terraform]
+----
+...
+resource "aws_lambda_function" "your_lambda_function" {
+ ...
+ environment {
+ variables = {
+ AWS_LAMBDA_EXEC_WRAPPER = "/opt/elastic-apm-handler"
+ ELASTIC_APM_LAMBDA_APM_SERVER = ""
+ ELASTIC_APM_SECRET_TOKEN = ""
+ }
+ }
+}
+...
+----
+
+// end::terraform-with-agent[]
diff --git a/docs/lambda/java-arn-replacement.asciidoc b/docs/lambda/java-arn-replacement.asciidoc
new file mode 100644
index 0000000000..42242f3fc9
--- /dev/null
+++ b/docs/lambda/java-arn-replacement.asciidoc
@@ -0,0 +1,7 @@
+++++
+
+++++
diff --git a/docs/setup-aws-lambda.asciidoc b/docs/setup-aws-lambda.asciidoc
index d2ddd92eda..51131c1545 100644
--- a/docs/setup-aws-lambda.asciidoc
+++ b/docs/setup-aws-lambda.asciidoc
@@ -1,81 +1,64 @@
[[aws-lambda]]
-=== Get started with Lambda
+=== Monitoring AWS Lambda Java Functions
+:layer-section-type: with-agent
-Getting Elastic APM set up for your lambda functions is easy,
-and there are various ways you can tweak it to fit your needs.
-
-NOTE: In order to get the full AWS Lambda tracing capabilities, use with APM Server 7.16 or higher. Using
-older versions provides most value, but some relevant metadata fields will not be indexed.
+The Java APM Agent can be used with AWS Lambda to monitor the execution of your AWS Lambda functions.
[float]
-[[aws-lambda-runtimes]]
-==== Supported runtimes
-
-AWS Lambda provides multiple https://docs.aws.amazon.com/lambda/latest/dg/java-image.html[JVM base images], only the ones that support the `AWS_LAMBDA_EXEC_WRAPPER` environment variables
-are supported out of the box.
-
-Running with unsupported images is still possible but requires providing agent configuration through environment variables
-explicitly.
+[[aws-lambda-java-quick-start]]
+=== Quick Start
-|===
-|Tags |Java Runtime |Operating System|Supported
+To get started with APM for your Java AWS Lambda functions, follow the steps below.
-|11
-|Java 11 (Corretto)
-|Amazon Linux 2
-|yes
+[float]
+[[aws-lambda-java-prerequisites]]
+==== Prerequisites
-|8.al2
-|Java 8 (Corretto)
-|Amazon Linux 2
-|yes
+. You need an APM Server to send APM data to. Follow the {apm-guide-ref}/apm-quick-start.html[APM Quick start] if you have not set one up yet. For the best-possible performance, we recommend setting up APM on {ecloud} in the same AWS region as your AWS Lambda functions.
+. Make sure you are using one of the supported AWS Lambda Java runtimes:
++
+--
+include::supported-technologies.asciidoc[tag=aws-lambda-runtimes]
+--
-|8
-|Java 8 (OpenJDK)
-|Amazon Linux 2018.03
-|no
+[float]
+==== Step 1: Select the AWS Region and Architecture
-|===
+include::{apm-aws-lambda-root}/docs/lambda-selector/lambda-attributes-selector.asciidoc[]
[float]
-[[aws-lambda-installation]]
-==== Installation
+==== Step 2: Add the APM Layers to your Lambda function
-Setting up APM for your Java Lambda function is a two-step process. Make sure to follow _both_ of the following steps:
+include::{apm-aws-lambda-root}/docs/lambda-selector/extension-arn-replacement.asciidoc[]
+include::./lambda/java-arn-replacement.asciidoc[]
-1. <>
-2. <>
+Both the {apm-guide-ref}/aws-lambda-arch.html[APM Lambda Extension] and the Java APM Agent are added to your Lambda function as https://docs.aws.amazon.com/lambda/latest/dg/invocation-layers.html[AWS Lambda Layers]. Therefore, you need to add the corresponding Layer ARNs (identifiers) to your Lambda function.
+
+include::{apm-aws-lambda-root}/docs/add-extension/add-extension-layer-widget.asciidoc[]
[float]
-[[aws-lambda-extension]]
-==== Install the Elastic APM Lambda extension
+==== Step 3: Configure APM on AWS Lambda
-Elastic uses a Lambda extension to forward data to an APM Server in a way that does not interfere with the execution of your Lambda function.
+The APM Lambda Extension and the APM Java agent are configured through environment variables on the AWS Lambda function.
-Follow the https://www.elastic.co/guide/en/apm/guide/current/aws-lambda-extension.html[installation documentation for the extension] to setup the Elastic APM Lambda extension for your Lambda function.
+For the minimal configuration, you will need the _APM Server URL_ to set the destination for APM data and an _{apm-guide-ref}/secret-token.html[APM Secret Token]_.
+If you prefer to use an {apm-guide-ref}/api-key.html[APM API key] instead of the APM secret token, use the `ELASTIC_APM_API_KEY` environment variable instead of `ELASTIC_APM_SECRET_TOKEN` in the following configuration.
-[float]
-[[aws-lambda-instrumenting]]
-==== Install the Elastic APM Java Agent Layer
+include::./lambda/configure-lambda-widget.asciidoc[]
-The Java Agent is installed as an AWS Layer.
+You can optionally <> or the {apm-guide-ref}/aws-lambda-config-options.html[configuration of the APM Lambda Extension].
-1. Pick the right ARN from the https://github.com/elastic/apm-agent-java/releases[ARN table for the APM Java Agent Lambda Layer]. Note: The APM Java Agent Layer needs to be in the _same region_ as your Lambda function.
-2. Navigate to your function in the AWS Console
-3. Scroll to the Layers section and click the _Add a layer_ button
-4. Choose the _Specify an ARN_ radio button
-5. Enter the Version ARN of the APM Java Agent Layer in the _Specify an ARN_ text input
-6. Click the _Add_ button
+That's it; After following the steps above, you're ready to go!
+Your Lambda function invocations should be traced from now on.
-Once the APM Java Agent Layer is in place, you'll need to configure some environment variables _in addition_ to the environment variables you already configured for the APM Lambda extension.
-Configure the following environment variables for the APM Java Agent Layer:
+Read on to learn more about the features and limitations of the Java APM Agent on AWS Lambda Functions.
-1. (required) `AWS_LAMBDA_EXEC_WRAPPER`: set this variable's value to `/opt/elastic-apm-handler`, so that Lambda starts the runtime with an attached APM Java agent.
-2. (recommended) <>: setting this may improve cold start times.
-3. (optional) Fine-tune the Java agent with any of the available <>.
+[float]
+[[aws-lambda-features-and-caveats]]
+=== Features and Caveats
-That's it, if you've done all of the above you are set to go!
-Your Lambda function invocations should be traced from now on.
+The AWS Lambda as a runtime behaves differently from conventional runtimes.
+While most APM and monitoring concepts apply to AWS Lambda, there are a few differences and limitations to be aware of.
[float]
[[aws-lambda-performance-monitoring]]
diff --git a/docs/supported-technologies.asciidoc b/docs/supported-technologies.asciidoc
index 7c3d0f4fcf..bcc1623825 100644
--- a/docs/supported-technologies.asciidoc
+++ b/docs/supported-technologies.asciidoc
@@ -15,6 +15,7 @@ This section lists all supported technologies.
* <>
* <>
* <>
+* <>
* <>
* <>
* <>
@@ -583,6 +584,39 @@ JBoss LogManager - 1.30.0
|===
+[float]
+[[supported-aws-lambda-runtimes]]
+=== AWS Lambda runtimes
+
+AWS Lambda provides multiple https://docs.aws.amazon.com/lambda/latest/dg/java-image.html[JVM base images]. Only those that support the `AWS_LAMBDA_EXEC_WRAPPER` environment variables are supported out of the box.
+
+Running with unsupported images is still possible but requires providing agent configuration through environment variables
+explicitly.
+
+// tag::aws-lambda-runtimes[]
+
+|===
+|Tags |Java Runtime |Operating System|Supported
+
+|11
+|Java 11 (Corretto)
+|Amazon Linux 2
+|yes
+
+|8.al2
+|Java 8 (Corretto)
+|Amazon Linux 2
+|yes
+
+|8
+|Java 8 (OpenJDK)
+|Amazon Linux 2018.03
+|no
+
+|===
+
+// end::aws-lambda-runtimes[]
+
[float]
[[supported-java-methods]]
=== Java method monitoring