Skip to content
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

Jump to bottom

Update lambda docs for lambda layer + docker image #1826

Merged
merged 7 commits into from May 22, 2023
Merged

Update lambda docs for lambda layer + docker image #1826

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
1b6c702
Add missing azure functions link for set-up page
basepi May 5, 2023
2f2c535
Update lambda docs for lambda layer + docker image
basepi May 5, 2023
10a5ab7
Merge branch 'main' into lambda_docs
basepi May 10, 2023
58ef7a4
CHANGELOG
basepi May 10, 2023
261188d
Update docs/serverless-lambda.asciidoc
basepi May 11, 2023
f6b483e
replaced extension-only tags with 'with-agent' tags
AlexanderWert May 12, 2023
7d2c5a6
Merge branch 'main' into lambda_docs
basepi May 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
13 changes: 9 additions & 4 deletions docs/lambda/configure-lambda.asciidoc
View file
Open in desktop
Expand Up @@ -9,9 +9,10 @@ To configure APM through the AWS Management Console:

[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
ELASTIC_APM_SEND_STRATEGY = background <1>
AWS_LAMBDA_EXEC_WRAPPER = /opt/python/bin/elasticapm-lambda # use this exact fixed value
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
ELASTIC_APM_SEND_STRATEGY = background <1>
----

--
Expand All @@ -27,7 +28,7 @@ To configure APM through the AWS command line interface execute the following co
[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>,ELASTIC_APM_SEND_STRATEGY=background}" <1>
--environment "Variables={AWS_LAMBDA_EXEC_WRAPPER=/opt/python/bin/elasticapm-lambda,ELASTIC_APM_LAMBDA_APM_SERVER=<YOUR-APM-SERVER-URL>,ELASTIC_APM_SECRET_TOKEN=<YOUR-APM-SECRET-TOKEN>,ELASTIC_APM_SEND_STRATEGY=background}" <1>
----

// end::cli-extension-only[]
Expand All @@ -46,6 +47,7 @@ Resources:
...
Environment:
Variables:
AWS_LAMBDA_EXEC_WRAPPER: /opt/python/bin/elasticapm-lambda
ELASTIC_APM_LAMBDA_APM_SERVER: <YOUR-APM-SERVER-URL>
ELASTIC_APM_SECRET_TOKEN: <YOUR-APM-SECRET-TOKEN>
ELASTIC_APM_SEND_STRATEGY: background <1>
Expand All @@ -65,6 +67,7 @@ functions:
yourLambdaFunction:
...
environment:
AWS_LAMBDA_EXEC_WRAPPER: /opt/python/bin/elasticapm-lambda
ELASTIC_APM_LAMBDA_APM_SERVER: <YOUR-APM-SERVER-URL>
ELASTIC_APM_SECRET_TOKEN: <YOUR-APM-SECRET-TOKEN>
ELASTIC_APM_SEND_STRATEGY: background <1>
Expand All @@ -83,6 +86,7 @@ resource "aws_lambda_function" "your_lambda_function" {
...
environment {
variables = {
AWS_LAMBDA_EXEC_WRAPPER = /opt/python/bin/elasticapm-lambda
ELASTIC_APM_LAMBDA_APM_SERVER = "<YOUR-APM-SERVER-URL>"
ELASTIC_APM_SECRET_TOKEN = "<YOUR-APM-SECRET-TOKEN>"
ELASTIC_APM_SEND_STRATEGY = "background" <1>
Expand All @@ -100,6 +104,7 @@ You can use one of the other options (through AWS Web Console, AWS CLI, etc.) to

[source,bash]
----
AWS_LAMBDA_EXEC_WRAPPER = /opt/python/bin/elasticapm-lambda # use this exact fixed value
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
ELASTIC_APM_SEND_STRATEGY = background <1>
Expand Down
9 changes: 9 additions & 0 deletions docs/lambda/python-arn-replacement.asciidoc
View file
Open in desktop
@@ -0,0 +1,9 @@
++++
<script>
window.addEventListener("DOMContentLoaded", async () => {
addArnGenerator('agent', 'apm-agent-python', 'arn:aws:lambda:${region}:267093732750:layer:elastic-apm-python-${version}');
replaceAgentDockerImageParams('FROM docker.elastic.co/observability/apm-agent-python:latest AS python-agent',
'COPY --from=python-agent /opt/python/ /opt/python/');
});
</script>
++++
63 changes: 12 additions & 51 deletions docs/serverless.asciidoc → docs/serverless-lambda.asciidoc
View file
Open in desktop
Expand Up @@ -3,67 +3,27 @@
:layer-section-type: extension-only
basepi marked this conversation as resolved.
Show resolved Hide resolved
: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.
The Python APM Agent can be used with AWS Lambda to monitor the execution of your AWS Lambda 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: Set up the {apm-lambda-ext}
==== Step 1: Select the AWS Region and Architecture

include::{apm-aws-lambda-root}/docs/lambda-selector/lambda-attributes-selector.asciidoc[]

Add the {apm-lambda-ref}/aws-lambda-arch.html[{apm-lambda-ext}] 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]
==== Step 2: Set up the APM Python Agent

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:

[source,bash]
----
$ pip install -t <target_dir> elastic-apm
----

Note: Please use the latest version of the APM Python agent. A performance
issue was introduced in version 6.9.0 of the agent, and fixed in version 6.14.0.

Once the library is included as a dependency in your function, you must
import the `capture_serverless` decorator and apply it to your handler:

[source,python]
----
from elasticapm import capture_serverless

@capture_serverless
def handler(event, context):
return {"statusCode": r.status_code, "body": "Success!"}
----

Note: any database or connection pool setup should go inside of your handler,
otherwise the agent will not be able to instrument those objects and you may
see missing spans. Example:
==== Step 2: Add the APM Layers to your Lambda function

include::{apm-aws-lambda-root}/docs/lambda-selector/extension-arn-replacement.asciidoc[]
include::./lambda/python-arn-replacement.asciidoc[]

[source,python]
----
conn = None
Both the {apm-lambda-ref}/aws-lambda-arch.html[{apm-lambda-ext}] and the Python 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.

@capture_serverless
def handler(event, context):
global conn
if not conn:
conn = pymysql.connect(host=rds_host, user=name, passwd=password, db=db_name, connect_timeout=5)
----
include::{apm-aws-lambda-root}/docs/add-extension/add-extension-layer-widget.asciidoc[]

[float]
==== Step 3: Configure APM on AWS Lambda
Expand All @@ -80,8 +40,9 @@ include::./lambda/configure-lambda-widget.asciidoc[]

You can optionally <<configuration,fine-tune the Python agent>> or the {apm-lambda-ref}/aws-lambda-config-options.html[configuration of the {apm-lambda-ext}].

That's it; Once the agent is installed and working, spans will be captured for
That's it. After following the steps above, you're ready to go! Your Lambda
function invocations should be traced from now on. 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`>>.
<<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`>>.
3 changes: 2 additions & 1 deletion docs/set-up.asciidoc
View file
Open in desktop
Expand Up @@ -10,6 +10,7 @@ To get you off the ground, we’ve prepared guides for setting up the Agent with
* <<starlette-support,Starlette/FastAPI>>
* <<sanic-support,Sanic>>
* <<lambda-support,AWS Lambda>>
* <<azure-functions-support,Azure Functions>>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch!

* <<wrapper-support,Wrapper (Experimental)>>

For custom instrumentation, see <<instrumenting-custom-code, Instrumenting Custom Code>>.
Expand All @@ -26,7 +27,7 @@ include::./starlette.asciidoc[]

include::./sanic.asciidoc[]

include::./serverless.asciidoc[]
include::./serverless-lambda.asciidoc[]

include::./serverless-azure-functions.asciidoc[]

Expand Down