Skip to content

Commit 6201762

Browse files
colleenmcginniscolleenmcginnis
committed
add migrated files
1 parent 4c8c939 commit 6201762

File tree

11 files changed

+1109
-0
lines changed

11 files changed

+1109
-0
lines changed

‎docs/docset.yml‎

Lines changed: 490 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/images/architecture-white.png‎

167 KB
Loading

‎docs/images/secrets-manager.png‎

197 KB
Loading

‎docs/reference/aws-lambda-config-options.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/apm/lambda/current/aws-lambda-config-options.html
4+
---
5+
6+
# Configuration options [aws-lambda-config-options]
7+
8+
The recommended way of configuring the {{apm-lambda-ext}} and the APM agents on AWS Lambda is through the Lambda function’s environment variables.
9+
10+
The configuration options for the APM agents are documented in the corresponding language agents:
11+
12+
* [Configuration options - Node.js APM agent](apm-agent-nodejs://docs/reference/configuration.md)
13+
* [Configuration options - Python APM agent](apm-agent-php://docs/reference/configuration.md)
14+
* [Configuration options - Java APM agent](apm-agent-java://docs/reference/configuration.md)
15+
16+
::::{note}
17+
Some APM agent configuration options don’t make sense when the APM agent is running in a Lambda environment. For example, instead of using the Python APM agent configuration variable, `verify_server_cert`, you must use the `ELASTIC_APM_LAMBDA_VERIFY_SERVER_CERT` variable described below.
18+
::::
19+
20+
21+
::::{note}
22+
APM Central configuration is not supported when using the Elastic APM AWS Lambda extension
23+
::::
24+
25+
26+
27+
## Relevant configuration options [aws-lambda-config-relevant]
28+
29+
A list of relevant configuration options for the {{apm-lambda-ext}} is below.
30+
31+
32+
### `ELASTIC_APM_LAMBDA_APM_SERVER` [aws-lambda-extension]
33+
34+
This required config option controls where the {{apm-lambda-ext}} will ship data. This should be the URL of the final APM Server destination for your telemetry.
35+
36+
37+
### `ELASTIC_APM_LAMBDA_AGENT_DATA_BUFFER_SIZE` [_elastic_apm_lambda_agent_data_buffer_size]
38+
39+
The size of the buffer that stores APM agent data to be forwarded to the APM server. The *default* is `100`.
40+
41+
42+
### `ELASTIC_APM_SECRET_TOKEN` or `ELASTIC_APM_API_KEY` [aws-lambda-config-authentication-keys]
43+
44+
One of these (or, alternatively, the corresponding settings for the AWS Secrets Manager IDs) needs to be set as the authentication method that the {{apm-lambda-ext}} uses when sending data to the URL configured via `ELASTIC_APM_LAMBDA_APM_SERVER`. Alternatively, you can store your APM Server credentials [using the AWS Secrets Manager](/reference/aws-lambda-secrets-manager.md) and use the [`ELASTIC_APM_SECRETS_MANAGER_SECRET_TOKEN_ID` or `ELASTIC_APM_SECRETS_MANAGER_API_KEY_ID`](#aws-lambda-config-secrets-manager-options) config options, instead. Sending data to the APM Server if none of these options is set is possible, but your APM agent must be allowed to send data to your APM server in [anonymous mode](docs-content://solutions/observability/apps/configure-anonymous-authentication.md).
45+
46+
47+
### `ELASTIC_APM_SECRETS_MANAGER_SECRET_TOKEN_ID` or `ELASTIC_APM_SECRETS_MANAGER_API_KEY_ID` [aws-lambda-config-secrets-manager-options]
48+
49+
Instead of specifying the [`ELASTIC_APM_SECRET_TOKEN` or `ELASTIC_APM_API_KEY`](#aws-lambda-config-authentication-keys) as plain text in your Lambda environment variables, you can [use the AWS Secrets Manager](/reference/aws-lambda-secrets-manager.md) to securely store your APM authetication keys. The `ELASTIC_APM_SECRETS_MANAGER_API_KEY_ID` or `ELASTIC_APM_SECRETS_MANAGER_SECRET_TOKEN_ID` config options allow you to specify the Secrets Manager’s secret id of the stored APM API key or APM secret token, respectively, to be used by the {{apm-lambda-ext}} for authentication.
50+
51+
`ELASTIC_APM_SECRETS_MANAGER_SECRET_TOKEN_ID` takes precedence over [`ELASTIC_APM_SECRET_TOKEN`](#aws-lambda-config-authentication-keys), and `ELASTIC_APM_SECRETS_MANAGER_API_KEY_ID` over [`ELASTIC_APM_API_KEY`](#aws-lambda-config-authentication-keys), respectively.
52+
53+
54+
### `ELASTIC_APM_SERVICE_NAME` [_elastic_apm_service_name]
55+
56+
The configured name of your application or service. The APM agent will use this value when reporting data to the 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.
57+
58+
59+
### `ELASTIC_APM_DATA_RECEIVER_TIMEOUT` [aws-lambda-config-data-receiver-timeout]
60+
61+
Added in: v1.2.0. Replaces `ELASTIC_APM_DATA_RECEIVER_TIMEOUT_SECONDS`.
62+
63+
The {{apm-lambda-ext}}'s timeout value, for receiving data from the APM agent. The *default* is `15s`.
64+
65+
66+
### `ELASTIC_APM_DATA_RECEIVER_SERVER_PORT` [_elastic_apm_data_receiver_server_port]
67+
68+
The port on which the {{apm-lambda-ext}} listens to receive data from the APM agent. The *default* is `8200`.
69+
70+
71+
### `ELASTIC_APM_DATA_FORWARDER_TIMEOUT` [aws-lambda-config-data-forwarder-timeout]
72+
73+
Added in: v1.2.0. Replaces `ELASTIC_APM_DATA_FORWARDER_TIMEOUT_SECONDS`.
74+
75+
The timeout value, for the {{apm-lambda-ext}}'s HTTP client sending data to the APM Server. The *default* is `3s`. If the extension’s attempt to send APM data during this time interval is not successful, the extension queues back the data. Further attempts at sending the data are governed by an exponential backoff algorithm: data will be sent after a increasingly large grace period of 0, then circa 1, 4, 9, 16, 25 and 36 seconds, provided that the Lambda function execution is ongoing.
76+
77+
78+
### `ELASTIC_APM_SEND_STRATEGY` [_elastic_apm_send_strategy]
79+
80+
Whether to synchronously flush APM agent data from the {{apm-lambda-ext}} to the APM Server at the end of the function invocation. The two accepted values are `background` and `syncflush`. The *default* is `syncflush`.
81+
82+
* The `background` strategy indicates that the {{apm-lambda-ext}} will not flush when it receives a signal that the function invocation has completed. It will instead send any remaining buffered data on the next function invocation. The result is that, if the function is not subsequently invoked for that Lambda environment, the buffered data will be lost. However, for lambda functions that have a steadily frequent load pattern the extension could delay sending the data to the APM Server to the next lambda request and do the sending in parallel to the processing of that next request. This potentially would improve both the lambda function response time and its throughput.
83+
* The other value, `syncflush` will synchronously flush all remaining buffered APM agent data to the APM Server when the extension receives a signal that the function invocation has completed. This strategy blocks the lambda function from receiving the next request until the extension has flushed all the data. This has a negative effect on the throughput of the function, though it ensures that all APM data is sent to the APM server.
84+
85+
86+
### `ELASTIC_APM_LOG_LEVEL` [_elastic_apm_log_level]
87+
88+
The logging level to be used by both the APM Agent and the {{apm-lambda-ext}}. Supported values are `trace`, `debug`, `info`, `warning`, `error`, `critical` and `off`.
89+
90+
91+
### `ELASTIC_APM_LAMBDA_CAPTURE_LOGS` [_elastic_apm_lambda_capture_logs]
92+
93+
[preview] Starting in Elastic Stack version 8.5.0, the Elastic APM lambda extension supports the collection of log events by default. Log events can be viewed in {{kib}} in the APM UI. Disable log collection by setting this to `false`.
94+
95+
96+
### `ELASTIC_APM_LAMBDA_VERIFY_SERVER_CERT` [_elastic_apm_lambda_verify_server_cert]
97+
98+
Added in: v1.3.0.
99+
100+
Whether to enable {{apm-lambda-ext}} to verify APM Server’s certificate chain and host name.
101+
102+
103+
### `ELASTIC_APM_LAMBDA_SERVER_CA_CERT_PEM` [_elastic_apm_lambda_server_ca_cert_pem]
104+
105+
Added in: v1.3.0.
106+
107+
The certificate passed as environment variable. To be used to verify APM Server’s certificate chain if verify server certificate is enabled.
108+
109+
110+
### `ELASTIC_APM_SERVER_CA_CERT_FILE` [_elastic_apm_server_ca_cert_file]
111+
112+
Added in: v1.3.0.
113+
114+
The certificate passed as a file name available to the extension. To be used to verify APM Server’s certificate chain if verify server certificate is enabled.
115+
116+
117+
### `ELASTIC_APM_SERVER_CA_CERT_ACM_ID` [_elastic_apm_server_ca_cert_acm_id]
118+
119+
Added in: v1.3.0.
120+
121+
The ARN for Amazon-issued certificate. To be used to verify APM Server’s certificate chain if verify server certificate is enabled.
122+
123+
::::{note}
124+
You may see errors similar to the following in {{stack}} versions less than 8.5:
125+
126+
```text
127+
client error: response status code: 400
128+
message: log: did not recognize object type
129+
```
130+
131+
Users on older versions should disable log collection by setting `ELASTIC_APM_LAMBDA_CAPTURE_LOGS` to `false`.
132+
133+
::::
134+
135+
136+
137+
## Deprecated options [aws-lambda-config-deprecated]
138+
139+
140+
### `ELASTIC_APM_DATA_RECEIVER_TIMEOUT_SECONDS` [aws-lambda-config-data-receiver-timeout-seconds]
141+
142+
Deprecated in: v1.2.0. Use [`ELASTIC_APM_DATA_RECEIVER_TIMEOUT`](#aws-lambda-config-data-receiver-timeout) instead.
143+
144+
The {{apm-lambda-ext}}'s timeout value, in seconds, for receiving data from the APM agent. The *default* is `15`.
145+
146+
147+
### `ELASTIC_APM_DATA_FORWARDER_TIMEOUT_SECONDS` [aws-lambda-config-data-forwarder-timeout-seconds]
148+
149+
Deprecated in: v1.2.0. Use [`ELASTIC_APM_DATA_FORWARDER_TIMEOUT`](#aws-lambda-config-data-forwarder-timeout) instead.
150+
151+
The timeout value, in seconds, for the {{apm-lambda-ext}}'s HTTP client sending data to the APM Server. The *default* is `3`. If the extension’s attempt to send APM data during this time interval is not successful, the extension queues back the data. Further attempts at sending the data are governed by an exponential backoff algorithm: data will be sent after a increasingly large grace period of 0, then circa 1, 4, 9, 16, 25 and 36 seconds, provided that the Lambda function execution is ongoing.
152+

‎docs/reference/aws-lambda-overhead.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/apm/lambda/current/aws-lambda-overhead.html
4+
---
5+
6+
# Performance impact and overhead [aws-lambda-overhead]
7+
8+
As described in [*APM Architecture for AWS Lambda*](/reference/index.md), using Elastic APM with AWS Lambda requires adding both the Elastic APM AWS Lambda extension and a corresponding Elastic APM agent to the Lambda runtime. These components may introduce a small overhead on the size of your function’s deployment package as well as the execution duration of your function’s invocations.
9+
10+
11+
## Impact on the deployment package size [_impact_on_the_deployment_package_size]
12+
13+
These components contribute a little to the uncompressed deployment package size of your Lambda function. Overall, the impact of using Elastic APM on the uncompressed deployment package size of your Lambda function is less than 30MB.
14+
15+
16+
## Performance impact [_performance_impact]
17+
18+
An advantage of the Elastic APM AWS Lambda extension architecture is that APM data dispatching is decoupled from your function’s request processing. The Elastic APM AWS Lambda extension flushes APM data to the Elastic backend *after* your function responds to the client’s request. Thus, it does not affect the latency of the client’s request. However, the extension’s flushing of APM data contributes to the overall execution time of the function invocation. The [`ELASTIC_APM_DATA_FORWARDER_TIMEOUT`](/reference/aws-lambda-config-options.md#aws-lambda-config-data-forwarder-timeout) config option with the related *exponential backoff algorithm* limits and allows to control the impact the extension may have on the function’s overall execution time.
19+
20+
When your function experiences a cold start, the Elastic APM AWS Lambda extension needs to be initialized and, thus, slightly increases the cold start duration (in the range of tens of milliseconds) of your function.
21+
22+
APM agents enrich your application’s code with measurement code that collects APM data. This measurement code introduces a small performance overhead to your application, which is usually in a negligible range. The same is true with Lambda functions. The concrete performance overhead introduced by APM agents highly depends on the configuration of the agent and on the characteristics of your function’s code. The following agent-specific documentation pages provide insights and instructions on tuning the performance the APM agents:
23+
24+
* [Performance Tuning - Node.js](apm-agent-nodejs://docs/reference/performance-tuning.md)
25+
* [Performance Tuning - Python](apm-agent-python://docs/reference/performance-tuning.md)
26+
* [Performance Tuning - Java](apm-agent-java://docs/reference/overhead-performance-tuning.md)
27+
28+
Similar to the Elastic APM AWS Lambda extension, APM agents are initialized at cold start time. As a consequence, the APM agent’s overhead will be higher for cold starts as compared to their overhead on *warm* invocations. This effect is especially relevant for the Java APM agent on AWS Lambda. Learn more about corresponding tuning options in the [Java Agent’s AWS Lambda documentation](apm-agent-java://docs/reference/aws-lambda.md#aws-lambda-caveats).
29+

0 commit comments

Comments
 (0)