Skip to content

Commit b864a1b

Browse files
bmorelli25bmorelli25
authored
docs: duplicate file (#160)
1 parent 8f5b893 commit b864a1b

File tree

1 file changed

+152
-0
lines changed

1 file changed

+152
-0
lines changed

‎docs/monitoring-aws-lambda.asciidoc‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
[[aws-lambda-extension]]
2+
= AWS Lambda Extension (Experimental)
3+
4+
experimental::[]
5+
6+
Elastic's APM Agents instrument AWS Lambda functions and dispatch APM data via an AWS Lambda Extension.
7+
8+
[discrete]
9+
[[aws-lambda-arch]]
10+
== Extension Architecture
11+
12+
Normally, during the execution of a Lambda function, there's only a single language process running in the AWS Lambda execution environment. However, with an AWS Lambda Extension, Lambda users can run a _second_ process alongside their main service/application process.
13+
14+
image:images/data-flow.png[image showing data flow from lambda function, to extension, to APM Server]
15+
16+
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.
17+
18+
[discrete]
19+
[[aws-lambda-instrumenting]]
20+
== Instrumenting a Lambda Function
21+
22+
The rest of this guide contains instructions for instrumenting a Lambda function. There are two high level steps to instrumenting an AWS Lambda function.
23+
24+
1. <<aws-lambda-configure-layer>>
25+
2. <<aws-lambda-handler>>
26+
27+
[discrete]
28+
[[aws-lambda-configure-layer]]
29+
=== Configuring the APM Lambda Extension Layer
30+
31+
First, you'll need to https://github.com/elastic/apm-aws-lambda/releases[pick the right ARN from the extension release table] for your AWS Lambda function. The ARN has the pattern `arn:aws:lambda:<AWS_REGION_KEY>:267093732750:layer:elastic-apm-extension-<APM_EXTENSION_VERSION>-<ARCHITECTURE_KEY>:<LAYER_VERSION>` and depends on:
32+
33+
* The AWS region your Lambda function runs in. The APM Lambda Extension layer needs to be in the same region as your Lambda function.
34+
* The architecture (_x86_64_ or _arm64_) used for your Lambda function.
35+
* The version of the APM Lambda Extension you would like to use.
36+
37+
You'll then need to configure your function to use that layer. To add a layer
38+
39+
1. Navigate to your function in the AWS Console
40+
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]
41+
3. Choose the _Specify an ARN_ radio button
42+
4. Enter the Version ARN of the APM Lambda Extension layer in the _Specify an ARN_ text input
43+
5. Click the _Add_ button
44+
45+
[discrete]
46+
[[aws-lambda-env-vars]]
47+
==== Configure Environment Variables
48+
49+
Finally, once the layer's in place you'll need to configure a few environment variables. To configure variables
50+
51+
1. Navigate to your function in the AWS Console
52+
2. Click on the _Configuration_ tab
53+
3. Click on _Environment variables_
54+
4. Add the necessary variables.
55+
56+
The following environment variables are relevant for instrumenting a Lambda function:
57+
58+
* (required) `ELASTIC_APM_LAMBDA_APM_SERVER`: +
59+
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.
60+
61+
* (required) `ELASTIC_APM_SECRET_TOKEN` or `ELASTIC_APM_API_KEY`: +
62+
One of these 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`.
63+
64+
* (optional) `ELASTIC_APM_SERVICE_NAME`: +
65+
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 the Lambda function name. Use this config option if you want to group multiple Lambda functions under a single service entity in APM.
66+
67+
* (optional) `ELASTIC_APM_DATA_RECEIVER_TIMEOUT_SECONDS`: +
68+
The timeout value, in seconds, for the Lambda Extension's server receiving data from the agent. The _default_ is `15`.
69+
70+
* (optional) `ELASTIC_APM_SEND_STRATEGY`: +
71+
Whether to synchronously flush APM agent data from the extension to the APM server at the end of the function invocation.
72+
The two accepted values are `background` and `syncflush`. The _default_ is `syncflush`.
73+
** The `background` strategy indicates that the extension will not flush when it receives a signal that the function invocation
74+
has completed. It will instead send any remaining buffered data on the next function invocation. The result is that, if the
75+
function is not subsequently invoked for that Lambda environment, the buffered data will be lost. However, for lambda functions
76+
that have a steadily frequent load pattern the extension could delay sending the data to the APM server to the next lambda
77+
request and do the sending in parallel to the processing of that next request. This potentially would improve both the lambda
78+
function response time and its throughput.
79+
** The other value, `syncflush` will synchronously flush all remaining buffered APM agent data to the APM server when the
80+
extension receives a signal that the function invocation has completed. This strategy blocks the lambda function from receiving
81+
the next request until the extension has flushed all the data. This has a negative effect on the throughput of the function,
82+
though it ensures that all APM data is sent to the APM server.
83+
84+
An example configuration of the APM Lambda Extension might look like the following
85+
86+
[source,bash]
87+
----
88+
ELASTIC_APM_LAMBDA_APM_SERVER=https://your-apm-server-url:443 # (required) this is your APM Server URL
89+
ELASTIC_APM_SECRET_TOKEN=shhhhhhitsasecret # (required) this is your APM Server's secret token
90+
ELASTIC_APM_SERVICE_NAME=yourApmServiceName # (optional) use this to group multiple lambda functions
91+
ELASTIC_APM_DATA_RECEIVER_TIMEOUT_SECONDS=20 # (optional) wait 20s to receive data from the APM agent
92+
ELASTIC_APM_SEND_STRATEGY=background # (optional) this is the default strategy
93+
----
94+
95+
For a _minimal configuration_ you need to specify the `ELASTIC_APM_LAMBDA_APM_SERVER` and the `ELASTIC_APM_SECRET_TOKEN` config options.
96+
97+
[discrete]
98+
[[aws-lambda-handler]]
99+
=== Configuring the Agent and Lambda Function handler
100+
101+
After the extension has been installed, install the relevant language agent and wrap the Lambda function handler.
102+
103+
104+
[discrete]
105+
[[aws-lambda-nodejs]]
106+
==== Node.js
107+
108+
To install the Node.js agent in Lambda you'll use a second layer. You'll need to https://github.com/elastic/apm-agent-nodejs/releases[pick the right ARN from the agent release table]. The ARN has the pattern `arn:aws:lambda:<AWS_REGION_KEY>:267093732750:layer:elastic-apm-node-ver-<APM_EXTENSION_VERSION>:<LAYER_VERSION>` and depends on:
109+
110+
* The AWS region your Lambda function runs in. The APM Lambda Extension layer needs to be in the same region as your Lambda function.
111+
* The version of the APM Lambda Extension you would like to use.
112+
113+
You'll then need to configure your function to use that layer. To add a layer
114+
115+
1. Navigate to your function in the AWS Console
116+
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]
117+
3. Choose the _Specify an ARN_ radio button
118+
4. Enter the Version ARN of the APM Lambda Extension layer in the _Specify an ARN_ text input
119+
5. Click the _Add_ button
120+
121+
Finally, to have the Node.js agent automatically wrap your Lambda function handler, add the following environment variable.
122+
123+
[source]
124+
---
125+
NODE_OPTIONS=-r elastic-apm-node/start
126+
---
127+
128+
See the {apm-node-ref}/lambda.html[Node.js agent setup guide] for detailed instructions on setting up the Node.js agent for AWS Lambda.
129+
130+
[discrete]
131+
[[aws-lambda-python]]
132+
==== Python
133+
134+
In Python, you wrap a Lambda function handler using the following syntax.
135+
136+
[source,python]
137+
----
138+
from elasticapm import capture_serverless
139+
@capture_serverless()
140+
def handler(event, context):
141+
return {"statusCode": r.status_code, "body": "Success!"}
142+
----
143+
144+
See the {apm-py-ref}/lambda-support.html[Python agent setup guide] for detailed instructions on setting up the Python agent for AWS Lambda.
145+
146+
[discrete]
147+
[[aws-lambda-java]]
148+
==== Java
149+
150+
Like the extension, the Elastic APM Java agent is installed as a Lambda layer.
151+
152+
See the {apm-java-ref}/aws-lambda.html[Java agent setup guide] for detailed instructions on setting up the Java agent for AWS Lambda.

0 commit comments

Comments
 (0)