Improved lambda getting started docs

docs/lambda/configure-lambda-widget.asciidoc

@@ -0,0 +1,99 @@
+++++
+<div class="tabs" data-tab-group="os">
+  <div role="tablist" aria-label="dependency">
+    <button role="tab"
+            aria-selected="true"
+            aria-controls="console-tab-lambda-python-config"
+            id="console-lambda-python-config">
+      AWS Web Console
+    </button>
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="cli-tab-lambda-python-config"
+            id="cli-lambda-python-config"
+            tabindex="-1">
+      AWS CLI
+    </button>
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="sam-tab-lambda-python-config"
+            id="sam-lambda-python-config"
+            tabindex="-1">
+      SAM
+    </button>
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="serverless-tab-lambda-python-config"
+            id="serverless-lambda-python-config"
+            tabindex="-1">
+      Serverless
+    </button>
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="terraform-tab-lambda-python-config"
+            id="terraform-lambda-python-config"
+            tabindex="-1">
+      Terraform
+    </button>
+  </div>
+  <div tabindex="0"
+      role="tabpanel"
+      id="console-tab-lambda-python-config"
+      name="lambda-tabpanel"
+      aria-labelledby="console-lambda-python-config">
+++++
+
+include::configure-lambda.asciidoc[tag=console-{layer-section-type}]
+
+++++
+  </div>
+  <div tabindex="0"
+      role="tabpanel"
+      id="cli-tab-lambda-python-config"
+      name="lambda-tabpanel"
+      aria-labelledby="cli-lambda-python-config"
+      hidden="">
+++++
+
+include::configure-lambda.asciidoc[tag=cli-{layer-section-type}]
+
+++++
+  </div>
+  <div tabindex="0"
+      role="tabpanel"
+      id="sam-tab-lambda-python-config"
+      name="lambda-tabpanel"
+      aria-labelledby="sam-lambda-python-config"
+      hidden="">
+++++
+
+include::configure-lambda.asciidoc[tag=sam-{layer-section-type}]
+
+++++
+  </div>
+  <div tabindex="0"
+      role="tabpanel"
+      id="serverless-tab-lambda-python-config"
+      name="lambda-tabpanel"
+      aria-labelledby="serverless-lambda-python-config"
+      hidden="">
+++++
+
+include::configure-lambda.asciidoc[tag=serverless-{layer-section-type}]
+
+++++
+  </div>
+  <div tabindex="0"
+      role="tabpanel"
+      id="terraform-tab-lambda-python-config"
+      name="lambda-tabpanel"
+      aria-labelledby="terraform-lambda-python-config"
+      hidden="">
+++++
+
+include::configure-lambda.asciidoc[tag=terraform-{layer-section-type}]
+
+++++
+  </div>
+</div>
+++++

docs/lambda/configure-lambda.asciidoc

@@ -0,0 +1,91 @@
+// tag::console-extension-only[]
+
+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]
+----
+ELASTIC_APM_LAMBDA_APM_SERVER = <YOUR-APM-SERVER-URL>     # this is your APM Server URL
+ELASTIC_APM_SECRET_TOKEN      = <YOUR-APM-SECRET-TOKEN>   # this is your APM secret token
+----
+
+--
+include::{apm-aws-lambda-root}/docs/images/images.asciidoc[tag=python-env-vars]
+--
+
+// end::console-extension-only[]
+
+// tag::cli-extension-only[]
+
+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={ELASTIC_APM_LAMBDA_APM_SERVER=<YOUR-APM-SERVER-URL>,ELASTIC_APM_SECRET_TOKEN=<YOUR-APM-SECRET-TOKEN>}"
+----
+
+// end::cli-extension-only[]
+
+// tag::sam-extension-only[]
+
+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:
+            ELASTIC_APM_LAMBDA_APM_SERVER: <YOUR-APM-SERVER-URL>
+            ELASTIC_APM_SECRET_TOKEN: <YOUR-APM-SECRET-TOKEN>
+...
+----
+
+// end::sam-extension-only[]
+
+// tag::serverless-extension-only[]
+
+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:
+      ELASTIC_APM_LAMBDA_APM_SERVER: <YOUR-APM-SERVER-URL>
+      ELASTIC_APM_SECRET_TOKEN: <YOUR-APM-SECRET-TOKEN>
+...
+----
+
+// end::serverless-extension-only[]
+
+// tag::terraform-extension-only[]
+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 = {
+      ELASTIC_APM_LAMBDA_APM_SERVER = "<YOUR-APM-SERVER-URL>"
+      ELASTIC_APM_SECRET_TOKEN      = "<YOUR-APM-SECRET-TOKEN>"
+    }
+  }
+}
+...
+----
+
+// end::terraform-extension-only[]

docs/serverless.asciidoc

@@ -1,15 +1,30 @@
 [[lambda-support]]
-=== AWS Lambda Support
-
-experimental::[]
+=== Monitoring AWS Lambda Python Functions
+:layer-section-type: extension-only
+:apm-aws-repo-dir: ./lambda
 
 Incorporating Elastic APM into your AWS Lambda functions is easy!
+Follow the steps below to setup Elastic APM for your AWS Lambda Python functions.
+
+[float]
+==== Prerequisites
+
+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.
+
+[float]
+==== Step 1: Setup the APM Lambda Extension
+
+include::{apm-aws-lambda-root}/docs/lambda-selector/lambda-attributes-selector.asciidoc[]
+
+Add the {apm-guide-ref}/aws-lambda-arch.html[APM Lambda Extension] as an https://docs.aws.amazon.com/lambda/latest/dg/invocation-layers.html[AWS Lambda Layer] to your AWS Lambda function.
+
+include::{apm-aws-lambda-root}/docs/lambda-selector/extension-arn-replacement.asciidoc[]
+include::{apm-aws-lambda-root}/docs/add-extension/add-extension-layer-widget.asciidoc[]
 
 [float]
-[[lambda-installation]]
-==== Installation
+==== Step 2: Setup the APM Python Agent
 
-First, you need to add `elastic-apm` as a dependency for your python function.
+You need to add `elastic-apm` as a dependency for your python function.
 Depending on your deployment strategy, this could be as easy as adding
 `elastic-apm` to your `requirements.txt` file, or installing it in the directory
 you plan to deploy using pip:
@@ -19,14 +34,6 @@ you plan to deploy using pip:
 $ pip install -t <target_dir> elastic-apm
 ----
 
-You should also add the
-https://github.com/elastic/apm-aws-lambda[Elastic AWS Lambda Extension layer]
-to your function.
-
-[float]
-[[lambda-setup]]
-==== Setup
-
 Once the library is included as a dependency in your function, you must
 import the `capture_serverless` decorator and apply it to your handler:
 
@@ -39,27 +46,20 @@ def handler(event, context):
     return {"statusCode": r.status_code, "body": "Success!"}
 ----
 
-The agent uses environment variables for <<configuration,configuration>>
+[float]
+==== Step 3: Configure APM on AWS Lambda
 
-[source]
-----
-ELASTIC_APM_LAMBDA_APM_SERVER=<apm-server url>
-ELASTIC_APM_SECRET_TOKEN=<apm-server token>
-ELASTIC_APM_SERVICE_NAME=my-awesome-service
-----
+The APM Lambda Extension and the APM Python agent are configured through environment variables on the AWS Lambda function.
 
-Note that the above configuration assumes you're using the Elastic Lambda
-Extension. The agent will automatically send data to the extension at `localhost`,
-and the extension will then send to the APM Server as specified with
-`ELASTIC_APM_LAMBDA_APM_SERVER`.
+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]
-[[lambda-usage]]
-==== Usage
+include::./lambda/configure-lambda-widget.asciidoc[]
 
-Once the agent is installed and working, spans will be captured for
+You can optionally <<configuration,fine-tune the Python agent>> or the {apm-guide-ref}/aws-lambda-config-options.html[configuration of the APM Lambda Extension].
+
+That's it; Once the agent is installed and working, spans will be captured for
 <<supported-technologies,supported technologies>>. You can also use
 <<api-capture-span,`capture_span`>> to capture custom spans, and
 you can retrieve the `Client` object for capturing exceptions/messages
 using <<api-get-client,`get_client`>>.
-