Skip to content

Update docs #87

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Dec 2, 2021
Merged

Update docs #87

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4ba57a7
feat: add overview section with main steps
bmorelli25 Nov 30, 2021
eb44dd5
docs: update for doc build
bmorelli25 Nov 30, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 54 additions & 3 deletions docs/aws-lambda-extension.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,11 @@
[[aws-lambda-extension]]
= AWS Lambda Extension (Experimental)

experimental::[]

Elastic's APM Agents instrument AWS Lambda functions via an AWS Lambda Extension.

[discrete]
[[aws-lambda-arch]]
== Extension Architecture

Expand All @@ -12,6 +15,8 @@ image:images/data-flow.png[image showing data flow from lambda function, to exte

By using a custom-built AWS Lambda Extension, Elastic APM Agents can send data to a locally running Lambda Extension process, and that process will forward data on to APM Server. The Lambda Extension ensures that any latency between the Lambda function and the AWS Server instance will not cause latency in the Lambda function/Service itself.

[discrete]
[[aws-lambda-instrumenting]]
== Instrumenting a Lambda Function

The rest of this guide contains instructions for instrumenting a Lambda function. There are two high level steps to instrumenting an AWS Lambda function.
Expand All @@ -21,6 +26,7 @@ The rest of this guide contains instructions for instrumenting a Lambda function

We'll start with installing the Lambda extension.

[discrete]
[[aws-lambda-install]]
== Installing the Lambda Extension

Expand Down Expand Up @@ -63,6 +69,8 @@ The `elastic-lambda.js` command assumes you have a `install.yaml` file configure
./elastic-lambda.js install
----

[discrete]
[[aws-lambda-configuring]]
== Configuring the Installer

A fully configured `install.yaml` might look like the following
Expand All @@ -83,47 +91,68 @@ install:

The meaning of each `install.yaml` configuration field is as follows.

[discrete]
[[aws-lambda-layer_name]]
=== `layer_name`

This is the name the compiler will use for your AWS Layer. The default, `apm-lambda-extension`, should work for most scenarios.

[discrete]
[[aws-lambda-function_name]]
=== `function_name`

The name of your Lambda function. The installer will use this to configure the correct Lambda function. This must be the name of a function that already exists.

[discrete]
[[aws-lambda-lambda_env]]
=== `lambda_env`

The installer will use the key/value pairs in this section of the configuration file to add environment variables to your Lambda function. The provided variables are those required to make the extension work correctly.

[discrete]
[[aws-lambda-log_level]]
==== `ELASTIC_APM_LOG_LEVEL`

The log level for the APM Agent. Consult your https://www.elastic.co/guide/en/apm/agent/index.html[APM Agent's documentation] for more information.

[discrete]
[[aws-lambda-secret_token]]
==== `ELASTIC_APM_SECRET_TOKEN`

The APM secret token. The extension will use this when communicating with APM Server.

[discrete]
[[aws-lambda-api_key]]
==== `ELASTIC_APM_API_KEY`

An alternative authentication method to the secret token. The extension will use this when communicating with APM Server.

[discrete]
[[aws-lambda-server_url]]
==== `ELASTIC_APM_SERVER_URL`

Your APM Server URL. This is the final destination for your data.

[discrete]
[[aws-lambda-service_name]]
==== `ELASTIC_APM_SERVICE_NAME`

The configured name of your application or service. The APM Agent will use this value when reporting data to APM Server.
If unset, the APM Agent will automatically set the value based on `AWS_LAMBDA_FUNCTION_NAME` or `context.functionName`.

[discrete]
[[aws-lambda-timeout_seconds]]
==== `ELASTIC_APM_DATA_RECEIVER_TIMEOUT_SECONDS`

The timeout value, in seconds, for the Lambda Extension's server.

[discrete]
[[aws-lambda-handler]]
== Configuring the Agent and Lambda Function handler

Once you've installed the extension, there's one last step to take. You'll need to wrap the Lambda function handler.

[discrete]
[[aws-lambda-nodejs]]
=== Node.js

Expand All @@ -141,6 +170,7 @@ exports.handler = apm.lambda(async function handler (event, context) {
})
----

[discrete]
[[aws-lambda-python]]
=== Python

Expand All @@ -154,6 +184,8 @@ def handler(event, context):
return {"statusCode": r.status_code, "body": "Success!"}
----

[discrete]
[[aws-lambda-manual-instrumentation]]
== Manual Installation

It's possible to install and configure the extension manually. In order to do so, you'll need to
Expand All @@ -163,22 +195,28 @@ It's possible to install and configure the extension manually. In order to do s
3. Configure your function to use that layer
4. Configure your function's environment variables correctly

[discrete]
[[aws-lambda-download-released]]
=== Download a Released Extension

The extension is released as a ZIP archive via https://github.com/elastic/apm-aws-lambda/releases[the GitHub releases page]. To download an archive, simply navigate to the latest version, and choose either the AMD64 or ARM64 release (depending on which architecture your Lambda function uses).

image:images/assets.png[image of assets tab in releases]

[discrete]
[[aws-lambda-publish-layer]]
=== Publish a Lambda layer

Next, you'll want to take that release ZIP file and publish it https://docs.aws.amazon.com/lambda/latest/dg/invocation-layers.html?icmpid=docs_lambda_help[as a Lambda layer]. A Lambda layer is a zip file archive that contains additional code or files for your Lambda function.

To do this, navigate the the Layers section of the AWS console, click the _Create layer_ button, and follow the prompts to upload the ZIP archive as a layer.
To do this, navigate to the Layers section of the AWS console, click the _Create layer_ button, and follow the prompts to upload the ZIP archive as a layer.

image:images/layers.png[image of layers section in the Amazon Console]

After publishing a layer, you'll receive a Version ARN. This ARN is the layer's unique identifier.

[discrete]
[[aws-lambda-configure-layer]]
=== Configure the Layer

Once you've published a layer, you'll need to configure your function to use that layer. To add a layer
Expand All @@ -189,6 +227,8 @@ Once you've published a layer, you'll need to configure your function to use tha
4. Enter the Version ARN of your layer in the _Specify an ARN_ text input
5. Click the _Add_ button

[discrete]
[[aws-lambda-configure-env]]
=== Configure your Environment Variables

Finally, once the layer's in place you'll need to configure a few environmental variables. To configure variables
Expand All @@ -198,25 +238,36 @@ Finally, once the layer's in place you'll need to configure a few environmental
3. Click on _Environment variables_
4. Add the necessary variables.

[discrete]
[[aws-lambda-variables]]
=== The Necessary Variables

[discrete]
[[aws-lambda-central_config]]
==== `ELASTIC_APM_CENTRAL_CONFIG`

The `ELASTIC_APM_CENTRAL_CONFIG` value _must_ be set to `false`. Central configuration does not work in a Lambda environment, and having this on will negatively impact the performance of your Lambda function.

[discrete]
[[aws-lambda-cloud_provider]]
==== `ELASTIC_APM_CLOUD_PROVIDER`

The `ELASTIC_APM_CLOUD_PROVIDER` value _must_ be set to `none`. Amazon's Cloud Metadata APIs are not available in an AWS Lambda environment, and attempting to fetch this data will negatively impact the performance of your Lambda function.

[discrete]
[[aws-lambda-lambda_apm_server]]
==== `ELASTIC_APM_LAMBDA_APM_SERVER`

The `ELASTIC_APM_LAMBDA_APM_SERVER` controls where the Lambda extension will ship data. This should be the URL of the final APM Server destination for your telemetry.

[discrete]
[[aws-lambda-apm_secret_token]]
==== `ELASTIC_APM_SECRET_TOKEN` or `ELASTIC_APM_API_KEY`

Either `ELASTIC_APM_API_KEY` or `ELASTIC_APM_SECRET_TOKEN` needs to be set. This controls the authentication method that extension uses when sending data to the URL configured via `ELASTIC_APM_LAMBDA_APM_SERVER`.
Either `ELASTIC_APM_API_KEY` or `ELASTIC_APM_SECRET_TOKEN` needs to be set. This controls the authentication method that the extension uses when sending data to the URL configured via `ELASTIC_APM_LAMBDA_APM_SERVER`.

[discrete]
[[aws-lambda-apm_server_url]]
==== `ELASTIC_APM_SERVER_URL`

This _must_ be configured to the value `http://localhost:8200`. This configuration field controls where your APM Agent sends data. The extension listens for data on `localhost:8200`.